Design a Top-K Leaderboard

The leaderboard question surface is narrow on first glance: fetch the top K users by score. But the constraint that makes it interesting is freshness: the score window is live, updates arrive in bursts, and K users are queried by thousands of concurrent viewers. The question probes whether you understand why a naïve database query falls apart under concurrent writes — and what it takes to return a ranking in under 50 ms when scores are arriving in bursts.

Interviewers use this question to probe three distinct capabilities that map almost perfectly onto engineering level:

Note: L6 is not a separate architecture from L5: it's the multi-tenant, multi-window extension of the same design. An L6 candidate can articulate when to introduce complexity, not just how.

Functional requirements

Non-functional requirements

NFR reasoning

Leaderboard estimation has an unusual asymmetry: reads are heavy but cheap (sorted set range queries are O(log N + K)), while writes are moderate but bursty and cluster at predictable intervals. Storage has an unusual constraint: the primary serving store is fully in-memory, so RAM — not disk — is the binding capacity variable. The main question to resolve is whether the user population fits entirely in Redis memory.

Before discussing components, the dominant observation from §3 shapes the entire architecture: reads massively outnumber writes, but writes cluster in bursts that can overwhelm a naïve synchronous update path. The architecture separates the write ingestion path from the read serving path, with a stream as the decoupling boundary.

Component breakdown

Load Balancer routes client traffic to two separate service pools (Score API for writes, Read API for reads), enabling each pool to scale independently. Both pools are stateless; all state lives in Redis and Postgres.

Score API is the write-path gateway. It validates the score event, publishes it to a durable message queue (Kafka) with acks=all, and returns 202 Accepted immediately. It never writes directly to Redis — that keeps the write path's latency independent of Redis's single-threaded command execution.

Kafka (score events topic) is the durability boundary. Once a score event is committed to Kafka (replication factor 3, acks=all), it is guaranteed not to be lost even if every downstream service crashes. This decouples durability from availability of the consumer.

Aggregator Consumer is a Kafka consumer that reads score events in micro-batches (every 1–2 seconds), aggregates increments per user per leaderboard within the batch, and issues a single ZINCRBY call per user to Redis rather than one per event. When many players finish the same match simultaneously, a 1–2 second batch collapses 200k events into 20k–100k unique users — cutting ZINCRBY calls by 2–10× without any loss of accuracy.

Redis Sorted Set (ZSET) is the primary serving layer for all reads. ZINCRBY is O(log N) for writes; ZREVRANGE is O(log N + K) for top-K reads; ZREVRANK is O(log N) for user rank lookups. All operations are sub-millisecond even at 100M-user scale.

Postgres (score of record) stores the canonical per-user score, used for recovery (rebuilding the Redis ZSET after a full flush), auditing, and time-windowed queries that don't fit in Redis. It is not on the hot read path.

Architectural rationale

Real-world comparison

Ranking K users out of N is a well-studied problem with a wide spectrum of tradeoffs between exactness, memory, and latency. The right approach is determined by the total user population versus available RAM — a question that only materialises at 500M+ user scale, but one that distinguishes senior from staff-level answers.

Our choice for this system: Redis sorted sets (approach ①) for the active user population (up to ~500M), with Count-Min Sketch (approach ④) as a discussed extension once the population exceeds the RAM budget. Sharded sorted sets (③) appear in the scalability deep-dive as an exact alternative if approximate ranks are unacceptable at 2B+ users.

# Increment user score on an event (aggregated batch flush)
# pipe.zincrby is O(log N); pipelined for bulk updates
with redis.pipeline() as pipe:
    for user_id, delta in batch_scores.items():
        pipe.zincrby("lb:global", delta, user_id)
        pipe.zincrby(f"lb:daily:{today}", delta, user_id)
    pipe.execute()

# Top-K read — ZREVRANGE returns members sorted high-to-low
# withscores=True returns (member, score) tuples
top_k = redis.zrevrange("lb:global", 0, k - 1, withscores=True)

# User rank lookup — ZREVRANK is 0-indexed, so +1 for display
rank = redis.zrevrank("lb:global", user_id)  # None if not in set
score = redis.zscore("lb:global", user_id)

The leaderboard API has two core write endpoints and two core read endpoints. The write side is fire-and-forget (202 Accepted); the read side is synchronous with strict latency requirements.

POST /score-events — submit a score event

// Request
POST /score-events
Content-Type: application/json
Authorization: Bearer <api_key>

{
  "leaderboard_id": "global",
  "user_id": "u_7f3a9c",
  "delta": 150,          // score increment (must be positive)
  "event_type": "match_win",
  "idempotency_key": "match_42819_u_7f3a9c"   // caller-provided
}

// Response — 202 Accepted (event durably queued, not yet ranked)
{
  "event_id": "ev_9kLm2nQ",
  "status": "accepted",
  "expected_visible_in_ms": 5000
}

Input validation: delta must be a positive integer (no score decrements via this endpoint — score resets are a separate admin operation); leaderboard_id must exist; idempotency_key is used to deduplicate retried events at the Kafka consumer layer — writing the same key twice results in one score increment, not two.

GET /leaderboard/:id/top — fetch top-K entries

// Request
GET /leaderboard/global/top?k=100&offset=0
Authorization: Bearer <api_key>

// Response — 200 OK
{
  "leaderboard_id": "global",
  "generated_at": "2026-04-21T09:55:00Z",
  "total_entries": 100000000,
  "entries": [
    { "rank": 1, "user_id": "u_4a9f1b", "score": 98420, "display_name": "Nyx" },
    { "rank": 2, "user_id": "u_7f3a9c", "score": 97815, "display_name": "Zephyr" }
  ]
}

GET /leaderboard/:id/users/:user_id — user rank lookup

// Response
{
  "user_id": "u_7f3a9c",
  "leaderboard_id": "global",
  "rank": 2,
  "score": 97815,
  "percentile": 99.9998   // computed: (total - rank + 1) / total * 100
}

Optional endpoints by level

The durability NFR from §2 — zero score loss — drives the key design decision: the Score API must acknowledge only after the event is written to a durable store. The freshness NFR — 5-second lag — means Redis does not need to be updated synchronously. This produces the async write path shown below.

Why 202 Accepted, not 200 OK?

Returning 202 explicitly signals to the caller that the event has been durably accepted but the rank effect is not yet visible. This aligns with the eventual consistency model: a client that polls the leaderboard immediately after a 202 may not see the new rank, and that is correct behaviour, not a bug. A 200 OK would imply synchronous processing — semantically incorrect if the rank update is asynchronous.

Idempotency key mechanics

On first receipt, the Score API atomically stores the idempotency key in Redis (SET NX with a 24h TTL). If the key already exists, meaning this is a retry: the API returns immediately with the original 200 response and skips the Kafka publish entirely.

The SET NX atomicity matters: a naïve read-then-write pattern would allow two concurrent retries to both see a missing key, both publish to Kafka, and produce a double score increment. The key is also forwarded in the Kafka message header as a secondary guard, so the aggregator can drop duplicates within a batch window even if an event somehow slips through.

The leaderboard involves three distinct entities: score events (ephemeral, streaming), user scores (the materialised aggregate), and leaderboard metadata (configuration). Each entity is used very differently, and those differences shape how we store them.

Access patterns

Two structural constraints follow from these access patterns. First, the top-K and user rank operations both need a sorted structure — a B-tree index on score supports ORDER BY but degrades under concurrent increments (lock contention). Redis sorted sets handle both operations natively. Second, score events are write-once in Kafka and never updated; their only consumer is the aggregator, which drains them in order. Querying them for time-windowed boards requires a separate materialised view rather than scanning the raw event log.

Schema

Read-path flow

The 50 ms p99 latency NFR from §2 is what forces layers 1–2 to exist — Redis alone at high read QPS would still satisfy latency, but the absolute Redis command count becomes the ceiling. The read path works through each cache layer in sequence, short-circuiting on the first hit:

The baseline architecture scales comfortably to ~500M active users on a single Redis primary with read replicas. Beyond that, three bottlenecks emerge: Redis memory, write throughput, and merge complexity for global rankings across geographic shards. Each is addressed separately.

Classic probes table