Sign in to keep reading
“Online Chess” is free with an account. Your progress and bookmarks follow you across devices.
Sign in to continueDesign an Online Chess Platform - This system design covers real-time multiplayer gameplay, server-authoritative game state, distributed matchmaking, cross-device session management, and leaderboard updates at scale.
Written by a Staff+ Engineer and an Engineering Manager
10+ years of experience in low-latency streaming and AI infrastructure. Tech lead for real-time LLM serving platforms handling millions of concurrent requests. Over 12 years of industry experience with 6 years in engineering leadership, building and scaling tech infrastructure teams that deliver end-to-end large-scale distributed systems.
“Online Chess” is free with an account. Your progress and bookmarks follow you across devices.
Sign in to continueThink Beyond the Happy Path
Could you answer these today? Tick what you already know.
Design a distributed chess platform that allows millions of users to play real-time games against opponents matched by skill level. The system must support simultaneous games, enforce chess rules server-side, maintain accurate game clocks, and provide instant move updates with sub-200ms latency. Players should be able to start games through automated matchmaking or by sending direct challenges to friends.
The platform needs to handle 500,000 concurrent games during peak hours, store complete game histories indefinitely for later review and analysis, and maintain global leaderboards that update within seconds of game completion. The system must prevent cheating through client-side manipulation while ensuring players can seamlessly resume interrupted games from any device. Consider how you'll handle network failures, concurrent move attempts, and the complexities of features like offering draws or requesting move takebacks.
The use case is that a player clicks "Play" and gets paired with a similarly skilled opponent, or challenges a friend and starts a new match once accepted. Let's truncate this use case:
The use case is that once the game starts, both players interact in real time and see consistent board updates and accurate clocks.
Knowledge Tip - Clock in Chess
In real-time chess, each player has a fixed amount of time to complete all their moves, and only the active player's clock counts down during their turn. When a player makes a move, their clock stops and the opponent's clock starts. If a player's remaining time reaches zero before the game ends, they automatically lose on time (unless the position is a draw by rule). Because clock accuracy directly affects fairness, the server must be the single authority for time tracking and turn switching — client-side clocks are only visual representations and cannot be trusted.
The use case is that players can end games naturally (checkmate, timeout) or through interactions like resignation or draw offers.
Chess is a rule-based competitive game. The system must guarantee that every game progresses in a single, deterministic order without inconsistencies.
game_id, moves must be applied in a strict, authoritative sequence.Chess is interactive and clock-sensitive. Move delivery must feel instant to both players.
The system must support large peak traffic without gameplay degradation.
The system should remain safe and usable under real-world failures.
Game history is a core product promise and must not be lost.
Requirement Summary
| Functional Requirements (FRs) | |
|---|---|
| Name | Description |
| FR1. Game Set: Matchmaking & Creation | Match players by skill level or direct challenge, and initialize a new authoritative game session. |
| FR2. In-Game: Real-Time Gameplay | Accept, validate, apply, persist, and broadcast moves with server-authoritative board and clock control. |
| FR3. Game Completion | Detect terminal conditions (checkmate, timeout, resignation, draw), finalize result, and update leaderboard. |
| Non-Functional Requirements (NFRs) | |
|---|---|
| Name | Description |
| NFR1. Correctness & Deterministic Ordering | Per game, moves must form a single strict order with server-authoritative board and clock. |
| NFR2. Low Latency | End-to-end move propagation must meet sub-200ms p99 target. |
| NFR3. Scalability | Support 500,000 concurrent games with horizontal scalability. |
| NFR4. Fault Tolerance | Network failures, retries, and concurrent actions must not corrupt state. |
| NFR5. Durability | Persist complete game histories indefinitely with no loss of acknowledged moves. |
Knowledge Tip — Why WebSocket for Real-Time Chess and how HTTP "upgrades" to WS
For real-time gameplay, we use WebSocket because it provides a long-lived, bidirectional connection so the server can push moves and clock updates instantly without repeated HTTP polling. Practically, the client first makes a normal HTTP request to obtain game_id and a short-lived join_token, then opens wss://... to the game endpoint. Under the hood, the WebSocket handshake starts as an HTTP/1.1 request containing Connection: Upgrade and Upgrade: websocket. If the server accepts, it returns 101 Switching Protocols. From that point forward, the same underlying TCP connection is kept, but the application-layer framing switches from HTTP messages to WebSocket frames (still running over TCP/IP, and over TLS for wss). This lets us treat REST as the "setup/control plane" and WebSocket as the "in-game data plane."
Now we will follow the user journey during the chess game to illustrate our high level APIs and data communications.
1. Create a match request (level matching or friends challenge)
POST /v1/matches
Mode A — Level Matching
{
"mode": "LEVEL_MATCHING",
"user_id": "userA",
"skill": { "rating": 1520 },
"clock_config": { "initial_ms": 300000, "increment_ms": 0 }
}
Mode B — Friends Challenge
{
"mode": "FRIENDS_CHALLENGE",
"from_user_id": "userA",
"to_user_id": "userB",
"clock_config": { "initial_ms": 300000, "increment_ms": 0 }
}
{"match_id":"m_123","status":"PENDING"}
2. Check match status (poll until matched)
GET /v1/matches/{match_id}
If matched
{
"match_id": "m_123",
"status": "MATCHED",
"game_id": "g_456",
"ws_url": "wss://.../v1/ws/games/g_456",
"join_token": "jwt_or_session_token"
}
3. Accept a friends challenge (only for FRIENDS_CHALLENGE)
POST /v1/matches/{match_id}/accept
{"user_id":"userB"}
{
"status": "MATCHED",
"game_id": "g_456",
"ws_url": "wss://.../v1/ws/games/g_456",
"join_token": "jwt_or_session_token"
}