Sign in to keep reading
“Leaderboard” is free with an account. Your progress and bookmarks follow you across devices.
Sign in to continueDesign a real-time leaderboard service - This system design covers global rankings, friend leaderboards, time-windowed boards, and handling billions of updates per day at scale.
Written by a Staff+ Engineer and an Engineering Manager
10+ years of experience in gaming infrastructure and real-time ranking systems. Tech lead for leaderboard platforms handling billions of score updates daily. 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.
“Leaderboard” 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 real-time leaderboard service for an online game that:
Here are some examples we made, and the following design align these assumptions:
1. Game & Score Model
2. Scale & Traffic Model
3. Leaderboard Scope (Multi-Dimension Support)
FR1 – Ingest & Update Player Scores
player_id, leaderboard_id (game / mode / region / period), and new_score plus an idempotency key (e.g., match_id).(player_id, leaderboard_id).FR2 – View My Global Rank & K Neighbors
player_id and leaderboard_id, the system must return:
FR3 – View K Friends Around Me
player_id, leaderboard_id, and K, the system must return:
FR4 – View Top-N Leaderboards (Global / Regional / Time-Windowed)
leaderboard_id and N, the system must return the top-N entries (player_id, score, rank) for that leaderboard.leaderboard_id:
Why these 4 Functional Requirements matter?
These aren't just "screens" the product wants — each FR encodes a distinct access pattern that drives the whole design:
(player_id, leaderboard_id).If you get these four access patterns right, most follow-up questions (sharding, caching, K-neighbors, hotspots, recovery) become specific implementation choices, not surprises.
NFR1 – Correctness & Determinism
(player_id, leaderboard_id) (e.g., keyed by match_id).NFR2 – Real-time Freshness & Latency
NFR3 – Availability & Graceful Degradation
NFR4 – Scalability & Hotspot Resistance
Why This Order?
For each important FR, we suggest structure the High-Level Design in this way:
score, last_match_id, ).API (Abstract)
We'll assume the game backend calls us after each match.
POST /leaderboards/{leaderboard_id}/players/{player_id}/score
Content-Type: application/json
{
"new_score": 12345,
"match_id": "match-uuid-123", // idempotency key
}
{
"player_id": "player-123",
"leaderboard_id": "lb-ranked-na-s12-week-2025-11-17",
"score": 12345,
"previous_score": 12000,
"last_match_id": "match-uuid-123", // last match that actually change sco
"updated_at": "2025-11-17T10:15:00Z",
"update_applied": true // false if this was a pure idempotent retry
}
Behavior guarantees
new_score < current_score, we ignore the update or return a 4xx error (pick one and be explicit).match_id for this (player_id, leaderboard_id), the request is a no-op: we return the existing score and update_applied=false.Core Entities
leaderboardsHIGH_SCORE world (monotonic best-score).| leaderboards | |
|---|---|
| Name | Description |
leaderboard_id | Primary key; unique identifier for this leaderboard (game + mode + region + period). |
game_id | Which game this leaderboard belongs to. |
| mode | Game mode type, e.g. HIGH_SCORE |
| region | Region for this leaderboard: GLOBAL, NA |
2. score_events (append-only log of raw updates)
(leaderboard_id, player_id, match_id) so the same match can't be ingested twice.| score_events | |
|---|---|
| Name | Description |
event_id | Primary key; unique id for this score event. |
leaderboard_id | Which leaderboard this event targets (FK to leaderboards). |
player_id | Player whose score this event is about. |
match_id | Match identifier; used for idempotency (one event per (leaderboard, player, match) |
3. leaderboard_scores (canonical per-player state)
(player, leaderboard).| leaderboard_scores | |
|---|---|
| Name | Description |
leaderboard_id | Leaderboard this score belongs to (PK part 1; FK to leaderboards). |
player_id | Player identifier (PK part 2). |
| score | Current high score for this player on this leaderboard (monotonic under HIGH_SCORE policy). |
last_match_id | The last match that actually changed this high score (used for idempotency and debugging). |
Workflow
Step 1 - Match service sends score update
POST the leaderboard_id, player_id, match_id, new_score to API-GW.Step 2 - API-GW routes to Score Ingestion Service
Step 3 - Score Ingestion validates leaderboard & logs event
leaderboard_id exists and is ACTIVE.score_events (leaderboard_id, player_id, match_id, new_score, event_ts).(leaderboard_id, player_id, match_id) enforces idempotency (duplicate match → treated as retry).Step 4 - Apply HIGH_SCORE rule using leaderboard_scores
(leaderboard_id, player_id) from leaderboard_scores.match_id == last_match_id → retry, no change.new_score <= current score → not a new high score, no change.leaderboard_scores with score = new_score, last_match_id = match_id, last_update_ts = now().Step 5 - Respond back to match service
score, previous_score, last_match_id, and update_applied = true/false → API-GW → match service.Design Diagram
Per game / per season, across all regions.
Regional leaderboard
Regional splits such as NA / EU / APAC.
Time-window leaderboard
Friends leaderboard
Rankings restricted to the user's friends list (social graph provided by a separate service).
last_update_tsEUAPACseason_id | Season identifier (e.g., "S12"). |
period_type | Time window type: DAILY, WEEKLY, MONTHLY, SEASONAL. |
period_start_ts | Start timestamp of this leaderboard period. |
period_end_ts | End timestamp of this period (null while active). |
| status | ACTIVE, FROZEN, or ARCHIVED (controls whether we accept writes). |
created_at | When this leaderboard was created. |
new_score | Candidate high score from this match (before applying HIGH_SCORE logic). |
event_ts | When this event was recorded. |
last_update_ts | When this high score was last updated. |
| version | Optional version counter for optimistic locking / concurrency control. |