Leaderboard

Functional Requirements

FR1 – Ingest & Update Player Scores

• The system must accept score updates for a player on a given leaderboard.
• Input includes: player_id, leaderboard_id (game / mode / region / period), and new_score plus an idempotency key (e.g., match_id).
• The system must maintain a non-decreasing integer score per (player_id, leaderboard_id).

FR2 – View My Global Rank & K Neighbors

• Given player_id and leaderboard_id, the system must return:
  • The player's current score.
  • The player's current global rank.
  • Up to K players above and K players below the user on the global leaderboard.
• Must handle edge cases (player near top/bottom → fewer than K neighbors).
• Results should reflect recent updates in near real-time (tied to our <500 ms update SLO).

FR3 – View K Friends Around Me

• Given player_id, leaderboard_id, and K, the system must return:
  • The player's rank and score within their friends-only leaderboard.
  • Up to K friends above and K friends below them.
• Uses an external friends/social graph as input; our service filters or indexes rankings based on that list.

FR4 – View Top-N Leaderboards (Global / Regional / Time-Windowed)

• Given a leaderboard_id and N, the system must return the top-N entries (player_id, score, rank) for that leaderboard.
• Must support multiple scopes via leaderboard_id:
  • Global (per game / per season, all regions).
  • Regional (e.g., NA / EU / APAC).
  • Time-windowed (daily / weekly / monthly / seasonal, each with a strict start date).
• Used for classic "Top 100 / Top 1000" views and tournament pages, and should refresh near real-time as scores change.

Non-Functional Requirements

NFR1 – Correctness & Determinism

• A player's score on a leaderboard is never lost, mis-ordered, or double-counted.
• Updates are monotonic and idempotent per (player_id, leaderboard_id) (e.g., keyed by match_id).

NFR2 – Real-time Freshness & Latency

• Write → visible rank (unchanged):
  • p95 ≤ 500 ms, p99 ≈ 1 s for the player's own score.
• Read APIs (my rank, neighbors, top-N), server-side:
  • p95 ≤ 100 ms, p99 ≤ 500 ms.
• It's fine if some pages (e.g., big top-N lists) sit closer to the tail; players experience this as "instant enough" as long as it's clearly under ~0.5–1 s end-to-end including network.

NFR3 – Availability & Graceful Degradation

• Leaderboard reads and score updates: ≥ 99.9% availability.
• Under failures, prefer serving last-known data (cached rank / top-N) over errors.
• If degraded, surface simple hints like "last updated X seconds ago" instead of breaking UX.

NFR4 – Scalability & Hotspot Resistance

• Handle 100–300M score updates/day → peak around 10K updates/sec.
• Handle ~1B leaderboard reads/day (~5× writes).
• Sharding / caching must avoid any single hot shard (e.g., top of global board or celebrity profiles) becoming a bottleneck.
• System scales horizontally by adding nodes, not by vertically beefing up a single box.

High Level Design

FR1 – Ingest & Update Player Scores

API (Abstract)

We'll assume the game backend calls us after each match.

1. Endpoint (abstract)

POST /leaderboards/{leaderboard_id}/players/{player_id}/score
Content-Type: application/json

{
  "new_score": 12345,
  "match_id": "match-uuid-123",  // idempotency key
}

1. Response (example)

{
  "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
}

Core Entities

1. leaderboards

• Describes one concrete leaderboard: game + mode + region + season + time window.
• Tells us where a score update should go and whether that leaderboard is active.
• Encodes score policy so we know we're in the HIGH_SCORE world (monotonic best-score).

2. score_events (append-only log of raw updates)

• Logs every match event that tried to update a leaderboard.
• Useful for audit, debugging, and later replay / rebuild if needed.
• Enforces uniqueness on (leaderboard_id, player_id, match_id) so the same match can't be ingested twice.

3. leaderboard_scores (canonical per-player state)

• Holds the current visible score per (player, leaderboard).
• This is the row all future FRs will query for:
  • My score, my rank, K neighbors, top-N, etc.
• Encodes the HIGH_SCORE, monotonic semantics and idempotency.

Workflow

Step 1 - Match service sends score update

• After a match, the match service POST the leaderboard_id, player_id, match_id, new_score to API-GW.

Step 2 - API-GW routes to Score Ingestion Service

• API-GW does auth / basic validation and forwards the request to the Score Ingestion Service.

Step 3 - Score Ingestion validates leaderboard & logs event

• Checks that the leaderboard_id exists and is ACTIVE.
• Inserts a row into score_events (leaderboard_id, player_id, match_id, new_score, event_ts).
• The unique index on (leaderboard_id, player_id, match_id) enforces idempotency (duplicate match → treated as retry).

Step 4 - Apply HIGH_SCORE rule using leaderboard_scores

• Reads current row for (leaderboard_id, player_id) from leaderboard_scores.
• If match_id == last_match_id → retry, no change.
• Else if new_score <= current score → not a new high score, no change.
• Else → update leaderboard_scores with score = new_score, last_match_id = match_id, last_update_ts = now().

Step 5 - Respond back to match service

• Score Ingestion Service returns final score, previous_score, last_match_id, and update_applied = true/false → API-GW → match service.

Design Diagram

Click to expand