Design Real Time Gaming Leaderboard
What is a Real-Time Leaderboard?
A real-time leaderboard is a system that tracks and ranks users or entities based on scores, achievements, or performance metrics as they update in real time.
Examples include leaderboards in online games, fitness apps, or platforms like Kaggle competitions. Users expect their ranks and positions to update instantly as new scores are submitted.
In a real-time leaderboard, updates happen almost instantly:
- A player’s score changes (e.g., after scoring a point or defeating an opponent).
- The system updates that player’s rank immediately.
- Other players can see the updated position without waiting or refreshing.
This real-time aspect makes the user experience more dynamic and engaging.
However, it also introduces significant technical challenges, such as:
- Efficiently retrieving Top-N players (e.g., Top 10 or Top 100).
- Allowing players to quickly find their own rank without scanning the entire leaderboard.
In this chapter, we will walk through the high-level design of a real-time leaderboard system.
Let’s begin by clarifying the requirements.
1. Requirements
Before diving into the design, lets clearly define the functional and non-functional requirements of our real-time gaming leaderboard..
Functional Requirements
- Top-N Queries: Display top N players (e.g., top 10, top 100) on the leaderboard and update it in real-time.
- Player’s Own Rank: Allow a player to query their current rank without scanning the entire leaderboard.
- Nearby Rank Queries: Provide the ability to retrieve a “slice” of the leaderboard around a specific player (e.g., ranks 45 to 55 if the player is rank 50).
- History Tracking: Players can view past game scores and historical leaderboards for previous matches.
Non-Functional Requirements
- Real-time updates: Score changes should reflect immediately in the leaderboard.
- Low latency: Leaderboard queries should return the results in milliseconds.
- High Concurrency: System should support thousands of concurrent players submitting scores and fetching rankings.
Approach to Designing the System
The most challenging aspects of building a real-time leaderboard is database design. Choosing the right storage system is critical to ensuring that queries can be executed efficiently without performance bottlenecks.
To simplify the design process, we will follow below approach:
- Start with API Design: Clearly define the input/output structure of leaderboard queries and updates.
- Define the High-Level Architecture: Identify core system components and their interactions.
- Database Design: Choose the appropriate storage model optimized for fast leaderboard lookups and real-time updates.
2. API Design
To support real-time leaderboard operations, we define a set of RESTful APIs that allow players to update scores, retrieve rankings, and query nearby ranks efficiently.
2.1 Score Update
Updates a player's score incrementally.
Endpoint: POST /leaderboard/score/update
Request Body (JSON):
Assumption: We will use relative score updates (
scoreDelta) rather than absolute updates.
Response (JSON):
2.2 Get Top-N Players
Retrieves the top-N players from the leaderboard, ranked by their scores.
Endpoint: GET /leaderboard/top?n=10
Query Parameter: n = number of top players to fetch (default 10, max 100, etc.)
Response (JSON):
2.3 Get Player Rank
Allows a player to retrieve their current rank without scanning the entire leaderboard.
Endpoint: GET /leaderboard/rank/{playerId}
Response (JSON):
2.4 Get Nearby Ranks
Retrieves players ranked around a given player, allowing for comparison with competitors of similar skill levels.
Endpoint: GET /leaderboard/nearby/{playerId}?range=5
Query Param: range indicates how many ranks above and below to fetch (e.g., 5 above, 5 below).
Response (JSON):
Example: If a player is ranked 50th, this API allows them to see players ranked 45-55 for a competitive comparison.
2.5 WebSockets for Real-Time Updates
While REST APIs are good for on-demand queries, WebSockets or Server-Sent Events (SSEs) can push real-time leaderboard updates to subscribed users.
Players would subscribe to leaderboard updates, and receive updates instantly without polling.