Design Case Studies · Lesson 16

Design: Chess / Turn-based Game API

A chess API looks deceptively simple — two players, alternate turns, finite board. The hard parts are invisible: preventing a crafty client from submitting two moves in a row, keeping a spectating crowd in sync with the live board at sub-second latency, and ensuring a disconnect mid-game doesn't corrupt time controls. This lesson designs the whole system from requirements through latency budget.

1 — Requirements

Capture what the system must do before deciding how to build it. Clarity here prevents scope creep and surfaces hidden constraints.

Functional requirements

• Create a game: one player creates a game (choosing time control, variant), and a second player joins or is paired via matchmaking.
• Make a move: a player submits a move in algebraic notation. The server validates legality, enforces turn order, and advances the board state.
• Game state: any authenticated client can fetch the current board state, move history, clocks, and result at any time.
• Matchmaking: automatically pair two players of similar rating for a new game.
• Spectators: any number of read-only observers can watch a live game in real time; they see each move within ~1 second of it being played.
• Real-time move updates: both players and spectators receive move notifications via push (not polling).
• Time controls: each player has a clock (e.g. blitz 5+0, rapid 10+5). The server is the authoritative clock; it deducts time on each move and flags a player as having lost on time if their clock expires.

Non-functional requirements

• Move latency: the opponent and spectators should see a move within 500 ms of submission in the same region; p99 < 1 s globally.
• Turn-order consistency: no player may submit two consecutive moves without the opponent having moved in between. Enforced server-side regardless of client behaviour.
• Anti-cheat: the server validates every move against legal chess rules. An illegal move is rejected (422) and does not advance the game.
• Idempotent moves: a network retry of the same move at the same ply must not create a duplicate move.
• Clock precision: server clock deductions are monotonic. A client cannot gain extra time by disconnecting and reconnecting.
• High availability for reads: game state reads should remain available even if the primary game server is temporarily unavailable.

Scale assumption: 500,000 concurrent active games. Each game produces roughly one move per 30 seconds on average (blitz games move faster; classical slower). That is ~17,000 move submissions per second at peak, each fanning out to 2 players plus a variable number of spectators. A popular tournament game may have 10,000 spectators.

2 — Design decisions

Decision 1: Server-authoritative move validation (anti-cheat boundary)

Imagine a locked vault with a slot in the door. You slide a move proposal through the slot; the vault checks it against the rules, stamps it "legal" or "illegal," and only if legal does it update the canonical game record inside. The client never touches the canonical record directly — it only sees what the vault stamps and returns.

In practice: the server receives a move string like "e2-e4", loads the current board state, runs a legal-move generator, and either advances the game or returns 422. The client holds a display board for smooth UX (premove, animation), but that board is considered speculative until the server confirms. This is what "server-authoritative" means: the server's board is the only board that counts.

Why it matters for anti-cheat: without this boundary, a client can lie about the board state, submit moves for the wrong colour, or use a local engine to calculate moves without network round-trips. With it, all of those attacks require compromising the server itself.

Decision 2: REST for game CRUD, WebSocket for real-time push

Two interaction styles serve different needs:

The REST / WebSocket split is clean: REST handles writes (games, moves) and point-in-time reads. WebSocket handles everything that is push-based — moves arriving at the opponent, clock updates, game-over signals. This means a player client needs one persistent WebSocket connection per active game, and uses REST for submitting their own moves.

Decision 3: Game lifecycle as a state machine

A game is not just a collection of moves — it is a stateful entity with well-defined transitions. Modelling it as a state machine forces you to enumerate every transition and its preconditions, which makes the API surface explicit.

States: WAITING (created, awaiting second player) → ACTIVE (both players present, moves allowed) → PAUSED (optional: a player disconnected during casual/correspondence play) → COMPLETED (checkmate, stalemate, resignation, timeout, draw agreement). COMPLETED is terminal; no transitions out.

Each API operation is a transition guard: POST /moves is only valid when the game is ACTIVE and it is the submitting player's turn. Attempting it in any other state returns 409 Conflict with a game_state field in the error body so the client can handle it correctly.

Decision 4: Idempotent move submission keyed by ply number

Network retries are inevitable — a mobile player's connection drops mid-submit. Without idempotency, two copies of the same move arrive at the server; the first succeeds and the second either fails with a confusing error or, worse, is interpreted as a second move by the same player (violating turn order).

The solution (idempotency): the client includes a ply field in the move body — the half-move number this move should be. If the server receives a move with ply=23 and the game is already at ply=23 (the move was already applied), it returns the same 200 response as if it just accepted the move. If the server receives ply=23 and the game is at ply=25 (the move is stale), it returns 409. The ply number is a natural idempotency key: it encodes "this is the 23rd half-move in this game" uniquely.

Decision 5: Optimistic concurrency for turn order

Two rapid move submissions from the same player (a network glitch replays the POST) could race at the server. To prevent turn-order corruption without a distributed lock: the server stores the current ply number alongside the game record. The move handler runs a conditional update:

-- Pseudo-SQL: atomic turn check + advance
UPDATE games
SET    ply      = ply + 1,
       position = $new_fen,
       to_move  = $next_colour
WHERE  id       = $game_id
  AND  ply      = $expected_ply   -- optimistic lock on ply
  AND  to_move  = $submitting_colour;

If the WHERE clause matches zero rows (because ply advanced before this query ran), the handler returns 409. No extra locking infrastructure required.

3 — The API model

Create a game

POST /v1/games
Authorization: Bearer <token>
Content-Type: application/json

// Request body
{
  "time_control": {
    "initial_seconds": 300,    // 5 minutes
    "increment_seconds": 0      // no increment — blitz 5+0
  },
  "variant":      "standard",
  "opponent_id":  "player_77"     // null for matchmaking
}

// 201 Created
{
  "id":         "game_ab3f",
  "state":      "WAITING",
  "white":      "player_42",
  "black":      null,              // not yet joined
  "to_move":    "white",
  "ply":        0,
  "created_at": "2024-06-01T10:00:00Z"
}

Make a move

POST /v1/games/game_ab3f/moves
Authorization: Bearer <token>

// Request body — ply is the idempotency key
{
  "move":  "e2e4",       // long algebraic notation
  "ply":   1             // this should be the 1st half-move
}

// 200 OK — move accepted (or idempotent re-accept on retry)
{
  "ply":        1,
  "move":       "e2e4",
  "fen":        "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
  "to_move":    "black",
  "clock":      { "white": 292, "black": 300 },   // seconds remaining
  "game_state": "ACTIVE"
}

// 422 Unprocessable Entity — illegal move
{
  "error":  "illegal_move",
  "detail": "e2e5 is not a legal move for the piece on e2 in this position"
}

// 409 Conflict — wrong turn or stale ply
{
  "error":        "wrong_turn",
  "current_ply":  4,
  "to_move":      "black"
}

Fetch game state

GET /v1/games/game_ab3f

// 200 OK
{
  "id":         "game_ab3f",
  "state":      "ACTIVE",
  "white":      "player_42",
  "black":      "player_77",
  "ply":        4,
  "to_move":    "white",
  "fen":        "rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq e6 0 2",
  "moves":      [ "e2e4", "e7e5", "g1f3", "b8c6" ],
  "clock":      { "white": 286, "black": 289 }
}

WebSocket: subscribe to live game events

// Connect — one connection per game per client
wss://live.example.com/v1/games/game_ab3f/stream
Authorization: Bearer <token>  // via query param or upgrade header

// Server → client: move event
{
  "type":       "MOVE",
  "ply":        5,
  "move":       "f1c4",
  "fen":        "...",
  "clock":      { "white": 281, "black": 289 }
}

// Server → client: clock tick (every 1 s while ACTIVE)
{ "type": "CLOCK", "clock": { "white": 280, "black": 289 } }

// Server → client: game over
{
  "type":       "GAME_OVER",
  "state":      "COMPLETED",
  "result":     "white_wins",
  "reason":     "checkmate"
}

4 — Evaluation & latency budget

Real-time latency path

The player submitting a move cares about two latencies: (1) how long until they get the 200 confirmation (move-submit latency), and (2) how long until the opponent sees the move on their board (opponent-receive latency). Both matter for blitz games.

For spectator fan-out: a popular game with 10,000 spectators must push the same MOVE event to all 10,000 WebSocket connections. The WebSocket server cannot iterate 10,000 send calls synchronously on the hot path — it will block move acceptance for subsequent moves. The solution: publish to an internal game channel; a dedicated broadcast worker asynchronously drains the fan-out. The move-submit latency is unaffected; spectators may lag by up to ~200 ms behind the players, which is acceptable.

Turn-order consistency

The optimistic concurrency control described in Decision 5 is the consistency guarantee. Two concurrent POSTs for the same ply: the database accepts the first (ply matches) and rejects the second (WHERE ply = $expected_ply returns zero rows). No distributed lock needed; the database serialises competing writes through its own row-level locking on the game row.

Anti-cheat trade-offs

Server-side legal-move validation is comprehensive but has a cost: every move requires loading the current board position (FEN string) from storage, initialising a chess engine, and running the move generator. For a well-implemented engine in a compiled language this takes 1–3 ms. At 17,000 moves/second across 500,000 concurrent games, the CPU cost is proportional to the number of game workers, not the number of games — each game is independent.

The attack surface that server-authoritative validation does not eliminate: engine assistance (a player using a chess engine on their own device to choose moves). Detecting engine use requires statistical analysis of move quality over time (a separate anti-cheat service), not move legality checks. Legality checks only prevent cheating through illegal board manipulation.

Under the hood: the core mechanism

Every move submission flows through a strict pipeline: the server never accepts the client's view of the board as ground truth — it owns the canonical position and re-derives everything from it. Here is the exact data structure the server holds for a live game and the precise steps it executes on each move request.

The canonical game record

The server stores one row per active game. The key fields that enforce correctness:

The FEN string is the complete game state. Example after 1.e4 e5:

"rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq e6 0 2"
# ranks 8→1 / active colour (w=white) / castling rights / en passant / halfmove / fullmove

The move history is stored as a separate moves append-only table (game_id, ply, move_san). The FEN in the games table is always the current position — the move table is the audit log. On retry, the server looks up the moves table for the requested ply to return the original response without re-running the engine.

Worked trace: submit move → validate → broadcast

Concrete example: White submits 1.e4 (e2e4) as ply 1. The game is brand new (starting FEN, ply 0, state ACTIVE, to_move white).

Worked trace: illegal move rejected

Now black tries e7e5 — a legal move — but the client has a bug and submits e7e2 (a pawn jumping 5 squares).

The game state machine: transition guards in code

The state machine is not just documentation — each transition is enforced as a pre-condition check before the move handler runs the engine. The server checks all of these in order, short-circuiting on the first failure:

Move idempotency detail: when the server receives ply=N and the game is already at ply=N (or higher), it queries the moves table for ply=N and returns the stored response without re-executing. This means a retry after a network timeout returns a bit-for-bit identical response to the original — the FEN, clock, and to_move are all as they were when the move was first applied.

Operating & debugging it

Inspecting a live game from the server side

The three things you need to verify when a move is behaving unexpectedly:

Symptom → cause → fix table

Production monitoring checklist

1. Move acceptance rate: alert if illegal_move rejections exceed 1% of submissions — could indicate a client bug, a corrupted FEN, or a chess engine version mismatch.
2. Move handler p99 latency: should be under 50 ms. If it spikes, check the legal-move generator CPU time (profile the engine) and the games table UPDATE latency.
3. Optimistic update collision rate: if WHERE ply=N matches 0 rows more than ~0.1% of moves, concurrent duplicate submissions are higher than expected — check client retry logic.
4. WebSocket fan-out lag: measure time from DB write to opponent receives MOVE event. Should be under 100 ms. Spikes indicate pub/sub broker backpressure.
5. Games stuck in ACTIVE after clock expiry: run a periodic query for games where state='ACTIVE' AND (white_clock_ms=0 OR black_clock_ms=0) — these should have been transitioned to COMPLETED by the clock-expiry handler.

Sources & further reading

• Chess.com — How cheating detection works — covers engine detection vs. move legality, distinct problems
• MDN — WebSocket API — transport used for live game streaming
• RFC 6455 — The WebSocket Protocol
• Lichess API reference — open-source chess platform's public API; useful real-world comparison
• Wikipedia — Forsyth–Edwards Notation (FEN) — the standard compact encoding for chess board positions used in the API model above
• Stripe — Idempotent Requests — canonical reference for idempotency key design patterns