System Design: [Gaming leaderboard name]

Reference design for a real-time gaming leaderboard: score updates from trusted game servers, ranking with in-memory sorted sets, deterministic tie breaking, "my rank" and "top N" queries, sharding when one set is not enough, friends leaderboards, seasonal resets, and the boundary with anti-cheat. It is an introductory design: it explains each building block before using it, so it suits a first system design review or interview practice. It follows the structure of the System Design Document template, adds a 45-minute interview path, access-pattern and failure-mode tables, and is pre-filled with a worked design to adapt. Replace every [bracketed] value and every row marked Example; values marked Example are assumptions, not benchmarks.

Document control

Approvals

Revision history

Contents

1. Overview
2. Requirements
3. Capacity estimation
4. API design
5. Data model
6. High-level design
7. Detailed design
8. Scalability and performance
9. Reliability, security and operations
10. Trade-offs and alternatives
11. Delivery plan and risks
12. Appendices

1. Overview

1.1 Problem statement

[Example: The game computes rankings with a nightly SQL job that sorts all players by points. Players see yesterday's rank, the "top 100" page times out during events, and two players with equal points swap places between page loads. The new season mode needs live ranks for 50 million players.]

1.2 Proposed solution

[Example: When a match ends, the match service (a trusted server, not the game client) publishes a signed score event. A leaderboard writer records the event durably in a database and updates an in-memory sorted set for the current season. Ranks and the top 100 are read from the sorted set in a few milliseconds. Ties are broken by who reached the score first, encoded inside the sorted-set score. Friends leaderboards are computed at read time from the friend list. Each season uses a new key, so a reset is a key switch, not a mass delete.]

1.3 Decisions requested from reviewers

1.4 45-minute interview path

Use this order when the document serves an interview or a short review.

Start the deep dive with the naive answer, a database query that counts rows with a higher score, and show why it gets slower as players grow. Then introduce the sorted set and its logarithmic rank lookup.

2. Requirements

2.1 Core functional requirements

2.2 Non-functional requirements

2.3 Below the line (out of scope)

• [Example: matchmaking ratings such as Elo or Glicko (a separate service; the leaderboard can display them)]
• [Example: cheat detection itself (anti-cheat system; see 7.6 for the boundary)]
• [Example: rewards and prize payout at season end]
• [Example: cross-game global rankings]
• [Item deferred, with the release that will take it]

3. Capacity estimation

3.1 Assumptions

3.2 Score updates

Consequence: the write rate is far below what one in-memory node handles, so sharding is not needed for writes. Writes go through a queue only to absorb spikes and to make retries safe.

3.3 Reads

The top 100 is the same for everyone, so it is cached in the API for 1 s. "My rank" is per player and goes to the sorted set. Consequence: about $14\,500 + 29\,000 \approx 44\,000$ operations per second at peak, under half of one node's Example capacity $c$; read replicas add headroom and availability.

3.4 Memory

Consequence: the current season fits on one node with room to spare. Past seasons move to the database and are not kept in memory.

3.5 Summary

4. API design

4.1 Endpoints

4.2 Request and response examples

A rank request for one player with neighbours, and the response:

GET /v1/leaderboards/season-2026-10/players/p_8812?around=2 HTTP/1.1

{"board": "season-2026-10", "player": {"player_id": "p_8812", "rank": 1042, "points": 18350}, "neighbours": [{"rank": 1040, "player_id": "p_1201", "points": 18360}, {"rank": 1041, "player_id": "p_5530", "points": 18350}, {"rank": 1043, "player_id": "p_0077", "points": 18340}, {"rank": 1044, "player_id": "p_3109", "points": 18335}], "as_of": "2026-10-22T09:30:01Z"}

Players p_5530 and p_8812 both have 18 350 points; p_5530 reached it first, so it ranks higher (7.2).

4.3 Errors and idempotency

Score events carry match_id. The writer records (season, match_id, player_id) with a unique constraint, so a replayed event adds points once.

5. Data model

5.1 Entities

The database holds durable records; the sorted set is a derived index.

5.2 Storage choices

5.3 Access patterns

6. High-level design

7. Detailed design

7.1 Deep dive: why a sorted set

To find a player's rank, something must know how many players have a higher score.

A sorted set keeps members ordered by a numeric score. Adding or updating a member and looking up its rank both take time proportional to the logarithm of the set size, so 50 million players cost only a few dozen steps. In Redis the commands are ZADD or ZINCRBY to write, ZREVRANK for rank from the top, and ZRANGE ... REV for a slice by rank (ZREVRANGE is deprecated since Redis 6.2).

Choice: a sorted set per board, with the database as the source of truth. Reason: it is the only option that serves both top N and my rank in milliseconds for a live board.

The writer writes the absolute total computed by the database rather than incrementing in the cache. A retried write then sets the same value again instead of adding points twice.

7.2 Deep dive: ties

When scores are equal, Redis orders members by their names byte by byte (reversed for the ZREV commands). The order of two tied players then depends on their ids, which is not a game rule.

Choice: encode time. Redis scores are double-precision numbers, which represent integers exactly only up to $2^{53}$. Split those 53 bits into points and time: with $t$ the whole seconds since the season started,

$2^{22}$ seconds is about 48.5 days, enough for a monthly season, which leaves 31 bits for points (up to about 2.1 billion). Earlier $t$ gives a larger composite, so the earlier achiever ranks higher. The API decodes points as $\lfloor \text{composite} / 2^{22} \rfloor$. Reason: it keeps every query a single sorted-set call. Players who reach the same score in the same second still fall back to id order; document that as the final rule.

7.3 Deep dive: sharding and top N

Sharding is not needed at the estimated size (3.5), but plan it for boards that outgrow one node, for example a global all-time board.

Choice: hash sharding when needed, plus percentile display below the top 10 000. Reason: hash sharding keeps load even and top N is a cheap merge; players outside the top rarely need an exact six-digit rank, and a histogram answers "top 3%" with one lookup.

7.4 Friends leaderboards

Choose compute on read: friend lists are small (cap at Example 500), and friends boards are viewed far less often than scores change. Cache the result per player for Example 10 s.

7.5 Seasons and resets

Each season has its own key, for example lb:{game}:2026-10. At the season boundary (defined in UTC), the writer switches to the new key; the old set stays read-only for Example 7 days for late disputes, then a job writes FINAL_STANDING and deletes the old key. No mass delete happens at midnight, and late events for the old season are rejected by the season check. All-time boards, if any, are separate keys updated in parallel.

7.6 Anti-cheat boundary

The leaderboard is not where cheating is detected, but its design can make cheating harder:

• Accept scores only from the match service, never from game clients, and verify an event signature or service identity.
• Reject events outside plausible ranges (for example more points than a match can award) and route them to review.
• Support removal: the anti-cheat system calls the admin API, the writer marks the player removed in the database and removes the member from the sorted set; ranks of everyone below change immediately.
• Keep every score event, so points can be recomputed after a rules change or an exploit.

7.7 How real systems do it

How real systems do it (paraphrased, not copied). The AWS Database Blog post "Build a real-time gaming leaderboard with Amazon ElastiCache for Redis" (2019, updated 2024) describes moving ranking out of a relational database into Redis sorted sets, so that each score write keeps the set ordered and rank queries no longer scan tables. A later AWS for Games post on Amazon MemoryDB discusses the durability gap of a cache-only leaderboard and the common pairing of an in-memory store with a persistent database, which is the split used in this design. The Redis documentation itself lists leaderboards as a typical use of sorted sets and states that equal scores are ordered lexicographically, which is why 7.2 exists. Read the originals in 12.3; this box keeps only the general idea.

8. Scalability and performance

Latency budget for "my rank with neighbours" (target p99 50 ms):

9. Reliability, security and operations

9.1 Failure modes

9.2 Security and privacy

9.3 Observability

9.4 Cost estimate

10. Trade-offs and alternatives

11. Delivery plan and risks

11.1 Milestones

11.2 Rollout and rollback

[Example: Run the new leaderboard in shadow for one week, comparing ranks with the nightly job for a sample of players. Switch the client to the new API behind a flag; rollback switches the flag back to the nightly ranks.]

11.3 Risks

12. Appendices

12.1 Open questions

12.2 Glossary

12.3 References

Standard and licence note

Based on common industry practice for real-time ranking and on the public documentation cited in 12.3. The book and engineering write-ups listed there are inspiration only; no text, diagrams or numbers were copied, and all figures here are illustrative examples. Check the current documentation of your cache and database for command behaviour and limits. Original text written for this collection. Template licence: MIT.