Requirements

Functional Requirements:

• Matchmaking pairs players by skill level based on ELO rating.
• Provide real-time move updates between players via persistent connection (WebSocket).
• Enforce chess rules with server-side move validation, rejecting invalid moves.
• Store completed games and allow users to review past games and replay moves.
• Maintain user accounts with profiles, ELO ratings, win/loss records, and game statistics.

Non-Functional Requirements:

• Performance, server side validation should be exteremly quick under 100ms
• Scalability, need to scale to millions of users

Back of envelope

10 milliion users

1 million DAU, 5 games so 5 million games per day. 50 games per second. 1 move per 5 seconds.

10 QPS for games, 10x higher on peak times, 100 QPS potential

Storage

• 10 million user's data
• how many games per user? maybe 50 s an average
• how much data in a game, lets say average 100 moves, each move is 10 bytes (just a piece and a position). So 1kb per game
• 50 million games: 50million kb -> 50 gb
• 10 million users: 10million kb -> 10 gb
• 60gb is easily stored on one cpu

High Level Design

The key design to get right is the games themselves. These need to be extremly fast for blitz 5 minutes, game, where say a half second lag would be extremely jarring.

To minimize latency and the needed network bandwidth we will use websockets. The two client devices will connect to a gaming server that will host one of the games. They will send a json message like

{type: "entrance", user: "bob"} to enter the game and then send messages for each move {type: move, piece: "knight1", user: "bob", to: "F5"}

Given these two moves the server will continually store the current game state, manage the connection between both, and validate then update the game state.

Workflow

game creation -> assign user colors -> start game ->

server recieves move -> validates move -> updates game state

update game state then leads either to server is ready to recieve another move or game is over

Websocket storage

• 10kb for websocket connection
• 5kb to store the game state
• 32,000 KB ram / 15kb = 2000 games

even with 1000 games memory is not a bottle neck. validation should also be extremely quick sub 1 ms, and should therefore not be a bottleneck either. Network time will be the bottleneck

We probably could squeeze all these games onto one server but we would want to have a load balancer that is distrubted by region to minimize network travel time & would want redudnant servers for failures.

Game complete Workflow

1. Store all of the message history/moves into a database server
2. Send game complete resonses to the client devices
3. Free up the websocket connections

User profile

• Users want to be able to view past games, simple postgres that stores the history of all the games sot hey can review
• Elo score tracker to see their current elo score
• Highest elo score to see its height

Game matching service

• Each request for game should contain extremely little data, jus teh user id, elo score, and how long ago they requested the game
• One server can probably store all game requests in memory. Keep these game requests sorted by elo score and each 100ms look for matches. Match is defined by both player's elo scores are in an appropriate band I.E. +- 50. As time goes on the band increases, I.E. after 10 seconds of waiting the band goes up to +- 100 elo. We may also want to put preerence on putting geographically close people together to reduce network lag times.

Table design

user:

• user_id: UUID
• games: list[Game] // fk is actually stored on the game table
• elo_score: int
• highest_elo_score: Int
• friends: list[user]

game:

• game_id: UUID
• white_player: user_id
• black_player: user_id
• winner: "WHITE" | "BLACK"
• move_file_id: string // store list of moves in object storage like S3 since we only need them when replaying a game and a lag to parse the file is fine

Redis memory cached data

active_game:

• game_id: UUID
• white_player: user_id
• black_player: user_id
• time_elapsed
• game_type
• moves: list[string]

Api Design

create_move(player, piece_id, to_coordinates): websocket message when a move is made

create_game_request(player_elo, player_geolocation)

list_games(player_id)

list_moves(player_id, game_id)

Detailed Component Design

Websocket game

• If one player network fails then retry until reconnection while runnign the game clock
• If both player fails then stop the game clock, until one reconnects, then treat like one player network fails
• In case server fails, we need to get both players on a new server. We will need a monitoring system that looks for dead servers, uses the redis saved active_games. Then to these players we push a message to their devices asking them to reconnect to a new server. That new server will then use the active_game info from the redis cache to rebuild the game state
• Each time a client sends a move we first validate the move, then update the game state, if it passes. When we update the game state we both update the in memory server & the redis cache

Game matcing service should send new games to servers with the frewst # of current games. Or else create new servers on threshold