[Submission] Durable Wordle

[MasonEgger]

Project link

https://github.com/temporal-community/durable-wordle

Language

Python

Short description (max 256 chars)

Wordle where each game is a Temporal Workflow, not a database row. Crash the server mid-game and your progress survives. A small, complete app demoing durable execution, Updates, Queries, and Activities, fully playable from the Temporal CLI or a web UI.

Long Description

Durable Wordle is the word game you already know, rebuilt so that each game session is a Temporal Workflow instead of a row in a database. There is no database at all. The Workflow's event history is the game state.

Kill the worker mid-guess and restart it, and Temporal replays the history, rebuilds your exact board, and finishes the guess that was in flight. Nothing lost, and you didn't write a single line of save-and-restore code.

How It's Built

It's a small, complete, readable app that maps Wordle mechanics directly onto the core Temporal building blocks, so it works as both a teaching reference and a "show, don't tell" demo:

• Start Workflow: each game session starts a Workflow; a deterministic Workflow ID reconnects a returning player.
• Updates: make_guess mutates state and returns feedback, with a synchronous validator that rejects malformed guesses before anything is written to history.
• Queries: get_game_state returns the board, read-only, any time.
• Activities: word selection, real dictionary-API word validation (with Temporal retries), and green/yellow/gray scoring, each visible in the event history.
• Durable Execution: the worker holds state in memory; a restart replays history to rebuild it with zero data loss.

The Workflow is the whole game

All game logic lives in the Workflow, never in the API layer. You can play a complete game from the command line with temporal workflow start / update / query, which makes it a great way to show what's actually happening underneath. Two modes ship: a daily word (deterministic via workflow.now()) and a random word (via workflow.random()), both replay-safe.

Stack

Temporal Python SDK, FastAPI, and Jinja2 on the backend; HTMX and Tailwind on the frontend. uv for packaging, just for tasks, and a Docker Compose setup that brings up the Temporal dev server, worker, and web app with one command.

Great for learning durable execution and the Python SDK by reading one complete example, or for running a quick booth or conference demo that lets someone feel why durability matters.

Author(s)

@MasonEgger - Temporal

[github-actions]

Hi, I'm ZiggyBot! 🤖 Here's my pre-evaluation of this submission:

---

Criterion	Assessment
Useful to Temporal users	✅ Yes — An excellent teaching tool that maps familiar Wordle mechanics directly onto core Temporal primitives (Workflows, Updates, Queries, Activities), making abstract concepts tangible and playable.
Benefits clearly explained	✅ Yes — The README includes a clear concept-to-implementation table, architecture diagram, and explicit explanations of how each Temporal feature is used and why durability matters.
OSI Approved License	⚠️ Unclear — GitHub did not detect a license file; the repository needs an explicit LICENSE file with an OSI-approved license.
README with working instructions	✅ Yes — Comprehensive setup instructions for both local development (three terminals) and Docker Compose, plus complete CLI-based gameplay examples and configuration documentation.

Overall: Needs review ⚠️

Notes:

• This is a delightfully well-crafted educational project! The "show, don't tell" approach of mapping a game everyone knows onto Temporal primitives is genuinely clever for demos and learning.
• The code is clean, readable, and demonstrates excellent practices like Update validators, deterministic randomness via workflow.random(), and proper use of workflow.now() for replay-safe time handling.
• The ability to play entirely via temporal workflow update/query commands is a fantastic way to demystify what's happening under the hood.
• The only blocking issue is the missing license file — this is a quick fix but essential for Code Exchange inclusion.
• Nice touch including both daily (deterministic) and random modes to demonstrate different replay-safe patterns!

Suggested questions for submitter:

• Could you add an OSI-approved license file (MIT is recommended) to the repository root?
• Any plans to add a "crash demo" script that kills and restarts the worker mid-guess to really showcase durability in action?

Teaching moment:

The Update handler with a synchronous validator is a standout pattern here. The make_guess Update uses a validator that rejects malformed guesses (wrong length, non-alphabetic, already-completed games) before anything touches the event history. This is exactly how Updates should be used: validate first to keep your history clean, then mutate state and return feedback atomically. It's a perfect example of why Updates are preferable to Signals when you need synchronous validation and response.
View in source ↗

---

---

ZiggyBot is an AI pre-screener based on Temporal's community mascot Ziggy. Final decisions are made by the community team.

Reviewer: Check the box below to generate a Contentful-ready long description for this submission.

• Generate long description if needed

[MasonEgger]

I added MIT license, so we should be good there.