Design Online Chess

The ask

Two players of similar strength start a game. They take turns moving pieces on one shared board.

A clock runs against the player to move. Running out of time loses the game.

Spectators can watch live games. Finished games stay stored for study and ratings.

Games span minutes, and players disconnect and return. The game must survive both.

Estimate the scale

Games start at 1,000,000 a day.

1,000,000 games / 86,400 seconds = 12 new games per second.

The average game lasts 80 moves. That is a stated figure for one game.

1,000,000 games x 80 moves = 80,000,000 moves a day.

80,000,000 moves / 86,400 seconds = 926 moves per second.

The rates are small. The tight budget is delay, since a move must reach the other player in about 100 milliseconds.

API and data

The find-game operation takes a player, a time control and a rating range. It returns a game or a place in the waiting pool.

The move operation takes a game, a player and a move. It returns the new board state, both clocks and the game state.

The resign and draw operations take a game and a player. A draw needs the other player's agreement, except where the rules force one.

A game record holds two players, a time control, a move list in order and a state. The state is waiting, live, or finished with a result.

A rating record holds a player, a time control and a rating number. Ratings update once, when a rated game finishes.

High-level design

Matchmaking is the pairing of players who are waiting for a game at a similar strength and time control. A matchmaking service owns the waiting pools, one pool per time control.

A game server hosts live games. Each game lives on one server, and that server is the single writer for its board.

Players hold a WebSocket connection to the game server. Moves and clock updates travel on that connection in both directions.

A rules component checks legality against the board. It knows piece movement, check, castling and promotion.

Finished games move to storage for records and rating updates. Live servers keep only live games in memory.

Deep dive: matchmaking pools

A fresh waiter accepts only a narrow rating range. A narrow range gives a fair game and a slower start.

The range widens the longer a player waits. Waiting itself becomes the trade the player makes for fairness.

Pairing happens in short rounds over each pool. Two players leave the pool together the moment a game is created.

Colour balance matters over many games. The pairing prefers the colour each player has played less lately.

A player who leaves pools repeatedly without playing gets slower entry. The pool protects patient players from churn.

Deep dive: the clock and the true state

The server keeps both clocks. A client's clock display is a copy, never the authority.

A move carries the game's move count as the player saw it. The server accepts it only if that count matches its own.

Time is charged when the server accepts the opponent's move. Network delay before a move arrives is part of the game, and fast time controls say so openly.

A disconnect pauses nothing by default. The clock keeps running, with a grace rule that ends abandoned games cleanly.

Reconnect returns the full board, clocks and move list. The player rejoins the same single-writer game.

Fair play

A detection service reviews finished and live game patterns for outside help. It is a named component with game records in and flags out.

Flags never change a live game mid-move. Reviews act on ratings and accounts after checks by people.

Rate limits guard the pools and the move path. One account cannot flood pairing or stall many games at once.

Every move and clock event is kept in order. A disputed game can be replayed exactly from its record.

Evaluation and trade-offs

One writer per game makes legality and clocks exact. The price is a game tied to one server until it ends.

Widening rating ranges trade fairness for waiting time. The pool makes that trade openly, second by second.

Server-owned state is the core promise. Online chess earns trust when no client can rewrite the board, the order or the clock.

State is small enough to keep whole games in memory. Durability comes from the ordered move record, saved as moves land.

Scale at a glance