Represent legal moves, turns, game state, persistence, and optional multiplayer synchronization.
Choose a path, then play or step through exactly how the call moves between components.
The caller starts the operation at Player Client with a stable request and retry identity.
The design separates the latency-sensitive online path, the correctness-critical durable transition, and asynchronous projection or repair work. Each chapter below explains one decision shown in the diagrams.
State assumptions before choosing technology. The supplied workload is 2–8 players · deterministic rules · replayable history. Convert it into peak throughput, retained records, bandwidth, and failure budget; then connect each number to a component.
| Dimension | Working estimate | Design implication |
|---|---|---|
| Traffic | 2–8 players · deterministic rules · replayable history | Separate online compute, durable state, and asynchronous consumers. |
| Peak factor | 5–10× average | Admission control, autoscaling headroom, and hot-key protection. |
| Stored state | write rate × retention × record bytes | Partition count, indexes, compaction, backup, and archival tier. |
| Network | peak operations × payload size | Batching, compression, edge placement, and egress budget. |
| Availability | 99.9–99.99% | Multi-zone replicas, tested failover, and dependency error budgets. |
| Recovery | RPO/RTO by invariant | Ack boundary, replay retention, reconciliation, and operator runbooks. |
POST /v1/matchescreate/joinWS MOVE(match_id, turn, client_move_id, move)GET /v1/matches/{id}/state?after_turn=POST /v1/matches/{id}/resignmatch(match_id PK, ruleset, players, state, turn, version) move(match_id, turn, actor, client_move_id, action, state_hash) snapshot(match_id, turn, state_blob, checksum) clock(match_id, player_id, remaining_ms, updated_at)
# Command envelope
operation: POST /v1/matches
request_id: req_01J...
idempotency_key: idem_7f2...
aggregate_key: board-card-game_123
expected_version: 17
payload: {...}
# Durable event
event_id: evt_01J...
aggregate_key: board-card-game_123
event_type: board_card_game_committed
schema_version: 3
trace_id: tr_8ac...The authoritative aggregate and idempotency record share a transactional or conditional-write boundary. Event streams, search indexes, caches, analytics, and dashboards are rebuildable projections.
↑ topThe boxes are not a shopping list. Each boundary exists because it owns a different invariant, scaling dimension, data lifecycle, security policy, or failure domain. The table makes those choices explicit and shows when the design should remain simpler.
| Component | Owned responsibility | Why separate it | Rejected alternative | Cost and evolution trigger |
|---|---|---|---|---|
| Player Client | Owns client protocol, request identity, retry, and resume behavior. In this design it participates in: Route all commands for a match to one session actor/serialized mailbox. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents the external caller from also owning the contract and failure behavior of Lobby / Matchmaking. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Duplicate move after reconnect” to the external caller. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Player Client boundary before extracting or scaling it. |
| Lobby / Matchmaking | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Check player, turn, sequence, clock, and dedupe client_move_id. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Player Client from also owning the contract and failure behavior of Game Gateway. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Clock expires during valid move” to Player Client. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Lobby / Matchmaking boundary before extracting or scaling it. |
| Game Gateway | Owns authentication, validation, quotas, deadlines, and routing. In this design it participates in: Pure rules engine validates move and returns deterministic next state plus events. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Lobby / Matchmaking from also owning the contract and failure behavior of Session Actor. | Put protocol, authentication, quotas, and business transitions in one process. Acceptable at low scale, but it couples external traffic risk to domain releases. Here that simpler choice would couple “Session owner crashes after append” to Lobby / Matchmaking. | Costs another hop, policy distribution, and a high-blast-radius fleet. Introduce it when many clients or services need one protocol and protection boundary. Measure the latency, saturation, lag, or mismatch at the Game Gateway boundary before extracting or scaling it. |
| Session Actor | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Append move/state hash durably, update snapshot, acknowledge player, and fan out. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Game Gateway from also owning the contract and failure behavior of Turn Coordinator. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Random deck differs across replicas” to Game Gateway. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Session Actor boundary before extracting or scaling it. |
| Turn Coordinator | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Reconnect loads snapshot plus moves; anti-cheat verifies hidden information and timing server-side. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Session Actor from also owning the contract and failure behavior of Rules Engine. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Spectator receives hidden state” to Session Actor. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Turn Coordinator boundary before extracting or scaling it. |
| Rules Engine | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Route all commands for a match to one session actor/serialized mailbox. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Turn Coordinator from also owning the contract and failure behavior of Legal Move Generator. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Duplicate move after reconnect” to Turn Coordinator. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Rules Engine boundary before extracting or scaling it. |
| Legal Move Generator | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Check player, turn, sequence, clock, and dedupe client_move_id. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Rules Engine from also owning the contract and failure behavior of Random Seed / Deck. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Clock expires during valid move” to Rules Engine. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Legal Move Generator boundary before extracting or scaling it. |
| Random Seed / Deck | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Pure rules engine validates move and returns deterministic next state plus events. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Legal Move Generator from also owning the contract and failure behavior of Authoritative State. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Session owner crashes after append” to Legal Move Generator. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Random Seed / Deck boundary before extracting or scaling it. |
| Authoritative State | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Append move/state hash durably, update snapshot, acknowledge player, and fan out. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Random Seed / Deck from also owning the contract and failure behavior of Immutable Move Log. | Embed policy in every caller. Rules then drift by deployment version and emergency changes require fleet-wide redeployment. Here that simpler choice would couple “Random deck differs across replicas” to Random Seed / Deck. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Authoritative State boundary before extracting or scaling it. |
| Immutable Move Log | Preserves durable ordering, replay, and consumer checkpoints. In this design it participates in: Reconnect loads snapshot plus moves; anti-cheat verifies hidden information and timing server-side. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Authoritative State from also owning the contract and failure behavior of Snapshot Store. | Call every downstream consumer synchronously. That couples user latency and availability to analytics, notification, indexing, and audit dependencies. Here that simpler choice would couple “Spectator receives hidden state” to Authoritative State. | Costs eventual consistency, schema evolution, replay tooling, idempotent consumers, and lag operations. Earn it when bursts or downstream failure must not block acknowledgment. Measure the latency, saturation, lag, or mismatch at the Immutable Move Log boundary before extracting or scaling it. |
| Snapshot Store | Owns authoritative versioned state or immutable evidence. In this design it participates in: Route all commands for a match to one session actor/serialized mailbox. | Defines the source of truth and commit boundary. It prevents Immutable Move Log from also owning the contract and failure behavior of Clock Service. | Let each service persist its own interpretation. That removes one clear commit boundary and makes retries, support, and reconciliation ambiguous. Here that simpler choice would couple “Duplicate move after reconnect” to Immutable Move Log. | Costs schema migration, replication, backup, and shard ownership. Split storage only when access patterns, retention, or compliance boundaries materially differ. Measure the latency, saturation, lag, or mismatch at the Snapshot Store boundary before extracting or scaling it. |
| Clock Service | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Check player, turn, sequence, clock, and dedupe client_move_id. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Snapshot Store from also owning the contract and failure behavior of Spectator Fanout. | Keep this behavior inside an adjacent service. Prefer that simpler option until independent scale, ownership, policy, or failure isolation is measurable. Here that simpler choice would couple “Clock expires during valid move” to Snapshot Store. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Clock Service boundary before extracting or scaling it. |
| Spectator Fanout | Executes idempotent asynchronous work under lease and retry policy. In this design it participates in: Pure rules engine validates move and returns deterministic next state plus events. | Separates a distinct scale, ownership, policy, or failure boundary. It prevents Clock Service from also owning the contract and failure behavior of Anti-Cheat / Audit. | Perform the work before acknowledging the caller. This gives simpler consistency but unbounded tail latency and fragile retries. Here that simpler choice would couple “Session owner crashes after append” to Clock Service. | Costs leases, checkpoints, retries, DLQs, and lag operations. Separate once execution time or burstiness no longer fits the request deadline. Measure the latency, saturation, lag, or mismatch at the Spectator Fanout boundary before extracting or scaling it. |
| Anti-Cheat / Audit | Owns one bounded domain decision, transition, or operational capability. In this design it participates in: Append move/state hash durably, update snapshot, acknowledge player, and fan out. | Proves correctness and supports controlled recovery. It prevents Spectator Fanout from also owning the contract and failure behavior of operators and repair tooling. | Infer correctness from request logs. Logs do not prove durable business state, detect silent drift, or safely repair ambiguous outcomes. Here that simpler choice would couple “Random deck differs across replicas” to Spectator Fanout. | Costs an interface, deployment, telemetry, ownership, and failure mode. Keep it in-process first; extract when independent scale or reliability pays for the boundary. Measure the latency, saturation, lag, or mismatch at the Anti-Cheat / Audit boundary before extracting or scaling it. |
Make the rules engine pure: given state and action, return validation plus next state.
A single deployable with one transactional store is the right starting point for a small chess or card game workload. The proposed boundary becomes justified when make the rules engine pure: given state and action, return validation plus next state. Separating it contains the named failure “Duplicate move after reconnect” without placing unrelated work on the critical path.
Store an immutable move log for replay, undo policy, spectators, and dispute resolution.
The design coordinates only where every object transition is legal and atomic at one aggregate boundary. Everywhere else it accepts bounded staleness or asynchronous propagation. The alternative—strong coordination for every projection—simplifies the mental model but increases tail latency and turns partitions into broad write unavailability.
Use optimistic client rendering but let an authoritative session validate sequence numbers and turns.
This choice adds dashboards, ownership, schema compatibility, capacity planning, and recovery runbooks. Start with the minimum topology that supports “Pure rules engine validates move and returns deterministic next state plus events.” and extract another service only when measured throughput, blast radius, data lifecycle, or team ownership changes independently.
Make the rules engine pure: given state and action, return validation plus next state.
Store an immutable move log for replay, undo policy, spectators, and dispute resolution.
Use optimistic client rendering but let an authoritative session validate sequence numbers and turns.
Route all commands for a match to one session actor/serialized mailbox.
Check player, turn, sequence, clock, and dedupe client_move_id.
Pure rules engine validates move and returns deterministic next state plus events.
Append move/state hash durably, update snapshot, acknowledge player, and fan out.
Reconnect loads snapshot plus moves; anti-cheat verifies hidden information and timing server-side.
identity = authenticate(request) prior = idempotency.get(identity, request.key) if prior: return prior.result current = authoritative_store.read(partition_key) next_state, events = domain.transition(current, request) authoritative_store.compare_and_set(current.version, next_state) idempotency.commit(request.key, next_state.result) outbox.append(events) return next_state.result
Add a cache only for a measured repeated read; do not place mutable correctness state in a disposable layer.
Measure per-key and per-tenant skew. Replicate safe reads, isolate the offender, salt only when ordering permits, and enforce budgets.
Bound queues, buffers, connection pools, and concurrency. Shed low-priority work and scale from lag/oldest-item age rather than CPU alone.
Use single-flight/coalescing, jittered expiry, bounded retries, exponential backoff, and circuit breakers so one dependency failure does not multiply traffic.
partition = stable_hash(primary_or_aggregate_key) → shard owner write = conditional_update(expected_version) read_projection = versioned and rebuildable
every object transition is legal and atomic at one aggregate boundary. Use a uniqueness constraint, serializable/conditional write, expected version, or fencing token at this boundary.
Analytics, notifications, search, read models, and operational dashboards may lag when freshness is observable and replay exists.
| Operation | Consistency | Reason |
|---|---|---|
| Authoritative mutation | Conditional / serializable | Protect uniqueness, ownership, money, inventory, order, or legal state transition. |
| Read after own write | Primary, session token, or cache warm | The caller must observe the result it just committed. |
| Ordinary read projection | Bounded stale where safe | Replicas and caches improve latency when version/freshness is visible. |
| Analytics and operations | Eventual + replay | Freshness is less important than isolating the online path. |
| Failure | Runtime behavior | Recovery proof |
|---|---|---|
| Duplicate move after reconnect | Resolve at source of truth with uniqueness, expected version, lease generation, or monotonic cursor. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
| Clock expires during valid move | Stop unsafe progress, serve only explicitly safe degraded behavior, and recover from durable state. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
| Session owner crashes after append | Stop unsafe progress, serve only explicitly safe degraded behavior, and recover from durable state. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
| Random deck differs across replicas | Stop unsafe progress, serve only explicitly safe degraded behavior, and recover from durable state. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
| Spectator receives hidden state | Stop unsafe progress, serve only explicitly safe degraded behavior, and recover from durable state. | Reconciliation returns zero invariant gaps; lag/replica health and user-visible SLO return to baseline. |
# Recovery checkpoint scenario: Duplicate move after reconnect operation_id: op_01J... aggregate_key: board-card-game_123 last_durable_version: 18 projection_checkpoint: partition-07@offset-482901 retry_policy: same_identity / bounded_backoff reconciliation_status: pending owner: Anti-Cheat / Audit
Every dependency needs a timeout, retry budget, circuit policy, and explicit fail-open, fail-closed, stale, or read-only mode. “Highly available” is incomplete until degraded behavior is named.
↑ topMake the rules engine pure: given state and action, return validation plus next state. Walk the concrete lifecycle step “Route all commands for a match to one session actor/serialized mailbox.” Then test it against “Duplicate move after reconnect”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
Store an immutable move log for replay, undo policy, spectators, and dispute resolution. Walk the concrete lifecycle step “Check player, turn, sequence, clock, and dedupe client_move_id.” Then test it against “Clock expires during valid move”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
Use optimistic client rendering but let an authoritative session validate sequence numbers and turns. Walk the concrete lifecycle step “Pure rules engine validates move and returns deterministic next state plus events.” Then test it against “Session owner crashes after append”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
Make the rules engine pure: given state and action, return validation plus next state. Walk the concrete lifecycle step “Append move/state hash durably, update snapshot, acknowledge player, and fan out.” Then test it against “Random deck differs across replicas”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
Store an immutable move log for replay, undo policy, spectators, and dispute resolution. Walk the concrete lifecycle step “Reconnect loads snapshot plus moves; anti-cheat verifies hidden information and timing server-side.” Then test it against “Spectator receives hidden state”. State the retry identity, durable checkpoint, recovery signal, and cost of the alternative.
| Time | What to cover |
|---|---|
| 0–5 min | Clarify scope, workload, SLOs, and the correctness invariant. |
| 5–10 min | Estimate throughput/storage and define concrete APIs and records. |
| 10–20 min | Draw online, durable-write, and asynchronous/repair paths. |
| 20–30 min | Explain the exact lifecycle, partition key, and concurrency control. |
| 30–38 min | Discuss caching, hot keys, replication, and backpressure. |
| 38–43 min | Run failure drills, security, observability, and regional evolution. |
| 43–45 min | Summarize the five most important choices and trade-offs. |
| Invariant | every object transition is legal and atomic at one aggregate boundary. |
|---|---|
| Partitioning | Stable aggregate/key hash with versioned ownership and measured hot-key isolation. |
| Commit | Expected version or uniqueness at the authoritative state boundary. |
| Async work | Durable outbox/log, idempotent consumers, checkpoints, and replay. |
| Recovery | Same operation identity, durable truth lookup, and business reconciliation. |