Design an Online Chess Service

Two players, one board, and a server that acts as the referee. Unlike a chat application where messages are fire-and-forget, every chess move must be validated server-side before the opponent sees it. A malicious or buggy client could send an illegal move, and if the server blindly forwards it, the game breaks. The server owns the truth.

The core loop: a player submits a move, the server validates it against the full chess ruleset, updates the board state and clocks, broadcasts the result to the opponent, and checks whether the game has ended. Every design decision serves this loop.

Functional

Chess generates surprisingly little data per game but demands persistent connections. The bottleneck is concurrent WebSocket connections, not storage or compute.

Traffic

Assume 1 million daily active users. At peak hours, roughly 10% are in active games, that is 100,000 concurrent players, or 50,000 concurrent games. Each game requires 2 WebSocket connections (one per player). Peak load: 100,000-200,000 active WebSocket connections when accounting for players in matchmaking queues and browsing between games.

Two fundamentally different communication patterns serve this system. REST handles one-time operations like joining a matchmaking queue or fetching game history. WebSocket handles the real-time game session where every millisecond matters.

REST Endpoints

POST /api/matchmaking/join
Body: { "timeControl": "blitz_5_0" }
Response: { "queueId": "uuid", "estimatedWait": 5 }

Three storage tiers serve different needs. PostgreSQL holds permanent records that outlive any single game. Redis holds ephemeral state that must be fast but can be rebuilt. Game server memory holds the critical hot path. The state that is accessed on every single move.

Users Table (PostgreSQL)

1users
2├── user_id UUID PRIMARY KEY
3├── username VARCHAR(30) UNIQUE NOT NULL
4├── email VARCHAR(255) UNIQUE NOT NULL
5├── password_hash VARCHAR(255) NOT NULL
6├── rating INTEGER DEFAULT 1500
7├── rating_deviation INTEGER DEFAULT 350
8├── peak_rating INTEGER DEFAULT 1500
9├── wins INTEGER DEFAULT 0
10├── losses INTEGER DEFAULT 0
11├── draws INTEGER DEFAULT 0
12└── created_at TIMESTAMP NOT NULL

The architecture has two distinct paths. A matchmaking pipeline that creates games, and a real-time game loop that runs them. Every component serves one of these two paths.

API Gateway handles REST requests (matchmaking, game history, user profiles) and upgrades WebSocket connections for game sessions. It validates JWT tokens, enforces rate limits, and routes requests to the appropriate backend service.

Two flows define this system. Matchmaking is a one-time pipeline that creates a game. The move loop is a tight cycle that runs 40-80 times per game with sub-100ms latency requirements.

Matchmaking Flow

Three components contain the core complexity: the game session engine (the GATE), the clock manager, and the matchmaking algorithm.

Game Session Engine (GATE)

The server maintains a GameState object for each active game. This is the most critical data structure in the system. Every move reads it, modifies it, and broadcasts the result.

The stateful-vs-stateless decision for game servers is the defining trade-off of this system. It affects latency, resilience, scaling, and deployment. Every other trade-off is secondary.

Stateful vs Stateless Game Servers

Stateful (game state in server memory): Move validation is a microsecond in-memory operation. No Redis round-trip per move. Both WebSocket connections are on the same process, so broadcasting is direct. The cost: a server crash kills all active games on that server (mitigated by Redis backup). Scaling requires draining games before removing a server. Deployments need rolling restarts with graceful drain periods. You cannot simply kill and replace instances like stateless services.

A game server crash is the nightmare scenario, dozens of active games with real humans waiting for their opponent's move, and the state just vanished from memory.

Game Server Crash

Every move writes a backup to Redis. When a game server crashes, the recovery process begins. The load balancer detects the dead server (health check failure). Players' WebSocket connections drop. Each client automatically attempts to reconnect, sending a rejoin message with their game ID. The new game server receives the rejoin request, loads the last backed-up state from Redis, and resumes the game. Both clocks receive credit for the downtime (typically 5-10 seconds). At most one move of data is lost. The move that was being processed when the crash occurred. That player simply re-submits their move after reconnecting.

The core architecture handles millions of games per day. These extensions add engagement, competitive integrity, and new gameplay modes without changing the fundamental design.

Tournament System

Swiss-system and round-robin tournaments with automatic pairing, round scheduling, and bracket progression. The system reuses the matchmaking infrastructure but with constrained pairing, opponents must be from the same tournament and have not played each other yet. Each round starts simultaneously for all participants. A tournament leaderboard tracks cumulative points across rounds.