Leaderboard

A leaderboard ranks buddies by a scoring function over a window. It's optional — not every product benefits from ranking, and ranking can be stressful. When it fits, though, it's a strong pull.

What defines a leaderboard

• Metric — coins earned, skills-leveled, streaks completed, a custom sum.
• Window — all-time, monthly, weekly, custom cohort.
• Scope — global (across all buddies of the customer), per-audience, or per-group (classroom, team, etc.).
• Visibility — public to all, visible only to the buddy's own rank ±3 entries, or admin-only.

Example

Weekly coin leaderboard, scoped to the students audience. Resets every Monday. Each student sees their own rank plus the five nearest neighbours; admins see the full list.

How it computes

Leaderboards are computed on demand and served from a read-through cache with a 5-minute (300s) TTL. The first read after the cache expires runs the live aggregate and stores the result; subsequent reads within the window hit the cache, not the live query — this keeps performance stable regardless of scale.

Gotchas

• Leaderboards can demotivate the bottom ranks. Consider scoping visibility to "within ±N of me" rather than the whole list.
• Per-group leaderboards require you to pass a groupId on events; without it, the event doesn't count toward group ranking.
• Weekly/monthly windows reset in UTC. Cross-timezone products may see a sudden "reset" mid-day for some users.

Related

• Audiences — scope a leaderboard to one user group.
• Streaks — a common leaderboard metric.
• Leaderboard widget — rendering it in your product.