Development of a Leaderboard for Mobile App Gamification

Note: when you have thousands of users, a plain ORDER BY score DESC starts killing the database. We've encountered this in projects for FinTech and EdTech clients — delays grew to 5 seconds, and users complained about lag. For real-time ranking among a million users, we use Redis with special data structures. In this article, we share architectural solutions proven on dozens of projects. A well-designed leaderboard is one of the most effective tools for boosting engagement. But implementation approaches vary greatly depending on scale and requirements. Implementation mistakes can lead to high latency and poor user experience.

We consider three main categories: up to 10,000 users, from 10,000 to one million, and over one million. For each case, there is an optimal stack and configuration. We use Redis with AOF persistence for reliability, and separate keys with TTL for periodic leaderboards. It's also important to define the leaderboard type: global, periodic, social, or 'around me' — each solves its own motivation tasks.

And don't forget about UX: animations, avatar caching, and smooth rank updates are critical for perception. In this material, we focus on technical details and best practices that help avoid common mistakes. On the client side, we use image caching and incremental list updates.

Choosing Technology for a Leaderboard Based on Scale

Up to 10,000 users: PostgreSQL with RANK() / DENSE_RANK() window functions. A paginated query runs fast even without special indexes. We cache the top 100 in Redis with a 5-minute TTL.

10,000 – 1,000,000 users: Redis Sorted Sets (ZADD, ZRANK, ZREVRANK, ZREVRANGE). Adding scores: ZADD leaderboard:global NX <score> <user_id> or ZINCRBY leaderboard:global <delta> <user_id>. Getting user rank: ZREVRANK leaderboard:global <user_id> — O(log N). Top 100: ZREVRANGE leaderboard:global 0 99 WITHSCORES — O(log N + 100). This works without degradation even on a million users.

Millions of users: Sharding Redis Sorted Sets by time periods and regions. A global leaderboard becomes an unattainable goal for most — demotivating. Better to segment.

Types of Leaderboards and Their Characteristics

Time Periods for Leaderboards

Global 'all time' — for top players. Weekly and monthly — for everyone else. Reset at the beginning of a period: don't delete data, archive it. The user should see their past results.

Reset implementation: separate key for each period leaderboard:weekly:YYYY-WW, leaderboard:monthly:YYYY-MM. When the period expires, create a new key — the old one remains for history. TTL on old keys: 30 days for weekly, 90 for monthly.

Why the 'Around Me' Leaderboard Boosts Engagement?

The most useful type for the average user. Not 'top-100', but 'you are at position 4573, here are 5 people above and 5 below'. Motivates those who will never make the top.

Implementation on Redis: ZREVRANK to get user rank, then ZREVRANGE(rank-5, rank+5) for neighboring positions. An additional query to PostgreSQL to get display name and avatar by user_id from the result.

Social Leaderboards

Leaderboard among friends often motivates more than global. Implementation is trickier: there's no point in a global sorted set for a list of 50 friends.

Option 1: When opening the screen, query PostgreSQL: SELECT user_id, score FROM user_scores WHERE user_id IN (:friends_list) ORDER BY score DESC. Works for a small number of friends (up to 200).

Option 2: A separate sorted set for each user leaderboard:user:<user_id>:friends — update whenever any friend's score changes. More memory expensive in Redis (about 1.5x), but instant reads.

Display and UX

Highlighting the current user's position in the list is a must. Animated rank update when getting new scores (ScrollTo + highlight). Growth/decline arrows next to position — 'you rose 12 places today'. Historical rank curve for the period.

On Flutter: AnimatedList for smooth updates. On iOS: UITableView with performBatchUpdates. On Android: RecyclerView with DiffUtil. Don't reload the entire list on update — only changed cells (3-5 on average).

Avatars in the leaderboard — cache aggressively. SDWebImage (iOS) / Glide (Android) / cached_network_image (Flutter) with disk cache (up to 50 MB). Don't show leaderboard without names and avatars — only skeleton during loading.

Turnkey Leaderboard Development Process

1. Analysis and architecture: study requirements, choose stack (Redis + PostgreSQL), design API.
2. Backend implementation: configure Redis Sorted Sets, develop endpoints for rank and top.
3. Client side: integrate on iOS (Swift), Android (Kotlin) or Flutter with animations and caching.
4. Integration with authentication system: link to existing user database.
5. Documentation and testing: load testing (up to 10,000 RPS), check real-time performance.
6. Deployment and support: deploy on servers, one month of free maintenance.

What's Included

• Architecture and API documentation
• Access to repository with source code
• Deployment and setup instructions (including Redis configs)
• Team training on leaderboard operation
• One month of technical support after launch

Our Experience

We have been developing mobile applications with gamification for over 5 years. Our portfolio includes 50+ projects, including leaderboards for fintech, edtech, and gaming apps. We guarantee stable operation under load up to 10 million users. — Mobile Development Team

# redis.conf save 900 1 save 300 10 save 60 10000 appendonly yes appendfsync everysec