Online chess (matchmaking and real-time state)

01 · CONTEXT

What an online chess platform needs to do

An online chess platform does three things: finds an opponent of a similar level, hosts a real-time game with a clock for each player, and maintains a global rating ranking. This involves real-time communication between browser and server.

The point that organizes the design appears right in the source's prompt: the server validates every move and owns both clocks, so a player cannot claim that an illegal move is valid or that they still have more time.

02 · REQUIREMENTS AND SCALE

A single format and reference numbers

The prompt fixes a single format, the three-minute blitz: each player has three minutes in total and their clock only runs on their own turn. With that, all games follow the same matchmaking and clock rules.

There are three core requirements: find an opponent through level-based matchmaking and start the game; play in real time; and see the global ranking and your own position, updated shortly after each game ends.

The reference scale is 10 million registered players and 500 thousand simultaneous games at peak. Since each game has two players, each on their own connection, that is 1 million simultaneous connections, plus the capacity to validate every move and run two clocks per game.

03 · BASE DESIGN

First, just one game

The source proposes building a single game first and only then tackling, in the deep dives, the parts that get hard at scale. This teaching diagram follows that order.

1. The browser sends each move to the game server. The design has a single server to focus on the flow of one game.

2. The game server validates the move and owns both clocks: the player cannot claim that an illegal move is valid or that they have more time.

3. Each player's clock runs only during their turn, and it is controlled by the server, not the browser.

4. At the end of the game, the server writes the result to the database, from which the ratings and the ranking come.

04 · DEEP DIVES

Where the problem gets hard

According to the source, the parts that get hard at scale are matchmaking, the fleet of game servers, a fair clock under different latencies, and fast reads of the ranking.

05 · REAL REFERENCE

What Lichess documents

Lichess's README describes part of the architecture. WebSocket connections live on a separate server, which communicates through Redis; the pure chess logic lives in its own submodule; and the games are stored in MongoDB, indexed by Elasticsearch, totaling more than 12 billion.

1. Real-time connections go through a load balancer and reach connection-only servers, separate from the game logic, as in Lichess.

2. The connection server talks to the rest of the system over a Redis channel, as Lichess's README describes.

3. The game request goes to matchmaking, which looks for an opponent of a similar level and triggers a game server.

4. During the game, the game server validates each move and controls the clocks, receiving and returning messages over the Redis channel.

5. When the game ends, the result goes to a queue and a consumer updates the ratings and the ranking, which lets the ranking change shortly after games finish.

6. Ranking queries read from a dedicated cache instead of hitting the database on every request.

Ratings on Lichess use the Glicko-2 method. The documentation also records two rules: games lost to lag or disconnection do not give points back, but when Lichess itself restarts and someone loses on time because of it, the game is aborted.