Leaderboard walk-through: score events, a derived sorted set and rebuildable rankings

Goal

Rank members by score with fast top-N and "my rank" queries, per-period boards, and rankings that can be rebuilt from an event history when the ranking store is lost.

Prerequisites

A definition of the score per board (best single result, running sum, or latest value), a tie rule, board periods (all-time, weekly, daily), and a server-side path that produces scores; clients never submit scores directly.

Steps

1. Constraints: score submission is server-authoritative; rank queries dominate; a period board closes at a fixed time; the ranking store is a cache and the events are the truth.
2. Components: a score event writer; an updater that applies events to a sorted structure per board; a query API (top N, rank and score of one member, neighbours around a rank); a period roller that opens and closes boards; a rebuild job.
3. Data model: score_event(id, board, member, value, occurred_at, source, idempotency_key unique); board(id, period_start, period_end, aggregation, tie_rule, closed_at); derived: one sorted set per board keyed by member with the aggregated score. The Redis documentation describes sorted sets with rank lookups at O(log(N)) in the number of elements and names leaderboards as a use.
4. Ties: a sorted set orders equal scores by member string, which is arbitrary for users; encode the tie rule into the score (for example score * K - seconds_since_period_start for "earlier wins", with K above the period length in seconds and the result inside the exact integer range of a double) or resolve ties in the query layer for the visible page only.
5. Aggregation: "best result" keeps the maximum, "sum" increments, "latest" overwrites; fix one per board, because a rebuild must reproduce the same values from events.
6. Failure modes: duplicate events after a retry (the unique idempotency key rejects them before the updater); ranking store loss (rebuild from events, current period first, since boards are independent); a period boundary crossed while events are in flight (route by occurred_at, not arrival); a global board with millions of members (top N and single rank stay cheap, percentile bands are approximated later); cheating (validate scores against the rules server-side, keep source for audit).
7. Measure: event-to-visible lag, rank query latency, rebuild time per board, duplicate events rejected, disputes per period.
8. Not first: friends and regional boards, historical snapshots, real-time push of rank changes, reward logic.

Expected result

Top-N and single-member rank queries answer from the sorted structure, a lost board is rebuilt from events with identical results, and a period closes deterministically.

Limits and test basis

Proposed design, no measurements. An in-memory sorted structure grows with members per board; the design assumes boards bounded by period or sharded by region.