Design a leaderboard with exact snapshot ranks

01Define score, rank and the board being ranked

Build seasonal game leaderboards offering top 100, a player's rank and nearby competitors. Scores are cumulative contributions from trusted match-result services, with authorized corrections that may decrease a total. Do not accept arbitrary browser-submitted scores. Anti-cheat model training and matchmaking are separate systems, although producer authorization and correction audit belong here.

Competition rank is one plus the number of players with a strictly higher score. Use the following scores and shared ranks:

Display order needs a deterministic tie-breaker, but it must not turn P3's shared rank into 3. Choose descending player ID for equal-score display order in this exercise, matching the selected ordered-index query direction. Thus P3 displays before P2, while both retain rank 2.

The initial design gives each season/region board one authoritative ordered index, supports a bounded largest board and scales many boards independently. Top lists may be cached for a second; personalized rank is exact for the single-index state read, not a claim of globally instantaneous agreement with newly accepted scoring events.

A successful score update may precede its displayed ranking while the projection catches up. Show that delay honestly. A hundred-million-player globally sharded exact rank is a stronger extension with additional coordination, not the default architecture hidden behind one endpoint.

Clarify whether the ranking is global or per season/region, how tied scores rank, and how quickly an accepted score must appear. Choose bounded boards with exact competition rank for each coherent index read and explicitly delayed score projection; a globally sharded instantaneous rank is a different prompt.

02Functional requirements

1. Accept trusted scoring events. Record match contributions and authorized revisions, including corrections that reduce a player’s total.

2. Read rankings. Provide top 100, a player’s competition rank and a bounded neighborhood with deterministic tie display order.

3. Manage seasons and awards. Separate season/rule namespaces, close under a stated cutoff and completeness policy, and publish an auditable frozen award result.

4. Recover score history. Deduplicate retries, expose ranking freshness and rebuild the ordered view from durable score evidence and versioned updates.

03Non-functional requirements

These are illustrative interview assumptions, not product facts or measured benchmarks. Confirm them before choosing components, then validate the completed design under the stated workload. Here p95 means the 95th-percentile latency: 95% of measured requests take no longer than that value. Report errors and rejected work alongside latency; a fast failure is not a successful outcome.

1. Fleet and board scale. Plan for 100 million player/board records, 10,000 score events/s and 50,000 top-list reads/s across the fleet. Keep the largest initial board at one million players; assume at most 1,000 score updates/s and 5,000 uncached rank/neighborhood reads/s on one board for its load test.

2. Read latency and visibility. Target top/rank/neighborhood reads below 200 ms p95 under admitted load. Target 99% of accepted score changes reaching the ordered index within one second. For updates that change top-100 membership, ordering or displayed scores, target 99% of those updates being incorporated into a served top-list snapshot within two seconds of acceptance, including the one-second cache interval. The snapshot may already include a newer accepted update. An update to a player outside the top 100 need not appear in that list. Stalled projection is a measured miss and must expose age.

3. Ranking correctness. Competition rank is one plus the number of strictly higher scores. Read the player’s score and comparison population coherently; tie display order does not change shared rank, and a retry cannot award the same match twice.

4. Durability and recovery. Committed score evidence and outbox state survive scoring-service restarts; the ordered index and cache may be rebuilt. Do not acknowledge scores based only on a disposable index. The database’s replica/region disaster policy remains a separate deployment requirement.

5. Authority and fairness of evidence. Accept scores only from authorized producers, audit corrections and rule changes, and enforce board/friend permissions. Freeze awards only after checking the agreed cutoff’s evidence is complete; a cache refresh alone cannot establish completeness.

04Complete scoring and ranking with one ordered board

Start with an authenticated scoring API, a transactional score database and an ordered index for each board. A hash lookup answers P2's current score, while an ordered structure supports top ranges and counts above a score. A Redis sorted set is one practical projection; the score database remains the recoverable source.

Trusted event E77 reports match M91 awarding P2 thirty points. One database transaction records its business identity and match contribution, changes P2 from 900 to 930, advances the player's version and stores an outbox update. A worker applies the complete new total to the ordered index only if its version is newer than the stored projection version.

The index update changes score and version atomically. A repeated version 12 update does not add thirty again, and a delayed version 11 cannot restore the old score. After application, P2 is above P1 and has rank 1. Top-list reads return the highest entries under the chosen display comparator.

For a rank read, obtain P2's score and the count of strictly higher scores in one bounded atomic index operation. Reading the score first and counting later could compare it with a different board state. The score and comparison count therefore describe the same index state, although scoring-to-index lag remains an explicit freshness limitation.

05Separate fleet size from one hot board

Assume 100 million active player/board records across many seasonal or regional boards, 10,000 score events/s across the fleet and 50,000 top-list reads/s. A bounded largest board initially has up to one million players; benchmark its assumed 1,000 score updates/s and 5,000 uncached rank/neighborhood reads/s on one index against the 200 ms p95 target. These are proposed capacity requirements, not measured capabilities.

At 64 bytes of raw player state, the fleet payload is about 6.4 GB, but ordered indexes, version lookups, allocators and replicas require more. At an illustrative 128 bytes per indexed player, a million-player board uses about 128 MB before additional overhead and copies. That explains why many useful boards can remain on one ordered owner, while still requiring measurement of real memory use.

Ten thousand 100-byte score events/s create 1 MB/s or 86.4 GB/day of history. Ninety days require 7.776 TB before indexes and replicas. Retaining auditable scoring evidence can cost far more than caching a top list.

A top 100 response at 48 bytes per entry is 4.8 KB; 50,000/s produces about 240 MB/s of response payload. Many readers can share a cached complete top list instead of recomputing it. Personalized rank and neighbor reads are less shareable, so size them separately rather than assuming one cache solves every query.

06Represent match contributions and projection versions

Interfaces

Read P2’s competition rank

GET /boards/S4/players/P2/rank

Complete projection update after the worked correction

{
  "season": "S4",
  "player": "P2",
  "total": 905,
  "version": 13
}

Stored records

An event ID suppresses transport retries, but a second event ID for the same match must not award its points again. The stored match contribution and its source revision prevent awarding the same match twice. Retrying identical accepted content returns the prior result; conflicting reuse of an identity is an error.

Scope every query and cache key by season, region and scoring-rule version. The same player can have different scores on different boards. A top 100 means one hundred display positions, not every player tied at the boundary. If the product wants all boundary ties, its result size and pagination contract must change explicitly.

07Apply corrections without repeating or losing points

For E77, the stored contribution for P2's match M91 changes from zero to thirty. The owner calculates the change:

Contribution change

delta = new contribution − previous contribution

It adds that delta to P2’s total within the same transaction that saves the contribution revision, accepted event and outgoing update. P2 moves from 900 to 930 at version 12.

Now an authorized correction changes that match contribution from thirty to five. The derived delta is −25, so the total becomes 905 at version 13. A delayed older revision cannot restore thirty or subtract twenty-five again. The source revision orders that match's evidence; the player version orders resulting total changes across all its matches.

Send complete versioned totals to the projection, not unprotected increments. A repeated message saying “total 905, version 13” can be recognized and ignored. Repeating “subtract 25” would corrupt the board unless separately deduplicated. A lower numeric score can still be the newer correct version, so comparing score magnitude is not a valid stale-update rule.

Changes to the scoring rule itself need an explicit board version or rebuild plan. Do not apply a new rule to only some old matches and present the mixed result as if every player had been evaluated consistently. Keep immutable evidence and audit correction authority.

08Explain ties, atomic reads and nearby results

For P2 at 900, count players with scores strictly above 900 and add one. P1 is the only such player, so P2 and P3 both have rank 2. A sorted-set ordinal position answers a different question: it includes the display tie-breaker and therefore does not directly implement shared competition rank.

With a Redis-style index, a strict score-range count such as scores greater than 900 supplies the needed count. Read the player's score and that count together through the chosen atomic script or transactional operation so another update cannot change the comparison between the two reads. Keep the operation bounded and use the index's supported count query rather than scanning all members in an application loop.

For top 100, fetch the ordered entries in one index read. Compute displayed shared ranks using strictly higher scores, carrying the preceding score/rank through the list. The chosen descending-ID tie-breaker affects ordering only. A large tie group can occupy many display positions while all its members share one rank.

Nearby-player results use the same score order and tie comparator. This default API offers a bounded neighborhood, not unlimited stable historical pagination. If users need to page through a fixed old board while scores change, retain a snapshot explicitly; persistence files are not automatically a historical query API.

09Cache shared reads and distribute independent boards

Cache each complete top list for a short interval with its board identity and as-of metadata. Thousands of viewers can reuse the same hundred entries, reducing index work. Cache the whole coherent result rather than mixing rows from several refreshes. Personalized rank remains a separate current-index operation and should not combine a fresh authoritative score with an older cached population.

Assign different season/region boards to different index owners. This provides straightforward aggregate scale while keeping each board's top, rank and neighbors local. Replicas can improve read availability under their disclosed lag; failover and rebuild must preserve the projection's version state or reconstruct it from the score source before accepting new updates.

For a single board that exceeds one owner's memory or throughput, discuss the changed cost explicitly. Hashing complete players distributes updates, and global top k can be obtained by merging every shard's local top k under the same comparator. A globally winning player cannot have k better players on its own shard and still be globally top k.

Exact personalized rank is harder: every shard’s count and the player’s score must describe the same board snapshot. The baseline deliberately avoids promising that distributed snapshot protocol. Options include a coordinated snapshot, a separately labeled approximate percentile, or retaining a larger single ordered authority after benchmarking.

10Close a season from complete scoring evidence

Create a new season namespace instead of synchronously zeroing every old player. Scores, match identities, rules and caches include the season so old retries cannot silently award points in the new competition. Closing a season has an announced cutoff and an allowed-lateness/adjudication policy.

For the bounded single-authority baseline, stop accepting ordinary season scores at the chosen cutoff, drain all previously accepted outgoing updates, and verify the ordered projection against the authoritative totals before freezing the final award result. Publish an immutable award version with the rule and cutoff used. A cache refresh time alone is not proof that every eligible match arrived.

If the contract uses match event time rather than acceptance time, trusted sources must establish completeness through that cutoff or the rules must explicitly define which late results are reviewed. Waiting an arbitrary second does not prove that an offline match source has finished sending results.

A later fraud finding or accepted correction produces a new audited award-decision version rather than silently rewriting the originally awarded snapshot. This separates live display freshness from the stronger reproducibility required for prizes. Keep enough scoring evidence to explain the final result; the tiny top-list cache is not the evidence archive.

11Rebuild the index without treating it as score truth

A rebuild must include player versions as well as scores, then catch up updates after the source snapshot before becoming current. Copying arbitrary rows while scores change without a replay boundary can miss or double-apply changes. Use the database's consistent snapshot and change-stream/outbox recovery capabilities.

During overload, protect authoritative score acceptance and recovery work before optional personalized queries. Bound top-list limits, neighborhood size and private-board populations. The service can deliberately display an older complete top list while recovering, but must expose its age rather than call a stalled index live.

A future distributed board cannot omit one failed shard and still return an exact global rank. That missing population may contain every player above P2. Use a previously complete snapshot or fail the exact query under the stronger design's declared contract.

12Test the ranking rules rather than only endpoint speed

Monitor scoring acceptance, score-to-index lag, duplicate-event suppression, conflicting revisions, index rebuild progress, memory use and per-board read/write hotspots. A healthy cached top endpoint can hide a scoring pipeline that has not updated for an hour. Track the oldest unapplied score event directly. Measure accepted-score-to-index delay against one second for 99% of updates. For updates that affect top-100 membership, order or displayed scores, measure acceptance-to-visible-effect against two seconds total, including cache time; outages still count as visible misses.

Test tied scores, ties crossing the hundredth display position, E77 arriving twice, the same match under different event IDs, downward corrections and old revisions arriving late. Compare sampled ranks with a slow sort of the same source snapshot. Verify that the selected ordered-index tie behavior matches the API comparator rather than assuming reverse-score queries keep ascending member order.

Authorize score producers and corrections, audit rule changes and protect private friend graphs. A friend-only board ranks within the authorized friend population; filtering a global top 100 afterward can omit all relevant friends outside that global list. For a small friend set, retrieve their complete scores and rank that bounded set directly.

The primary limits are one very hot board, required historical snapshots and exact global rank under sharding. Keep those visible. The first coherent design can meet a useful bounded product without compressing a distributed publication proof into an unexplained “generation” field on every response.

13Check the design against its requirements

Use the numbered requirements to check the final design. FR refers to the functional list; NFR refers to the non-functional list. Performance rows specify tests still required, not achieved benchmark results.

14Rapid revision

Remember: A newer correction can lower a score. Order updates by version, and count strictly higher players for shared rank.

Close by tracing P2 from 900 to 930 after E77, then to 905 after correction. Explain why repeating E77 changes neither total, why P2 and P3 once shared rank 2, and why a globally sharded exact rank would require an additional coherent-view contract.

Recall the key ideas

Answer from memory before opening each card. Explain why the choice works and what it costs. Revisit missed cards tomorrow.