DEV Community: Charlie Brinicombe

The Gamification Data Model: How to Structure Streaks, Achievements, Points & Leaderboards

Charlie Brinicombe — Sun, 19 Apr 2026 22:33:10 +0000

The individual technical challenges of building gamification features are well documented at this point. Streak logic requires timezone-aware calendar evaluation, not 24-hour arithmetic. Leaderboards at scale require Redis sorted sets, per-segment key management, and atomic period resets. Achievement backfill requires idempotent scripts against event history, not denormalized totals. These are solvable problems, and teams who've understood them have a clear path through each one.

What's less documented is the data model problem that sits underneath all of them. Each feature, solved correctly in isolation, still leaves you with four separate systems — streak state in one table, achievement completions in another, points in a third, leaderboards driven by Redis — connected by glue code.

The moment you want an achievement that triggers when a user reaches a streak milestone, or a points boost that only applies to a specific user cohort, or a leaderboard that ranks by points balance rather than raw activity, you're writing across those systems. The integration points are where bugs live, where performance degrades, and where the features you didn't build upfront become expensive to add.

This post describes what a unified gamification data model looks like in practice, starting with the event layer that ties everything together, then the per-feature config and state models that Trophy has built and operated at scale.

The Event Layer: One Pipeline for Everything

The architectural decision that shapes everything else is where gamification logic lives relative to your event stream. In most custom implementations, features are added incrementally: you build streak logic that fires when a user logs activity, then add achievement checks to the same handler, then wire up points awards, then start a separate cron job for leaderboard updates. The result is a set of interconnected side effects on a single event that's easy to reason about when there are two features and increasingly brittle as the number grows.

Trophy's model inverts this. Every user interaction flows through a single metric event: a lesson completed, a workout logged, a task checked off. Trophy evaluates that event against all configured gamification features simultaneously and produces a unified response containing the state changes across all of them:

// One event — Trophy evaluates streaks, achievements, points, and leaderboards
const response = await trophy.metrics.event('lessons_completed', {
  user: { id: userId, tz: 'America/New_York' },
  value: 1,
});

// Everything that changed as a result of this single event
response.currentStreak // streak state after this event
response.achievements // any achievements unlocked by this event
response.points // points awarded by this event, across all systems
response.leaderboards // updated leaderboard positions after this event

The response isn't a polling result — it's the transactional outcome of evaluating one event against the full gamification configuration. Nothing is eventually consistent from the application's perspective: the streak has already been evaluated, the achievements have already been checked, the points have already been awarded, and the leaderboard positions have already been updated by the time the response returns.

This matters for the data model because it means every gamification record is traceable to the originating event. An achievement completion, a points award, a streak extension — each has a foreign key to the metric event that caused it. The event ledger is the canonical source of truth for everything downstream.

Streaks: Config and Period State

A streak in Trophy is not a counter. It's a series of period records, each with a start date, an end date, a length, and an outcome.

The config layer holds everything that determines how a streak is evaluated: frequency (daily, weekly, monthly), the metrics and thresholds that constitute a qualifying action, how multiple metrics are combined (ALL vs OR logic), freeze settings (initial grant, accumulation rate, maximum). This config is what makes it possible to change streak requirements without touching application code — adding a second qualifying metric, adjusting the threshold, switching from daily to weekly — all as config changes that take effect on the next event.

The period layer is where the history lives. Each streak period is a row:

streak_periods
  user_id
  period_start -- local calendar date in user's timezone
  period_end -- local calendar date in user's timezone
  length -- streak count at close of this period
  outcome -- extended | broken | frozen
  closed_at -- UTC timestamp when the period was finalised

This is the record that makes streak restoration a data operation rather than a guess, that powers longest-streak badges without table scans, and that enables the streak history calendar view without storing anything extra.

The freeze ledger is a separate table where every grant and every consumption is a row:

streak_freeze_events
  user_id
  event_type -- granted | consumed
  created_at -- UTC timestamp
  reason -- initial_grant | accumulation | manual

Freeze support isn't a feature you add to this model — it's a natural extension of modelling streak state as events rather than a counter. A freeze consumption is just a period outcome of frozen with a corresponding consumed row in the freeze ledger. The balance is always derivable by summing the ledger; there's no separate count to go stale.

The timezone handling described in Streak Timezone & DST Handling is baked into the period model at the schema level: period_start and period_end are local calendar dates, not UTC timestamps. DST transitions don't affect period boundaries because calendar dates don't have lengths in hours.

Achievements: Config, Progress, and Completions

Achievement data separates into three distinct concerns.

The config layer defines what an achievement is and when it triggers. Trophy supports four trigger types — metric threshold, streak length, API call, and composite — and each config row references the relevant entity (a metric key, a streak frequency, prerequisite achievement IDs). Config rows also carry attribute filters: a subject:physics filter on a metric achievement means the achievement only fires for metric events from users with that attribute, without any application-layer branching.

Achievement status (inactive, active, locked, archived) is part of config, and the status transition is what drives automatic backdating. When Trophy moves an achievement from inactive to active, it evaluates every existing user's metric totals and streak history against the achievement condition and creates completion records for qualifying users in bulk — the backfill happens automatically, and the achievement.completed webhook is suppressed for backdated completions to prevent notification floods. The full mechanics of this are covered in How to Backfill Achievements for Existing Users.

The progress layer tracks how far a user is toward each metric achievement's threshold:

achievement_progress
  user_id
  achievement_id
  current_value -- derived from the user's metric total
  threshold -- copied from config at progress record creation
  pct_complete -- precomputed, updated on each metric event

This is updated as a side effect of metric events, not computed on demand. A progress bar query is a single row lookup, not an aggregate against the full event history.

The completion layer is an append-only ledger:

achievement_completions
  id
  user_id
  achievement_id
  completed_at
  trigger_event_id -- the metric event or API call that caused this
  backdated -- boolean

Completion records are never updated — they're facts. The trigger_event_id foreign key means every completion is traceable to the originating event, which makes it possible to audit why a user received an achievement, replay the evaluation for debugging, and correctly handle the idempotent re-runs described in the backfill post.

Rarity (the percentage of users who have earned each achievement) is maintained as a precomputed field on the config row, updated incrementally as completion records are created rather than computed as an expensive aggregate at display time.

Points: Ledger, Triggers, Boosts, and Levels

Points are the most compositionally complex feature because they sit at the intersection of every other feature. Points can be awarded when a metric threshold is reached, when a streak milestone is hit, when an achievement is completed, on a time schedule, or at user signup. The data model has to represent all of these trigger types cleanly and produce an audit-proof award history.

The system config layer defines each points currency: key, name, display badge, and optional cap. Trophy supports multiple independent systems per app — XP and gems, for example — and each system has its own trigger configuration and ledger. The multi-currency case isn't a special case in the schema; it's just multiple rows in the systems table.

The trigger config layer defines the rules for each system. Each trigger is a row with a type, a reference to the triggering entity (a metric key and threshold, a streak length, an achievement ID, a time interval), a points value, an active/inactive status, and optional user attribute filters. The attribute filters on triggers are what make cohort-specific points rates possible — premium users earn 2× points for lesson completions, free users earn 1× — without any application-layer branching.

The award ledger is the canonical source of truth:

points_awards
  id
  user_id
  points_system_id
  amount -- net points after boost multiplication
  base_amount -- pre-boost amount, for audit
  boost_multiplier -- the combined multiplier active at award time
  trigger_id -- which trigger config row fired
  source_event_id -- the originating metric event, achievement, etc.
  awarded_at

amount and base_amount are separate columns because boost audit matters. When a user queries their points history and sees an award of 20 points, the award record shows that the base amount was 10 and the boost multiplier was 2.0. You can always reconstruct what the user saw, which is important for support tickets and for understanding the impact of past boosts.

The boost layer is a config table with time windows and multiplier values:

points_boosts
  id
  points_system_id
  multiplier
  rounding_mode -- floor | ceil | nearest
  starts_at
  ends_at
  user_attribute_filters -- JSON; null means global
  status

When a points award is created, Trophy evaluates every active boost applicable to the user and multiplies them together. The combined multiplier is stored on the award record. Boost stacking (a 2× global boost and a 1.5× personal boost producing a 3× combined multiplier) is a consequence of the multiplicative evaluation rule, not special-case logic.

Points boosts are the clearest example of a feature the data model either supports structurally or requires a redesign to add. A schema that stores points as a simple total plus a list of events has no natural place for "what multiplier was active when this award was created." Trophy's ledger carries this from the start.

The levels layer stores threshold configuration:

points_levels
  id
  points_system_id
  key
  name
  threshold
  badge_url

A user's current level is determined by finding the highest threshold their current balance clears. Trophy evaluates this on every points change and fires a points.level_changed webhook when the level transitions — the event payload contains both the previous level and the new level, so the application knows exactly what changed without querying current state separately.

Leaderboards: Config, Segments, and Rank History

The technical complexity of leaderboard infrastructure — Redis sorted set management, segment key explosion, atomic period resets — is covered in Scaling App Leaderboards: Redis Architecture and Where Trophy Fits. The data model question is distinct: even if you solve the infrastructure, what do you store and how?

The config layer defines each leaderboard: ranking method (metric, points, or streak), period type (perpetual or repeating), participant limit, and breakdown attributes. Breakdown attributes are the config-level representation of segmentation — a city breakdown attribute means Trophy automatically maintains a separate leaderboard segment for every distinct city value in the user base. The segments are not explicitly provisioned; they emerge from the attribute values Trophy has seen.

The rankings layer is the live sorted state, maintained in Redis. Every leaderboard has one sorted set per active segment, updated as metric events arrive. The Redis infrastructure and the reasoning for it are detailed in the leaderboard scaling post — the schema point is that this is ephemeral optimized storage, not the record of what happened.

The rank history layer is where Trophy diverges sharply from a custom implementation:

leaderboard_rank_events
  id
  leaderboard_id
  segment_key -- NULL for global, attribute:value for segments
  user_id
  previous_rank
  new_rank
  occurred_at

Every rank change for every participant, in every segment, is a row. This table is what makes leaderboard.rank_changed webhooks possible without polling: Trophy inserts a row, fires the webhook, and delivers the previous and new rank in the payload. It's also what makes "you were #3 in your city last week" queries possible without reconstructing history from raw events.

The period archive layer stores the final rankings when a repeating leaderboard period closes:

leaderboard_period_archives
  id
  leaderboard_id
  segment_key
  period_start
  period_end
  rankings -- JSON array of {userId, rank, value}
  finalised_at

Period archives are the queryable history of every leaderboard run. The leaderboard finalization process — evaluate all users across all timezones, wait for the last timezone to pass midnight, archive the final state, reset the live sorted set, fire leaderboard.finished — writes to this table atomically before clearing Redis. If you query a historical leaderboard run through the API, you're reading from this archive, not reconstructing from events.

Cross-Feature References: Where Custom Models Break Down

The individual models above are each technically achievable in a custom implementation. The harder problem is the foreign keys between them.

A points trigger that fires on streak milestone completion references both the points system config and the streak config. A composite achievement references the completion records of its prerequisite achievements. A leaderboard ranked by points balance references the points award ledger to determine participant scores. A points.level_changed event needs to fire when a points award causes a threshold crossing, which means the award write and the level evaluation happen in the same transaction.

In Trophy, these cross-feature references are structural — the foreign keys exist in the schema, and the evaluation logic that traverses them runs inside the same transactional boundary as the originating event. In a custom implementation, the equivalent is glue code: explicit queries from the achievement handler to the streak state table, explicit calls from the points award function to the level check function, explicit webhook dispatches after each state change. Each piece of glue is a place where something can go wrong silently, run in the wrong order, or produce inconsistent state under concurrent updates.

The features that are hardest to add to a custom implementation later — streak freezes, points boosts, composite achievements, rank-change notifications — are all features that require new cross-feature references. Streak freezes need the freeze ledger to reference streak periods. Points boosts need the award record to reference the active boost config. Composite achievements need a prerequisite graph traversal at evaluation time. Rank-change notifications need the rank history table to be populated atomically with the sorted set update.

These aren't design oversights — they're features teams typically don't know they want until they've shipped without them. Trophy's schema carries them from the start because they were always part of the model, not added later.

FAQ

If Trophy stores all this state, what do I own in my own database?

Your application data — user records, content, purchases, the things that make your product what it is. Trophy stores the gamification state that's derived from the events you send. The two are linked by user ID. You don't need to replicate gamification state into your own schema — you read it from Trophy's API as needed, or receive it in webhook payloads as it changes.

How does Trophy handle high event volumes without the points and achievement checks becoming a bottleneck?

The evaluation pipeline is designed for throughput, not just correctness. Achievement progress updates are async; the metric event response includes achievement completions that have already crossed the threshold, but progress increments for achievements not yet complete are written behind the response. Points awards, leaderboard updates, and streak evaluations are synchronous in the critical path because they affect the response the application receives. The distinction between what must be consistent on return and what can be eventually consistent is baked into the evaluation order.

Can I have one metric trigger achievements in one system and points in another simultaneously?

Yes. A single metric key can be referenced by multiple achievement configs and multiple points trigger configs, across multiple points systems. When an event arrives, Trophy evaluates all of them. The response contains the union of everything that changed — streak extension, achievement completions, points awards across all applicable systems, leaderboard position updates.

What happens if I add a new achievement or a new points trigger to users who already have existing history?

For metric and streak achievements, Trophy backdates automatically when you activate them — any user whose current totals meet the threshold receives the completion. For new points triggers, previously recorded events are not retroactively re-evaluated; the trigger applies from activation forward. If you need to award points to existing users for past activity, the Admin API allows creating point award records directly.

Where to Go Next

The per-feature technical challenges that motivate this data model are covered in detail across the series: Streak Timezone & DST Handling, Scaling App Leaderboards Beyond Basic Redis, and How to Backfill Achievements for Existing Users. The full configuration reference for each feature is in the Trophy documentation: Streaks, Achievements, Points, and Leaderboards.

Streak Timezone & DST Handling: The Complete Implementation Guide

Charlie Brinicombe — Sun, 19 Apr 2026 11:38:25 +0000

Streak bugs from timezone mishandling are the most common category of support tickets for consumer apps with a global user base. A user in Sydney completes their lesson at 11:55 PM local time. Your server is running on UTC, which makes it tomorrow. The streak breaks. The user is correct that they acted within the day. Your code is also technically correct. The problem is that both "days" refer to different things, and there is no graceful failure — the streak just disappears.

The fix is not complicated in principle, but the implementation has enough sharp edges that most teams get it wrong at least once in production. This post covers the correct approach to UTC storage and local-time evaluation, the two DST cases that will catch you even if you do everything else right, the per-user midnight scheduling problem, and what happens when users travel. At the end, there's a short section on how Trophy handles all of it so you understand what you're getting if you use the platform.

Why UTC Streak Logic Breaks

The naive approach to streak evaluation compares UTC timestamps:

// Broken: compares UTC dates, not the user's local dates
function didUserActToday(lastActivityAt: Date): boolean {
  const now = new Date();
  return (
    now.getUTCFullYear() === lastActivityAt.getUTCFullYear() &&
    now.getUTCMonth() === lastActivityAt.getUTCMonth() &&
    now.getUTCDate() === lastActivityAt.getUTCDate()
  );
}

For a user in UTC+10, this produces the wrong answer for the last ten hours of every calendar day. Their local "today" started at 2:00 PM yesterday UTC, but getUTCDate() still says yesterday until midnight UTC. Their activity from 2:00 PM to midnight local time is treated as belonging to the previous day on the server.

A slightly less naive version checks "within the last 24 hours" rather than comparing calendar dates:

// Still broken: fixed-duration arithmetic doesn't match calendar days
function didUserActYesterday(lastActivityAt: Date): boolean {
  const twentyFourHoursAgo = Date.now() - 24 * 60 * 60 * 1000;
  return lastActivityAt.getTime() > twentyFourHoursAgo;
}

This version fails on DST transitions, which are covered below, and also fails for any streak logic that needs to match calendar days rather than rolling 24-hour windows.

The root cause in both cases is the same: streak periods are calendar constructs (a "day" is midnight to midnight in some timezone), and calendar constructs require timezone context to evaluate correctly.

The Correct Foundation: Store UTC, Evaluate Locally

All timestamps go into your database as UTC. This is not optional — mixing timezone-local timestamps in storage creates a different class of problems that are harder to fix. The timezone awareness lives at evaluation time, not storage time.

The correct period boundary check converts both "now" and the last activity timestamp into the user's local calendar date, then compares calendar dates:

import { toZonedTime, format } from 'date-fns-tz';

// Get the local calendar date string for a UTC timestamp in a given timezone
function toLocalDate(utcDate: Date, ianaTimezone: string): string {
  const zoned = toZonedTime(utcDate, ianaTimezone);
  return format(zoned, 'yyyy-MM-dd', { timeZone: ianaTimezone });
}

// Check whether a user's last activity falls on the local calendar day
// immediately before today — i.e. they completed yesterday's period
function completedYesterday(
  lastActivityAt: Date,
  ianaTimezone: string
): boolean {
  const todayLocal = toLocalDate(new Date(), ianaTimezone);
  const activityLocal = toLocalDate(lastActivityAt, ianaTimezone);

  // Build yesterday's date string by subtracting one day from today
  const yesterday = new Date();
  yesterday.setDate(yesterday.getDate() - 1);
  const yesterdayLocal = toLocalDate(yesterday, ianaTimezone);

  return activityLocal === yesterdayLocal;
}

// Full streak evaluation: did the user act today or yesterday?
function evaluateStreak(
  lastActivityAt: Date | null,
  ianaTimezone: string
): 'extended' | 'maintained' | 'broken' {
  if (!lastActivityAt) return 'broken';

  const todayLocal = toLocalDate(new Date(), ianaTimezone);
  const activityLocal = toLocalDate(lastActivityAt, ianaTimezone);

  const yesterday = new Date();
  yesterday.setDate(yesterday.getDate() - 1);
  const yesterdayLocal = toLocalDate(yesterday, ianaTimezone);

  if (activityLocal === todayLocal) return 'extended';
  if (activityLocal === yesterdayLocal) return 'maintained';
  return 'broken';
}

Two things to note about this pattern. First, the timezone parameter must be an IANA identifier (America/New_York, Europe/London, Asia/Tokyo), not a UTC offset string like +05:30. UTC offsets don't encode DST rules, which means they'll produce the correct output most of the year and silently wrong output twice a year. Store and use IANA identifiers throughout.

Second, date-fns-tz is the recommended library for this in Node.js. Intl.DateTimeFormat can do the same job but the API is less ergonomic for this specific use case. Avoid moment-timezone for new code — it is in maintenance mode and the bundle size is significant.

DST: The Two Cases That Will Catch You

Daylight saving time creates two categories of non-standard days per year in every region that observes it. Both break 24-hour arithmetic while leaving calendar-day comparison correct.

Spring forward. Clocks jump from 2:00 AM to 3:00 AM. The local calendar day is only 23 hours long. A user who was active at 11:00 PM the previous night has 22 hours to repeat their activity before their "today" ends, not 24. Any system that evaluates "has 24 hours passed since last activity" will require action one hour earlier than expected on this day. Users who act at their normal time — say, 10:30 PM — will find that 23 hours has passed since the previous night's activity, which is less than 24, so the check passes. But users who rely on acting during that missing hour (2:00 AM to 3:00 AM, which simply doesn't exist) face a period that is shorter than their normal pattern.

Fall back. Clocks repeat the 1:00 AM to 2:00 AM hour. The local calendar day is 25 hours long. A 24-hour arithmetic check run at midnight local time will show that only 23 hours have elapsed since the previous midnight, because the local clock lagged UTC by one extra hour during the repeat. If you evaluate "did the user act in the last 24 hours" at midnight on fall-back day, the check passes even if the user acted 25 hours ago.

Calendar-day string comparison sidesteps both problems completely. '2026-03-29' !== '2026-03-28' is true regardless of how many hours exist between the two dates. The length of a DST day doesn't affect whether two dates have different local calendar strings.

The one edge case to test explicitly: an activity that occurs during the repeated hour on fall-back day will produce a local time that appears to occur twice. date-fns-tz handles this correctly using the IANA timezone data, which encodes the precise UTC offset at each moment. Test this by creating a UTC timestamp for 01:30 AM UTC on a fall-back date and verifying your toLocalDate function returns the correct local date string for a timezone observing the transition.

The Per-User Midnight Evaluation Problem

Most streak systems need to evaluate at some point whether a user's streak should be broken — typically triggered at the end of each day if no activity occurred. The obvious implementation is a cron job:

// Naive: runs once at UTC midnight, wrong for everyone not in UTC
cron.schedule('0 0 * * *', async () => {
  const users = await db.query('SELECT * FROM users');
  for (const user of users) {
    await evaluateAndBreakStreakIfNeeded(user);
  }
});

This evaluates all users at UTC midnight, which is midnight for users in UTC+0 and noon for users in UTC+12. Those users won't have their streak state updated until twelve hours into their next local day.

The correct approach is either to evaluate lazily or to schedule per-timezone. Lazy evaluation is simpler and usually sufficient:

// Lazy evaluation: check streak state when the user next interacts,
// rather than on a schedule
async function handleUserActivity(userId: string, ianaTimezone: string) {
  const user = await db.getUser(userId);
  const streakState = evaluateStreak(user.lastActivityAt, ianaTimezone);

  if (streakState === 'broken') {
    await db.resetStreak(userId);
  } else if (streakState === 'extended') {
    await db.incrementStreak(userId);
    await db.setLastActivity(userId, new Date());
  }
  // 'maintained' — no action needed, streak is still live
}

Lazy evaluation has one limitation: users who don't open the app won't have their streak broken until their next interaction, which means stored streak values can be stale for inactive users. For display purposes this usually doesn't matter. For analytics and leaderboard data, you may need a scheduled fallback that evaluates stale users once per day, bucketed by timezone.

The scheduled-per-timezone approach processes users at their local midnight:

// Group users by timezone and schedule a job for each timezone's midnight
async function schedulePerTimezoneEvaluation() {
  const timezones = await db.getDistinctTimezones();

  for (const tz of timezones) {
    const midnight = getNextLocalMidnight(tz); // returns a UTC Date
    const delay = midnight.getTime() - Date.now();

    setTimeout(async () => {
      const users = await db.getUsersByTimezone(tz);
      for (const user of users) {
        await evaluateAndBreakStreakIfNeeded(user.id, tz);
      }
      // Reschedule for the next local midnight
      scheduleForTimezone(tz);
    }, delay);
  }
}

At scale this becomes a queue problem rather than a cron problem — you're processing millions of per-user evaluation events distributed across 24 hours. The architectural pattern shifts to a job queue (BullMQ, SQS) where each user has a job scheduled for their next local midnight, rescheduled on completion.

When Users Travel

A user flying from London to Los Angeles crosses several timezones. Their streak should follow their current location, not lock to origin. Handling this correctly requires two things: updating the stored timezone when it changes, and deciding what to do about the gap.

The gap is the interesting part. If a user is in London at 11:00 PM (one hour before their streak period ends), boards a flight, and lands in Los Angeles where it's 2:00 PM local time, their "today" just got longer. If you update their timezone on landing, their remaining period is now ten hours rather than one. That's fairer to the user.

The implementation is straightforward: call evaluateStreak with the user's current timezone on every interaction, and update the stored timezone when it changes:

async function handleUserActivity(
  userId: string,
  currentTimezone: string // from device or explicit user setting
) {
  const user = await db.getUser(userId);

  // Update timezone if it changed — streak evaluation will use the new one
  if (user.ianaTimezone !== currentTimezone) {
    await db.updateTimezone(userId, currentTimezone);
    user.ianaTimezone = currentTimezone;
  }

  const streakState = evaluateStreak(user.lastActivityAt, user.ianaTimezone);

  if (streakState === 'broken') {
    await db.resetStreak(userId);
  } else if (streakState === 'extended') {
    await db.incrementStreak(userId);
    await db.setLastActivity(userId, new Date());
  }
}

The international date line is the genuinely tricky case. A user crossing from UTC+12 to UTC-12 skips a full calendar day according to local time. Using calendar-day string comparison as the evaluation method means this creates an apparent two-day gap with no activity, which would break the streak even though the user only missed one local sleep cycle.

There's no universally correct answer. For most apps, documenting the behaviour and handling support tickets individually is the pragmatic approach. The edge case affects an extremely small number of users.

How Trophy Handles This

Trophy's streak logic operates entirely in the user's local timezone. You pass the user's IANA timezone identifier on each metric event:

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

await trophy.metrics.event('lessons_completed', {
  user: {
    id: userId,
    tz: 'America/Los_Angeles', // IANA identifier from device or user settings
  },
  value: 1,
});

The tz field updates Trophy's stored timezone for the user on every event, so timezone changes from travel are handled automatically on the next interaction. Trophy evaluates streak periods using calendar-day comparison in the user's timezone, which means DST transitions — spring forward and fall back — don't break streaks for users in affected regions.

Once setup, displaying streak data on app load or a profile screen with Trophy is simple, just call the user streak API directly:

const streak = await trophy.users.getStreak(userId);

// streak.length — current streak count
// streak.expires — UTC timestamp when the period closes;
// convert to local time to show "expires at 11:59 PM"
// streak.periodStart — start of the current period
// streak.periodEnd — end of the current period
// streak.streakHistory — past periods, use historyPeriods param to control depth

console.log(`Current streak: ${streak.length} days`);
console.log(`Expires: ${new Date(streak.expires).toLocaleString()}`);

The expires timestamp is in UTC and represents the end of the user's current streak period in their local timezone. On the client, convert it with toLocaleString() or your preferred library to show the user a meaningful deadline. This is the primary value to display in streak countdown UI — not a server-computed duration, which would drift from the user's actual local midnight.

Streak freeze consumption also happens at midnight in the user's local timezone rather than UTC midnight, which is relevant to apps that use freezes as a buffer for missed days. A user whose streak period ends at midnight in Tokyo has their freeze consumed at Tokyo midnight, not London or New York midnight.

The remaining piece that Trophy handles but is not covered in this post is the streak expiry display: the API returns an expires timestamp that represents the end of the user's current streak period in UTC, which your frontend converts to local time for display. That's documented in the Trophy Streaks documentation.

Timezone-aware streak configuration in Trophy

FAQ

Should I store timezone as a UTC offset or an IANA identifier?

Always IANA. A UTC offset like +05:30 is static — it encodes the current offset but not the DST rules that determine when that offset changes. India doesn't observe DST, so +05:30 happens to be unambiguous there, but +10:00 could be AEST or AEDT depending on the time of year. An IANA identifier like Australia/Sydney encodes the full history of offset changes for that region and is handled correctly by any proper timezone library.

What timezone library should I use in Node.js?

date-fns-tz for most projects. It's actively maintained, tree-shakeable, and the API is straightforward for the period boundary calculations described in this post. Luxon is a good alternative with a more object-oriented API. Avoid moment-timezone for new projects — it is in maintenance mode and carries significant bundle weight. The Temporal API is the long-term native solution for JavaScript timezone handling, but browser support is still incomplete as of 2026.

How do I get the user's timezone on a mobile app?

iOS: TimeZone.current.identifier returns the IANA identifier. Android: TimeZone.getDefault().id returns the IANA identifier. Web: Intl.DateTimeFormat().resolvedOptions().timeZone returns the IANA identifier.

Send this value to your server on each relevant API call. Don't rely on IP geolocation for timezone inference — it's inaccurate for VPN users and doesn't update when users travel.

What happens to a user's streak if they update their timezone mid-day?

With the lazy evaluation pattern described in this post, the update takes effect on the next interaction. If a user changes their timezone and then logs activity in the same session, the new timezone is used for evaluation. There's no retroactive recomputation of the streak based on historical activity in a different timezone.

Do I need timezone handling for weekly or monthly streaks?

Yes, for the same reasons. A weekly streak requires the user to act in each calendar week in their local timezone. The week boundary in UTC+12 is 12 hours earlier than in UTC-12. Without per-user timezone evaluation, users in UTC+12 have a shorter competition window every week. The calendar-day comparison pattern extends naturally — replace the daily date string with a week or month string and the logic is identical.

How to Backfill Achievements for Existing Users in Mobile Apps

Charlie Brinicombe — Sun, 19 Apr 2026 11:14:31 +0000

You've shipped an achievement system, but your app already had users before you built it. Some of them completed 500 lessons before achievements existed. Others hit a 30-day streak last month with no milestone to mark it. The question is how to retroactively credit the users who already qualify without spamming everyone, without double-crediting on retries, and without locking up your database for an hour.

The problem is more tractable than it appears, but the details matter. This post covers the data model you need, the three query patterns that cover most achievement types, the production concerns that will catch you if you ignore them, and where Trophy removes most of this work for metric and streak-based achievements.

The Data Model

Before you write a single backfill query, your schema needs to support it. Three things have to be true.

You need a way to evaluate the qualifying condition from historical data. For cumulative achievements ("completed 500 lessons"), this means a table that records individual events — not just a denormalized total. SUM(value) FROM lesson_events WHERE user_id = X is backfillable. A users.lesson_count integer that gets incremented in-place is not, unless you can reconstruct the history from somewhere else.

You need an achievements table that records completions, not just current state. The minimum schema:

CREATE TABLE user_achievements (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id),
  achievement_key VARCHAR(255) NOT NULL,
  completed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  backdated BOOLEAN NOT NULL DEFAULT false,

  -- Prevents double-crediting on re-runs
  UNIQUE (user_id, achievement_key)
);

CREATE INDEX ON user_achievements (user_id);
CREATE INDEX ON user_achievements (achievement_key);

The UNIQUE (user_id, achievement_key) constraint is load-bearing. It means a backfill script can be re-run after a partial failure and the database will reject duplicates, rather than requiring you to track which users were already processed in application code.

The backdated column is optional but useful for analytics — it lets you distinguish organic completions from retroactive credits when measuring the achievement system's impact.

You need to know which achievements a user has already seen. Backdating should be silent by default: you credit the user, but you don't immediately fire a notification. The next time they open the app, your client needs to know which completed achievements haven't been surfaced yet. A shown_at column on user_achievements, or a separate shown_achievements table, is the clean way to track this.

The Three Backfill Patterns

Most achievements fall into one of three categories. Each has a different query pattern.

Cumulative achievements

These are milestones based on a running total: lessons completed, km run, words written, items purchased. The backfill query aggregates your event history and finds users who already qualify.

// Step 1: find all users who qualify but haven't been credited yet
async function findQualifyingUsers(
  achievementKey: string,
  metricTable: string,
  metricColumn: string,
  threshold: number
): Promise<string[]> {
  const result = await db.query(`
    SELECT e.user_id
    FROM (
      SELECT user_id, SUM(${metricColumn}) AS total
      FROM ${metricTable}
      GROUP BY user_id
    ) e
    LEFT JOIN user_achievements ua
      ON ua.user_id = e.user_id
      AND ua.achievement_key = $1
    WHERE e.total >= $2
      AND ua.id IS NULL
  `, [achievementKey, threshold]);

  return result.rows.map(r => r.user_id);
}

// Step 2: credit them in bulk
async function creditUsers(
  userIds: string[],
  achievementKey: string
): Promise<void> {
  // INSERT ... ON CONFLICT DO NOTHING makes this safe to re-run
  const placeholders = userIds
    .map((_, i) => `($${i * 3 + 1}, $${i * 3 + 2}, $${i * 3 + 3})`)
    .join(', ');

  const params = userIds.flatMap(id => [id, achievementKey, true]);

  await db.query(`
    INSERT INTO user_achievements (user_id, achievement_key, backdated)
    VALUES ${placeholders}
    ON CONFLICT (user_id, achievement_key) DO NOTHING
  `, params);
}

For large user bases, batch the INSERT rather than inserting one row at a time. Add a WHERE e.user_id > $cursor clause to paginate through the qualifying set rather than loading all user IDs into memory at once.

One-time action achievements

These cover discrete events: completing onboarding, linking a social account, making a first purchase. The qualifying condition is a row existing somewhere, not a cumulative sum.

async function backfillOnboardingAchievement(): Promise<void> {
  // Find users who completed onboarding before the achievement existed
  const qualifying = await db.query(`
    SELECT u.id AS user_id
    FROM users u
    LEFT JOIN user_achievements ua
      ON ua.user_id = u.id
      AND ua.achievement_key = 'onboarding-complete'
    WHERE u.onboarding_completed_at IS NOT NULL
      AND ua.id IS NULL
  `);

  if (qualifying.rows.length === 0) {
    console.log('No users to backfill');
    return;
  }

  console.log(`Backfilling ${qualifying.rows.length} users`);

  const placeholders = qualifying.rows
    .map((_, i) => `($${i * 3 + 1}, $${i * 3 + 2}, $${i * 3 + 3})`)
    .join(', ');

  const params = qualifying.rows.flatMap(r => [r.user_id, 'onboarding-complete', true]);

  await db.query(`
    INSERT INTO user_achievements (user_id, achievement_key, backdated)
    VALUES ${placeholders}
    ON CONFLICT (user_id, achievement_key) DO NOTHING
  `, params);

  console.log('Backfill complete');
}

Streak achievements

Streak achievements require a bit more care. A user's current streak at the time of the backfill might not reflect their longest ever streak. If the achievement is "reach a 30-day streak" and a user hit 45 days six months ago but is currently at day 3, querying users.current_streak would miss them entirely.

The correct backfill queries against streak history rather than current state:

-- You need a streak history table, not just current streak length
CREATE TABLE streak_events (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id),
  streak_length INTEGER NOT NULL,
  recorded_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Find users whose maximum historical streak meets the threshold
SELECT se.user_id
FROM (
  SELECT user_id, MAX(streak_length) AS max_streak
  FROM streak_events
  GROUP BY user_id
) se
LEFT JOIN user_achievements ua
  ON ua.user_id = se.user_id
  AND ua.achievement_key = 'streak-30-days'
WHERE se.max_streak >= 30
  AND ua.id IS NULL;

If you only store current streak and have no streak history, you cannot backfill streak achievements accurately. The options are to accept the gap (credit users who currently qualify and accept that lapsed high-streakers miss out), or to defer the backfill until enough streak history accumulates in the new table.

Production Concerns

Order matters for tiered achievements. If you have Bronze (100 completions), Silver (500), and Gold (1,000), backfill them in ascending order within each user's processing. Inserting Gold before Bronze works at the database level, but it breaks any downstream logic that expects to see the lower tiers already present.

Rate limit your downstream effects. The backfill INSERT is cheap. What's expensive is everything triggered next: achievement emails, XP awards, leaderboard updates. A backfill that credits 50,000 users and each triggers an email queues 50,000 emails in seconds. Either suppress downstream effects entirely for backdated completions using the backdated flag as a gate, or process them at a controlled rate.

Don't send real-time notifications. Achievement notifications land well when they're proximate to the action that earned them. A push notification about a 30-day streak the user hit eight months ago is confusing rather than motivating. Surface backdated completions passively on next app open — a "here's what you've earned" summary — rather than firing the same celebration that new completions trigger.

Test on a small cohort first. Before running across your full user base, scope the backfill to a single test user ID, then a 1% sample. Verify the counts look correct, check that downstream effects aren't misfiring, and confirm the ON CONFLICT DO NOTHING behaviour holds on a second run. A bad script run against 200,000 users is considerably harder to recover from than one run against 2,000.

How Trophy Solves This

If you're using Trophy' achievements system, the backfill story for metric and streak achievements is handled automatically. When you activate a metric or streak achievement in Trophy's dashboard, Trophy checks every existing user's stored metric totals and streak history and completes the achievement silently for any user who already qualifies. No script, no query, no production concern about ordering or rate limiting.

This works because Trophy stores the cumulative metric totals and streak records that the queries above are trying to reconstruct from raw event tables. The qualifying condition evaluation happens inside Trophy rather than in your application code.

For API achievements — the one-time action type — you still need a script, because the qualifying condition is defined by your application's own data. The script is simpler than the DIY version, since you only need to find qualifying users and call Trophy's completion API for each one. The idempotency key pattern ensures re-runs are safe:

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

async function backfillAPIAchievement(achievementKey: string): Promise<void> {
  const qualifying = await db.query(`
    SELECT id FROM users
    WHERE onboarding_completed_at IS NOT NULL
    ORDER BY created_at ASC
  `);

  for (const user of qualifying.rows) {
    await trophy.achievements.complete(achievementKey, {
      user: { id: user.id },
      // Stable key per user and achievement — re-running returns 202 for
      // users already credited, with no change to their state
      idempotencyKey: `backfill-${achievementKey}-${user.id}`,
    });

    // Brief pause to avoid rate limit pressure on large user bases
    await new Promise(resolve => setTimeout(resolve, 50));
  }
}

One important detail: Trophy does not fire the achievement.completed webhook for backdated completions, whether backdating happens automatically or through the completion API with an idempotency key. If your downstream effects depend on that webhook, call them explicitly in the script for each user, or suppress them and accept that backdated users skip those flows.

Trophy dashboard showing achievements configuration

FAQ

What if I only have denormalized totals, not individual event records?

You can't backfill cumulative achievements accurately without event history. The options are to use the current total as a proxy (credit users whose count now meets the threshold, accepting that churned users who once qualified will be missed), to look for event history in logs or analytics tools, or to start recording individual events now and run the backfill once enough history exists. Going forward, storing event rows rather than only incrementing totals is the right schema choice.

Should backdated achievements trigger XP awards?

It depends on whether XP inflation matters to your economy. Retroactively awarding XP to long-tenured users can distort leaderboards and level distributions if the amounts are significant. A common approach is to award a reduced amount for backdated completions, or to skip XP entirely for achievements completed before a certain date. The backdated flag on user_achievements is the clean gate for this logic.

How do I recover from a backfill script that fails partway through?

The ON CONFLICT DO NOTHING pattern makes the script re-runnable from the beginning — users already credited are silently skipped. For very large tables where re-running from scratch is expensive, add cursor-based pagination using the last successfully processed user_id as a restart point, stored in a checkpoint table or flat file between runs.

Can I backfill composite achievements directly?

Composite achievements complete automatically when all prerequisites are met. Backfill the prerequisite achievements first, and any user who then satisfies all prerequisites will have the composite credited automatically as a side effect, whether you're managing the system yourself or using Trophy.

How do I tell users about retroactively credited achievements without it feeling strange?

Avoid real-time push notifications for backdated completions. Surface them on next app open with a summary screen — "You've earned 3 achievements based on your activity" — and let users navigate to them rather than interrupting with a notification about something that happened months ago. The celebration mechanic works best when it's close to the qualifying action, so use it sparingly for credits that aren't.

Where to Go Next

For Trophy's full achievement configuration reference — trigger types, status management, and the completion API — see the Trophy Achievements documentation. The idempotency key pattern used in the backfill script is documented in the Trophy API idempotency guide.

For connecting achievement completions to your XP system, How to Sync XP Across Devices Without Firebase covers the server-authoritative model that ties the two together. And for the measurement question of whether backfilling is moving your retention numbers, How to Measure Points and Levels Across All Your Users covers the analytics layer.

How to Measure XP and Levels Across Users

Charlie Brinicombe — Sun, 19 Apr 2026 10:50:27 +0000

Across apps on Trophy's platform, users who complete achievements at the highest difficulty level (where the threshold is 30 to 100 times their average daily activity) retain at 74%. Users completing achievements that require less than one day's average activity retain at 32%. That gap is more than twice the retention rate, and it comes entirely from how the achievement system is calibrated, not from the feature being present or absent.

Source: Trophy platform data, April 2026. 14-day retention rate vs achievement difficulty, where difficulty is defined as the achievement threshold divided by the average daily activity volume.

Most teams shipping XP and levels never see a number like that for their own app. They know users have levels — they don't know what percentage of users are stuck at Bronze, whether Silver actually predicts retention, or whether their progression curve is set right. The data exists; it just isn't surfaced anywhere without a data pipeline.

This post covers the questions worth asking about your points and levels system, how the typical analytics tool path works and where it creates overhead, and what Trophy surfaces natively without a warehouse.

The Four Questions That Actually Matter

Before reaching for tools, it helps to be precise about what you're trying to learn. Most product teams working on XP and levels are really asking four things:

How are my users distributed across levels right now? If 80% of users are at Bronze and almost nobody reaches Silver, either the curve is too steep, Silver doesn't offer enough incentive to push for, or the user base isn't sufficiently engaged with the core activity. You can't tell which without the distribution.

Where is the progression curve breaking down? A healthy distribution typically tapers — lots of Bronze, fewer Silver, fewer still Gold. A cliff at a specific level means something is wrong at that transition: the activity required is too high, the reward for reaching it isn't visible enough, or the cohort reaching that point is churning before completing it.

Does reaching a level actually predict retention, or is it decorative? This is the question most teams never answer. Levels look good in the product. Whether users who reach Silver retain at meaningfully higher rates than those who don't is a separate question — and the answer determines whether the system is doing any work or just occupying screen real estate.

Is the engagement trend moving in the right direction? Levels are a snapshot. Engagement is a trend. A static level distribution that's improving week-on-week is different from one that's flat — and only a time series shows which you have.

The Data Warehouse Path

The standard answer for cross-user analytics is to pipe events into an analytics platform: Mixpanel, Amplitude, BigQuery, Snowflake. This works correctly and makes sense for teams already operating a warehouse for other product analytics. The integration points with Trophy are clean: the points.level_changed webhook streams level transitions as they happen, and points.changed streams every XP award.

// Pipe level changes to your warehouse via webhook handler
app.post('/webhooks/trophy', async (req, res) => {
  const event = req.body;

  if (event.type === 'points.level_changed') {
    const { user, points, previousLevel, newLevel } = event;

    // Write to your warehouse or analytics platform
    await analytics.track({
      userId: user.id,
      event: 'Level Up',
      properties: {
        pointsSystem: points.key,
        previousLevel: previousLevel.key,
        newLevel: newLevel.key,
        pointsTotal: points.total,
        timestamp: new Date().toISOString(),
      },
    });
  }

  res.sendStatus(200);
});

Once level events are in your warehouse, you can join them to retention data, build cohort analyses, and answer the questions above with whatever query layer you use. The data model is straightforward: each points.level_changed event is a row with userId, fromLevel, toLevel, timestamp, and pointsTotal.

For teams without an existing warehouse, though, standing up a pipeline to answer gamification-specific questions is significant infrastructure overhead. Trophy surfaces the most common answers directly.

What Trophy Surfaces Natively

Level distribution across all users

The level summary API returns a breakdown of user counts at each level in a points system — a direct answer to "how are my users distributed right now" without any querying:

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

// Get the count of users at each level for the 'xp' points system
async function getLevelDistribution() {
  const summary = await trophy.points.levelSummary('xp');

  // Returns an array of levels with user counts
  // e.g. [{ key: 'bronze', name: 'Bronze', userCount: 4821 },
  // { key: 'silver', name: 'Silver', userCount: 634 },
  // { key: 'gold', name: 'Gold', userCount: 87 }]
  return summary;
}

Pull this on a weekly schedule and store the snapshots — even just in a spreadsheet — and you have a time series of level distribution without any pipeline work.

Points distribution across all users

The points breakdown API returns users bucketed by points range, which is where the progression curve problems are visible at a finer grain than level labels alone:

// Get a breakdown of users by points range
async function getPointsDistribution() {
  const breakdown = await trophy.points.summary('xp');

  // Returns buckets showing how many users fall in each points range
  // A cliff between two adjacent buckets signals a sticking point
  // in the progression
  return breakdown;
}

A level distribution showing 80% at Bronze tells you there's a problem. The points breakdown tells you whether those Bronze users are clustered near 0 XP (not engaged at all), near the Silver threshold (almost there but not converting), or spread evenly (disengaged across the board). Each pattern implies a different fix.

Per-metric retention analytics

Every metric tracked in Trophy has its own retention dashboard showing the retention rate of users who engaged with that metric versus those who didn't. This is the mechanism for answering "does reaching a level actually predict retention" — not just for XP, but for any interaction you track.

The retention view compares users who performed the tracked action against those who didn't, across your configured retention window. If lessons completed shows 40% 30-day retention for users who logged at least one lesson versus 15% for those who never did, you have a number — not a hypothesis.

Trophy metric analytics dashboards

The control ratio — measuring gamification's impact directly

Trophy's built-in A/B testing splits users automatically into a control group (no gamification) and an experimental group (gamification active). Trophy withholds all gamification features — points, achievements, streaks, emails, notifications — from control-group users. The analytics dashboards then compare retention and engagement between the two groups.

This answers a question that Mixpanel and Amplitude struggle with: not "do users with high XP retain better" (which is confounded — engaged users earn more XP regardless of whether gamification helped) but "does the gamification system itself cause better retention?" The control group is the counterfactual, and Trophy manages the split automatically.

Configure it from the Integration page in the Trophy dashboard. The control field returned on user API responses lets you conditionally hide gamification UI from control-group users in your own frontend, keeping the split clean.

What Good Achievement Calibration Looks Like — and How to Read Your Own Data

The platform-wide numbers from Trophy's infrastructure give a useful benchmark. Across all apps on Trophy's platform, retention increases monotonically with achievement difficulty:

Achievement difficulty	Retention rate
<1×	32%
1×–3×	35%
3×–10×	49%
10×–30×	63%
30×–100×	74%

Source: Trophy platform data, April 2026. 14-day retention rate vs achievement difficulty, where difficulty is defined as the achievement threshold divided by the average daily activity volume.

The practical implication: if your level summary shows most users clustered at Bronze — which corresponds to low-difficulty achievements — those users are in the 32–35% retention cohort. Moving them into harder achievement territory isn't about making the game more difficult; it's about ensuring the goals are meaningful relative to what users are already doing. An achievement that requires exactly what a user does anyway is no more motivating than no achievement at all.

How to read your own distribution against this: pull the points breakdown, compare the achievement thresholds you've set to average daily metric values in Trophy's metric analytics, and calculate your own difficulty ratios. If the majority of your completions are happening in the <1x or 1x–3x bucket, there's a calibration problem worth fixing before attributing flat retention to the gamification feature itself.

Measuring Beyond XP — Tracking Cross-Feature Interactions

Because Trophy's measurement is built on metrics — which track any user interaction, not just gamification actions — you can add purchases, onboarding completions, feature activations, or any other event as a tracked metric. Once an interaction is tracked in Trophy, it gets the same retention and engagement analytics as any gamification metric.

This means questions like "do users who make a purchase within their first 7 days retain better than those who don't?" are answerable from Trophy's retention dashboard without joining to a separate data source — provided purchases are tracked as a metric. The same applies to any interaction you care about.

Trophy retention pathway analysis

The early engagement charts — which Trophy shows specifically for users within their configured activation window — are particularly useful here. They show metric-by-metric engagement for users in their first days, which surfaces which early interactions predict long-term retention and which are noise. That's the data that should drive which achievements and XP triggers you build around.

A note on scope: Trophy's per-metric retention analysis shows whether users who engaged with a given metric retained better. For questions that require joining multiple data sources outside Trophy — revenue attribution, support ticket correlation, ad spend efficiency — a dedicated analytics warehouse remains the right tool. The points.level_changed and points.changed webhooks are the integration points for those flows.

FAQ

What's the difference between Trophy's level summary API and querying my own database?

If levels are managed in Trophy, the authoritative user count per level lives in Trophy's infrastructure — not your database. Querying your database only works if you're mirroring Trophy's level state back into your own tables, which requires additional sync logic. The level summary API is a single call against the system of record, with no sync required.

Can I get a time series of level distribution, not just the current state?

The level summary and points breakdown APIs return current state. For a time series, the simplest approach is to schedule a daily or weekly call to both APIs and store the snapshots yourself — even a basic cron job writing to a spreadsheet or database table gives you a trend line without warehouse infrastructure. The points.level_changed webhook is the event-level alternative if you want full granularity: every level change as it happens, available to stream into whatever store you prefer.

How does Trophy's control ratio help me measure the impact of XP on retention?

The control ratio assigns a percentage of new users to a group that receives no gamification features. Trophy withholds points, achievements, streak tracking, and all gamification-triggered emails and notifications from these users automatically. The retention and engagement dashboards then compare the two groups, giving you a true causal read on whether gamification is driving retention improvement rather than just correlating with engaged users. Set the ratio from the Integration page; 10–20% in control is typically sufficient for statistical signal without meaningfully reducing the number of users experiencing the full product.

Can Trophy replace my product analytics tool for measuring engagement?

For gamification-centred engagement questions — is XP driving retention, which achievements correlate with long-term use, where users stall in the progression — Trophy's built-in analytics cover the most important queries without an external tool. For broader product analytics that span multiple features outside Trophy's scope, or for custom SQL queries against your full event history, a dedicated analytics platform remains the right choice. The two aren't mutually exclusive; many teams use Trophy for gamification analytics and a warehouse for everything else, with the Trophy webhooks as the bridge.

How do I know if my XP curve is calibrated correctly?

Pull the points breakdown to see where users cluster relative to your level thresholds. Then compare your achievement thresholds to average daily metric values in Trophy's metric analytics — that ratio is your difficulty score. Completions clustering in the <1x or 1x–3x buckets indicate achievements that are too easy relative to normal usage. The platform benchmark (32% retention at <1x, 74% at 30–100x) is a useful calibration reference: if most of your completions are in the easy buckets, adjusting thresholds upward — or creating a harder tier of achievements — is the highest-leverage change you can make to the system before blaming the feature for flat retention numbers.

Where to Go Next

If you're building an XP feature from scratch and need the implementation walkthrough alongside the measurement layer, How to Build an XP Feature covers the end-to-end integration. And for the per-user operational question — how a single user's XP stays consistent across their devices — How to Sync XP Across Devices Without Firebase covers the server-authoritative model in detail.

How to Sync XP Across Devices (Without Firebase)

Charlie Brinicombe — Sat, 18 Apr 2026 23:48:47 +0000

The instinct when you need XP to appear consistently on a user's phone, tablet, and web app is to reach for a sync layer. Firebase Realtime Database is the most common answer, and it solves exactly that problem, but the need for a sync layer is a consequence of a particular design choice: treating XP as a value that originates on the client and needs to be propagated outward. Change that choice and the sync problem largely disappears.

This post covers how the Firebase approach actually works, where it creates friction for XP specifically, and how a server-authoritative XP model, where Trophy is the single source of truth and devices simply read from it, handles the same use case with less infrastructure and better security guarantees.

The Firebase Approach

Firebase Realtime Database handles cross-device consistency through WebSocket connections and a client SDK that maintains a local cache. Each connected client subscribes to a node in the database; when any client writes to that node, Firebase pushes the updated value to all other subscribers in real time.

For XP, the typical schema stores each user's total under a user-scoped path:

/users/{uid}/xp: 1250

The client SDK listens to that node and re-renders the UI whenever the value changes:

import { initializeApp } from 'firebase/app';
import { getDatabase, ref, onValue, runTransaction } from 'firebase/database';

const app = initializeApp(firebaseConfig);
const db = getDatabase(app);

// Listen for XP changes — fires on this device and any other connected device
function subscribeToXP(uid: string, onUpdate: (xp: number) => void) {
  const xpRef = ref(db, `users/${uid}/xp`);
  return onValue(xpRef, (snapshot) => {
    onUpdate(snapshot.val() ?? 0);
  });
}

// Award XP for completing a lesson
async function awardXP(uid: string, amount: number) {
  const xpRef = ref(db, `users/${uid}/xp`);
  await runTransaction(xpRef, (current) => (current ?? 0) + amount);
}

Firebase also handles offline correctly: if a device loses connectivity, writes are queued locally and flushed when the connection is restored. For a pure "keep this number consistent everywhere" problem, this is a clean solution. The complications are specific to what XP actually needs to do in a gamified product.

Four Problems the Firebase Model Creates for XP

Business logic has no safe home

XP isn't a number you increment arbitrarily — it's the output of award rules. A lesson earns 10 XP. Completing a 7-day streak earns 50 XP. Finishing an achievement earns 100 XP. During a promotional campaign, all awards are doubled.

Firebase is a data store. It has no concept of award rules. Those calculations have to run somewhere: either in client code or in Cloud Functions triggered by database writes.

Client-side award logic is a security problem. If your app's JavaScript or mobile code decides how much XP to award and writes that value directly to Firebase, any user who can intercept or modify that code can award themselves arbitrary XP. The Firebase security rules are then your only line of defence — and encoding all your award logic in Firebase's declarative rules language is brittle, difficult to test, and easy to get wrong.

Cloud Functions shift the calculation server-side, which is more defensible, but you've now added a function deployment and invocation layer to what started as a simple data sync question. The logic lives in a Cloud Function, the value lives in Firebase, and you're operating two systems instead of one.

No award history

Firebase Realtime Database stores the current state of a node. It does not natively record why that state is what it is — which events fired, when they fired, or what multipliers were active. A user's XP node contains 1,250. What earned those 1,250 points? You don't know without building a separate event log.

Award history matters more than it seems during initial development. Support tickets ("I completed three lessons and didn't get my XP"), cheat detection ("this user's XP jumped by 5,000 in 30 seconds"), annual Wrapped features ("you earned 14,000 XP this year from 280 lessons") — all of these require a complete, ordered record of every award. If you didn't design that in from day one, reconstructing it later from Firebase is painful.

Level and boost logic creates client coordination overhead

Most XP systems aren't just a counter — they have levels (Bronze at 0 XP, Silver at 500 XP, Gold at 2,000 XP) and time-limited boosts (2× XP during a holiday campaign). In the Firebase model, your client code has to know the level thresholds to detect a level-up and trigger the celebration animation. It has to know whether a boost is currently active to display the correct multiplier in the UI. That configuration has to reach every client through some mechanism — another Firebase node, a remote config service, or a hardcoded constant — and stay consistent when it changes.

This is solvable but it's coordination work. Every additional piece of logic that spans both the client and the Firebase database is something that can drift out of sync.

Gaming the system and duplicate awards

Even with server-side award logic in Cloud Functions, a custom Firebase system has no built-in protection against the same action triggering an award more than once. Mobile networks drop requests. Retry logic re-fires them. A user completes a lesson, the request times out on the client, the app retries on reconnect — and if your Cloud Function doesn't explicitly check whether that specific lesson has already been rewarded for that specific user, the award fires twice.

The standard mitigation is to maintain a separate deduplication log: before processing an award, check whether this action ID has been seen for this user, and if so, skip it. This is straightforward to describe and moderately tedious to build correctly — the check and the award need to happen atomically, the log needs to be queryable by (userId, actionId), and you need a retention policy so it doesn't grow unbounded.

Without this protection, determined users can also exploit retry behaviour deliberately — triggering network failures at the right moment to manufacture duplicate completions. XP inflation is the common outcome: the total climbs faster than intended, level thresholds lose their meaning, and the progression system breaks down. This is a problem that grows with your user base, rarely surfaces in testing, and is painful to remediate after the fact.

The sync problem is downstream of the real problem

When you work through what it would take to make Firebase handle XP correctly — Cloud Functions for award calculations, security rules that encode business logic, a separate event log for history, remote config for level thresholds and boost state — you've built a server-side XP system that happens to use Firebase as its storage layer. At that point you're not saving engineering time compared to building XP server-side directly; you're adding Firebase as an extra dependency.

The Server-Authoritative Model

The alternative reframes the problem entirely. Rather than asking "how do I keep XP consistent across devices," ask "what if XP only ever lives in one place, and devices just read from it?"

In a server-authoritative model, no client ever writes an XP value. The client sends an event describing what the user did ("completed lesson 42"). The server applies the award rules, updates the total, and returns the new state. Every device that wants to display XP reads it from the server. There is no distributed state to synchronise — there is one number in one place.

A minimal server-authoritative XP implementation without any third-party tooling looks like this:

// Server-side: award XP and return the new total
async function handleLessonComplete(
  userId: string,
  lessonId: string
): Promise<{ xp: number; levelUp: boolean; newLevel: string | null }> {
  // Award rules live server-side — no client can influence this
  const award = calculateAward(lessonId); // e.g. 10 XP per lesson

  const result = await db.transaction(async (trx) => {
    const user = await trx('users').where({ id: userId }).forUpdate().first();
    const newTotal = user.xp + award;
    const newLevel = resolveLevel(newTotal);
    const levelUp = newLevel !== user.level;

    await trx('users').where({ id: userId }).update({
      xp: newTotal,
      level: newLevel,
    });

    // Write to event log — history is automatic
    await trx('xp_events').insert({
      user_id: userId,
      amount: award,
      reason: 'lesson_complete',
      lesson_id: lessonId,
      total_after: newTotal,
      created_at: new Date(),
    });

    return { xp: newTotal, levelUp, newLevel };
  });

  return result;
}

The client sends a request to your server, gets back the updated XP and level state, and renders it. No Firebase, no sync layer, no distributed state. The "how does the other device find out" question becomes "how does the other device know to refetch" — a simpler problem that polling or a lightweight push notification handles adequately.

Trophy's Implementation

Trophy is a purpose-built server-authoritative XP layer. Rather than building the award logic, level system, history, and boost infrastructure yourself, you configure them in Trophy's dashboard and interact via API.

Sending activity and reading XP inline

When a user completes an action, send a metric event to Trophy from your server. The response includes the updated XP total, current level, and (if the action triggered a level change) the new level object. No separate XP fetch required on the active device:

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

async function handleLessonComplete(userId: string, lessonId: string) {
  const response = await trophy.metrics.event('lessons_completed', {
    user: { id: userId },
    value: 1,
  });

  const xpData = response.points?.xp;

  if (xpData) {
    // Total XP after this event
    const newTotal = xpData.total;

    // xpData.level is only present when the user's level changed
    // Treat its presence as the level-up signal — no extra bookkeeping needed
    if (xpData.level) {
      triggerLevelUpAnimation(xpData.level.name, xpData.level.badgeUrl);
    }

    updateXPDisplay(newTotal, xpData.level);
  }

  return response;
}

Trophy evaluates all configured triggers on every event — metric-based awards, active boosts, caps — and returns the resulting state. Your server code doesn't need to know the award rules; they live in Trophy's configuration meaning they can be changed easily at any time without code changes.

Fetching current XP on app launch or device switch

When a user opens the app on a different device, fetch their current XP state from Trophy. This is the "sync on open" pattern — no persistent connection, no offline cache to manage:

async function loadUserXP(userId: string) {
  const points = await trophy.users.points(userId, 'xp');

  return {
    total: points.total,
    level: points.level, // Current level object, or null if no levels configured
    recentAwards: points.awards, // Recent award history
  };
}

Call this on app launch, on tab focus, or whenever the user navigates to a profile or progress screen. The value returned is always current — it's a read from Trophy's database, not a local cache.

Pushing display updates to other active sessions

The points.changed webhook fires when a user's XP balance changes (at most once per user per points system per minute, to avoid flooding high-frequency apps). Wire this to your own real-time push layer (whatever you already use for notifications) to update any other sessions the user has open:

// In your webhook handler
app.post('/webhooks/trophy', async (req, res) => {
  const event = req.body;

  if (event.type === 'points.changed') {
    const { user, points } = event;

    if (points.key === 'xp') {
      // Push the updated total to any other active sessions for this user
      // via your existing WebSocket, SSE, or push notification infrastructure
      await pushToUserSessions(user.id, {
        type: 'xp_updated',
        total: points.total,
        added: points.added,
      });
    }
  }

  if (event.type === 'points.level_changed') {
    const { user, points, previousLevel, newLevel } = event;

    if (points.key === 'xp') {
      // Level-up notification to other active sessions
      await pushToUserSessions(user.id, {
        type: 'level_up',
        total: points.total,
        previousLevel: previousLevel.name,
        newLevel: newLevel.name,
        newLevelBadge: newLevel.badgeUrl,
      });
    }
  }

  res.sendStatus(200);
});

The key difference from Firebase's model: Trophy is the source of truth, and your push layer is only responsible for telling other clients to refresh, not for carrying the XP value itself. The client that receives the push does a loadUserXP() call and renders the current state.

Querying award history

The points summary endpoint returns a time-series breakdown of XP awards for a user. No event log to build:

async function getUserXPHistory(userId: string) {
  const summary = await trophy.users.pointsEventSummary(userId, 'xp', {
    aggregation: 'daily',
    startDate: '2026-01-01',
    endDate: '2026-04-19',
  });

  // Returns a daily breakdown of XP awards — useful for
  // Wrapped features, support investigations, or progress graphs
  return summary;
}

Preventing duplicate awards with idempotency keys

Trophy's metric event API supports idempotency keys natively. Pass an idempotencyKey alongside the event — typically the unique ID of the action being rewarded — and Trophy guarantees the award fires at most once per user per key, regardless of how many times the request is retried.

async function handleLessonComplete(userId: string, lessonId: string) {
  const response = await trophy.metrics.event('lessons_completed', {
    user: { id: userId },
    value: 1,
    // Using the lesson ID ensures this award can only fire once
    // per user per lesson, no matter how many retries occur
    idempotencyKey: lessonId,
  });

  // response.idempotentReplayed is true if this key was already seen for this user
  // The response still reflects current state — safe to render regardless
  if (response.idempotentReplayed) {
    console.log(`Duplicate event for lesson ${lessonId} — no award processed`);
  }

  return response;
}

When Trophy receives a request with an idempotency key it has already seen for that user and metric, it returns a 202 Accepted response with idempotentReplayed: true. No metric is incremented, no points are awarded, no achievements are completed — the state is unchanged. The response still reflects the user's current state, so the client can render it safely without needing to branch on whether the event was replayed.

The key should reflect the granularity of uniqueness you want to enforce. A lesson ID prevents a user from earning XP from the same lesson twice, ever. A session ID would allow multiple completions of the same lesson across different sessions. The choice of idempotency key is the business rule — Trophy enforces whatever you specify.

Abstracting XP logic away from code

The difference with Trophy's server-authoritative XP model is that business logic around how to award XP to users based on interactions lives outside your codebase. This means it can be changed at any point without code changes, so product managers can optimize without bottlenecking developers with small logic tweaks.

Points trigger configuration in Trophy

Trophy has a system of triggers for different types of XP awards including:

Interaction driven triggers e.g. 10XP per flashcard viewed
Streak triggers e.g. 10XP per day of streak
Time triggers. e.g. 5XP per hour
Achievement triggers e.g. 50XP for completing a profile
One-time triggers e.g. 100XP on sign up

Additionally, Trophy natively supports setting up levels through the dashboard, allowing easy balance changes and optimizations without code changes.

Points levels in the Trophy dashboard

Finally, Trophy also supports adding time-limited 'boosts' to points logic during key periods such as Christmas, NY and BFCM. This allows product teams to modify poitns logic temporarily around key calendar events, again without creating extra work for developers.

What You're Not Building

The server-authoritative model with Trophy means the following are handled without custom code: award calculation and rate configuration, level threshold evaluation and assignment, boost multiplier stacking and scheduling, XP cap enforcement, and a complete per-user award event log. Each of those would be engineering work in the Firebase model — either in Cloud Functions, security rules, or additional database tables.

The one thing Trophy doesn't replace is your real-time push layer for notifying other active sessions. If you already have WebSockets, SSE, or FCM in your stack for other features (chat, notifications, collaborative activity), you use that. If you don't have anything, polling on focus events is a straightforward fallback — loadUserXP() on visibilitychange or app foreground keeps every session current without a persistent connection.

For the full configuration reference including trigger types, level setup, and boost management, see Trophy's Points documentation. If you're building out the full XP feature including UI patterns for progress bars and level displays, How to Build an XP Feature covers the end-to-end implementation. And if you're also connecting XP to a leaderboard, How to Build a Leaderboard for Your App covers how Trophy's points rankings work.

FAQ

Does Trophy push XP updates to other devices in real time?

Trophy fires the points.changed webhook when a user's XP balance changes, which you can use to trigger a push to other active sessions via your existing real-time infrastructure. Trophy doesn't maintain a persistent WebSocket connection to your clients directly — it notifies your server, and your server notifies the relevant clients. For apps without real-time infrastructure, polling on app foreground or page focus is a practical alternative that keeps sessions current without a persistent connection.

What if my app needs to work offline — can users earn XP without a connection?

Trophy's metric events are sent from your server, not the client, so offline XP earning requires queuing actions on the client and flushing them to your server when connectivity is restored. The pattern is: client stores completed actions locally, syncs to your server on reconnect, your server sends the batched events to Trophy in order, Trophy computes the awards. This is the same pattern you'd need with any server-authoritative system. The advantage over Firebase is that conflict resolution is trivial — Trophy processes events in the order received and applies award rules consistently, so there's no merge conflict to handle on reconnect.

How does Trophy handle the level-up moment across devices?

The metric event response includes the level key in the points map only when the user's level changed as a result of that event — its presence is the level-up signal, so no comparison logic is needed on the active device. For other sessions, the points.level_changed webhook fires separately from points.changed, giving you a clean hook to trigger level-up notifications or animations on any other open sessions without having to diff XP totals.

Can I migrate existing XP data from Firebase to Trophy?

Yes. The approach is to backfill Trophy with metric events that reconstruct each user's current XP total, then cut over new activity to Trophy once the backfill is complete. If your Firebase data includes a history of individual awards (separate from the running total), those can be replayed as individual events to preserve the history in Trophy's audit log. If you only have the current totals, you can use Trophy's Admin API to set initial balances directly before going live. Contact Trophy's team for guidance on large-scale migrations.

Is Trophy's points system only for XP, or can it handle multiple currencies like gems or coins?

Trophy supports multiple independent points systems per app. You can configure a separate system for each currency — XP, gems, coins, energy — each with its own triggers, level thresholds, caps, and boost schedules. Each system has its own key (e.g. xp, gems), and the metric event response returns updated totals for every system that changed as a result of the event. A single action can simultaneously award XP to one system and deduct energy from another, with both results returned inline in the same response.

How to Scale a Leaderboard Beyond Basic Redis

Charlie Brinicombe — Sat, 18 Apr 2026 23:00:59 +0000

Redis sorted sets are the right foundation for leaderboard ranking. The data structure is genuinely elegant: O(log N) insertions, O(log N + K) range reads, atomic operations, and no lock contention under concurrent writes. Trophy uses Redis under the hood for exactly this reason.

The question isn't whether to use Redis for ranking, it's how much of the surrounding infrastructure you want to build and maintain yourself. A bare sorted set gets you fast global ranking. It doesn't get you segmentation, time-based resets with historical state, a durability guarantee, user profile joins, or rank-change events. Each of those is a separate engineering project.

This post covers what each one involves, what Memcached adds to the picture, and how Trophy functions as an abstraction layer that keeps the Redis performance profile while handling the surrounding complexity.

Why Redis Sorted Sets Beat SQL at Scale

The standard starting point for a leaderboard is an ORDER BY query against a relational database. It works correctly and scales fine until it doesn't — typically somewhere between 50,000 and 500,000 users depending on update frequency. Aa tables grows and update frequency climbs, the sort operation becomes an increasingly expensive full-table pass. Adding an index on the score column helps reads but slows writes. You end up in an arms race between read and write performance that a general-purpose database isn't designed to win.

Redis sorted sets sidestep this entirely. Under the hood, each sorted set is implemented as a skip list — a probabilistic data structure that maintains sorted order on every write rather than sorting at read time. The consequence is that ZADD, ZRANK, and ZREVRANGE are all O(log N) regardless of set size, and range reads are O(log N + K) where K is the number of results returned. Fetching the top 10 users from a set of 10 million takes the same time as fetching from a set of 10,000 — the sort cost is paid incrementally on every write, not in a single expensive query at read time.

A basic TypeScript implementation using ioredis demonstrates the core pattern:

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

// Update a user's score — O(log N)
async function recordActivity(userId: string, value: number): Promise<void> {
  await redis.zincrby('leaderboard:weekly', value, userId);
}

// Fetch the top 10 — O(log N + 10)
async function getTopTen(): Promise<Array<{ userId: string; score: number }>> {
  const results = await redis.zrevrangebyscore(
    'leaderboard:weekly',
    '+inf',
    '-inf',
    'WITHSCORES',
    'LIMIT',
    0,
    10
  );

  const entries = [];
  for (let i = 0; i < results.length; i += 2) {
    entries.push({ userId: results[i], score: parseFloat(results[i + 1]) });
  }
  return entries;
}

// Get a specific user's rank — O(log N)
async function getUserRank(userId: string): Promise<number | null> {
  const rank = await redis.zrevrank('leaderboard:weekly', userId);
  return rank !== null ? rank + 1 : null; // Convert 0-indexed to 1-indexed
}

This is correct, fast, and handles concurrent writes safely. Redis processes commands sequentially through its single-threaded event loop, so two users updating scores simultaneously never corrupt the sorted set — no SELECT-then-UPDATE race condition, no transaction isolation level to worry about.

At this point, the competing guidance is accurate: Redis sorted sets are the right data structure. The complications start when you extend beyond a single global list.

Five Places Raw Redis Gets Complicated

Segmentation key explosion

A single global leaderboard maps to one sorted set key. The moment you add segmentation (city-level boards, skill-tier boards, friend groups, gym-specific rankings) you're managing one sorted set per segment. A mid-sized fitness app with 50 cities, 3 skill tiers, and 4 activity types has 600 sorted sets to maintain. Every score update potentially touches multiple sets. At 10,000 daily active users averaging two activities each, that's 20,000 write operations touching up to 600 keys per operation in the worst case.

To keep things maintainable as this scales, you need a consistent naming scheme (leaderboard:{type}:{segmentValue}), logic to determine which keys a given user belongs to on every write, a way to enumerate all segments when querying, and a cleanup strategy for segments that become empty. None of this is a Redis limitation, it's just engineering work that scales with the number of segment dimensions you add.

// What segmented writes look like at the application layer
async function recordActivitySegmented(
  userId: string,
  value: number,
  userCity: string,
  userSkillTier: string,
  activityType: string
): Promise<void> {
  const keys = [
    `leaderboard:global`,
    `leaderboard:city:${userCity}`,
    `leaderboard:tier:${userSkillTier}`,
    `leaderboard:activity:${activityType}`,
    `leaderboard:city:${userCity}:tier:${userSkillTier}`,
  ];

  // Pipeline all writes — but you're still managing N keys per user
  const pipeline = redis.pipeline();
  for (const key of keys) {
    pipeline.zincrby(key, value, userId);
  }
  await pipeline.exec();
}

This is manageable at 5 segments. At 600, key management becomes a significant operational concern.

Time-based resets and historical state

Resetting a weekly leaderboard at period boundaries sounds simple. It isn't. The naive approach (deleting the key and starting fresh) loses the previous period's final rankings before you've had a chance to announce winners or archive results for later analysis. The standard pattern is to snapshot the old set first, then reset:

async function resetWeeklyLeaderboard(weekKey: string): Promise<void> {
  const archiveKey = `leaderboard:weekly:archive:${weekKey}`;

  // Snapshot the current set before reset
  await redis.zunionstore(archiveKey, 1, 'leaderboard:weekly');
  await redis.expire(archiveKey, 60 * 60 * 24 * 90); // Keep 90 days

  // Delete the live set to start fresh
  await redis.del('leaderboard:weekly');
}

This introduces a race condition: if a score update arrives between the ZUNIONSTORE and DEL, that update is in the archive but not in the new live set. The correct approach uses a Lua script to make the operation atomic:

const resetScript = `
  local archiveKey = KEYS[2]
  local liveKey = KEYS[1]
  redis.call('ZUNIONSTORE', archiveKey, 1, liveKey)
  redis.call('EXPIRE', archiveKey, ARGV[1])
  redis.call('DEL', liveKey)
  return 1
`;

async function atomicReset(weekKey: string): Promise<void> {
  await redis.eval(
    resetScript,
    2,
    'leaderboard:weekly',
    `leaderboard:weekly:archive:${weekKey}`,
    String(60 * 60 * 24 * 90)
  );
}

Now add timezone handling. A weekly leaderboard ending Sunday midnight needs to end at Sunday midnight in each user's local timezone, not UTC. You can't reset the global set at a single UTC timestamp without disadvantaging users in later timezones. The correct architecture requires either per-user timezone tracking with per-user period offsets, or a finalisation window that holds the period open until all timezones have passed the boundary, typically 12 to 14 hours after the UTC deadline.

Persistence and durability

Redis is an in-memory store. By default, a Redis restart loses all data. For a leaderboard, that means losing all rankings since the last snapshot. Production deployments need to choose between RDB (periodic snapshots, faster but lossy) and AOF (append-only log, slower but durable) persistence modes, or a combination. Misconfiguring this — or failing to account for it at all — means a Redis node restart can silently wipe weeks of ranking data.

This isn't a hard problem to solve, but it's a configuration and operational concern that needs deliberate attention. A managed Redis service (ElastiCache, Redis Cloud, Upstash) handles this for you at the infrastructure level, but you still need to understand the durability model to know what you're getting.

User data joins

Redis stores user IDs and scores. It knows nothing about display names, avatars, or any other user attributes needed to render a leaderboard. Every leaderboard read requires a join between Redis (for ranks and scores) and your primary database (for user metadata).

async function getLeaderboardWithProfiles(limit: number) {
  // Step 1: Get ranked user IDs from Redis
  const ranked = await redis.zrevrangebyscore(
    'leaderboard:weekly',
    '+inf', '-inf',
    'WITHSCORES', 'LIMIT', 0, limit
  );

  const userIds = ranked.filter((_, i) => i % 2 === 0);

  // Step 2: Fetch user profiles from your database
  const profiles = await db.query(
    'SELECT id, name, avatar_url FROM users WHERE id = ANY($1)',
    [userIds]
  );

  const profileMap = new Map(profiles.map(p => [p.id, p]));

  // Step 3: Merge
  return userIds.map((userId, index) => ({
    rank: index + 1,
    userId,
    score: parseFloat(ranked[index * 2 + 1]),
    name: profileMap.get(userId)?.name ?? 'Unknown',
    avatarUrl: profileMap.get(userId)?.avatar_url ?? null,
  }));
}

Two round trips on every leaderboard render. For read-heavy leaderboards, this pattern drives significant database load. The standard mitigation is to cache the merged result — which then introduces cache invalidation complexity on top of the Redis and database layers.

Rank-change event blindness

Redis has no concept of a user's rank changing because someone else scored more. When User A's score update pushes User B from rank 9 to rank 10, Redis processes User A's ZINCRBY correctly — but nothing notifies User B. Building a rank-change notification system on top of Redis requires polling (expensive), a separate event stream (significant architecture), or a post-write rank comparison (latency and consistency trade-offs). This is one of the more underappreciated pieces of leaderboard infrastructure, and it's entirely absent from the Redis documentation and most tutorials.

What Memcached Adds — and Doesn't

Memcached is a simple key-value cache with no sorted data structure primitive. It cannot implement leaderboard ranking natively — there's no Memcached equivalent of ZADD or ZRANK. Where Memcached appears in leaderboard architectures, it's as a read cache layer in front of Redis or a database: pre-computed leaderboard snapshots are stored in Memcached with a short TTL and served from there to reduce Redis or database read load.

// Typical Memcached caching layer in front of Redis
async function getCachedLeaderboard(key: string, ttlSeconds = 30) {
  const cached = await memcached.get(key);
  if (cached) return JSON.parse(cached);

  const fresh = await getLeaderboardFromRedis(key);
  await memcached.set(key, JSON.stringify(fresh), ttlSeconds);
  return fresh;
}

This pattern makes sense at very high read volumes — if thousands of users are viewing the leaderboard simultaneously and fresh-to-the-second accuracy isn't required, serving from Memcached reduces Redis round trips. But it doesn't solve segmentation, time-based resets, persistence, user data joins, or rank-change events. It adds a caching layer on top of the existing Redis problems, along with its own staleness and invalidation considerations.

Trophy's Architecture

Trophy uses Redis sorted sets for real-time ranking — the same data structure and the same O(log N) performance profile. The difference is that Trophy handles the surrounding infrastructure as a managed layer, so the problems above don't land in your codebase.

The architecture sits across three components:

Redis handles real-time ranking for all active leaderboard periods. Sorted sets are maintained per leaderboard per period per segment. Segmentation key management, atomic period resets, and the Lua scripts required for safe transitions are internal to Trophy's infrastructure.

PostgreSQL materialises ranking data for durability and historical queries. Completed leaderboard periods are persisted to Postgres, which means historical runs are queryable without relying on Redis TTL management or archived keys. It also means a Redis node restart doesn't wipe live ranking data — writes to Redis are backed by Postgres persistence.

An event pipeline sits on top of both. When a user's rank changes — including when their rank shifts because another user scored more — Trophy detects the transition and fires a leaderboard.rank_changed webhook. Period boundaries trigger leaderboard.finished and leaderboard.started events. These are the re-engagement hooks that raw Redis can't emit.

From the application side, the integration is three API calls:

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

// 1. Identify users with segmentation attributes — Trophy manages key routing internally
await trophy.users.identify(userId, {
  name: 'Sam Okafor',
  attributes: {
    city: 'london',
    skill_level: 'intermediate',
  },
});

// 2. Send activity — Trophy writes to all relevant sorted sets atomically
const response = await trophy.metrics.event('workouts_completed', {
  user: { id: userId, tz: 'Europe/London' },
  value: 1,
});

// Rank positions for all relevant leaderboards come back inline
// No separate ranking query, no user data join required on your side
console.log(response.leaderboards);

// 3. Fetch a segmented leaderboard for display
const londonBoard = await trophy.leaderboards.get('weekly-workouts', {
  limit: 10,
  userAttributes: 'city:london',
});

// Historical runs are available without any archival work on your end
const lastWeek = await trophy.leaderboards.get('weekly-workouts', {
  limit: 10,
  userAttributes: 'city:london',
  run: '2026-04-07', // Period start date of the previous week
});

The rank-change webhook requires a handler in your application, but the detection and delivery are handled by Trophy:

// Webhook handler — Trophy fires this when any user's rank shifts
app.post('/webhooks/trophy', async (req, res) => {
  const event = req.body;

  if (event.type === 'leaderboard.rank_changed') {
    const { userId, leaderboardKey, rank, previousRank } = event.data;

    if (rank > previousRank) {
      // User has dropped — re-engagement trigger
      await sendPushNotification(userId, {
        title: "You've been overtaken",
        body: `You've dropped to rank ${rank} on the ${leaderboardKey} leaderboard this week.`,
      });
    }

    if (rank < previousRank) {
      // User has climbed — positive reinforcement
      await sendPushNotification(userId, {
        title: 'You moved up',
        body: `You're now ranked #${rank} this week. Keep going.`,
      });
    }
  }

  if (event.type === 'leaderboard.finished') {
    // Period has closed — announce winners, trigger recap emails
    const { leaderboardKey, topRankings } = event.data;
    await sendWeeklyRecapEmail(topRankings);
  }

  res.sendStatus(200);
});

The rankings configuration and rest conditions are all managed through the Trophy dashboard, meaning all members of the product team, including non-technical colleagues, can be involved in the build.

Trophy dashboard repeating leaderboard configuration

Teams can also make use of Trophy's built-in leaderboard analytics dashboards which help understand leaderboard activity, balance and competitiveness.

Leaderboard analytics in the Trophy dashboard

What You're Actually Trading Off

Running Redis leaderboard infrastructure yourself means owning the following, in addition to the core sorted set operations:

Key schema management — naming convention, enumeration, and cleanup for all segment keys
Atomic reset logic — Lua scripts for safe period transitions without race conditions
Persistence configuration — RDB vs AOF trade-offs, backup strategy, recovery procedures
Timezone-aware period management — per-user timezone tracking and finalisation windows
Historical state archival — TTL management or database snapshots for past period queries
User profile join layer — round trips between Redis and your database on every render, plus caching strategy
Rank-change event pipeline — polling or event streaming to detect rank transitions from third-party score updates
Redis cluster management — sharding decisions, replica configuration, monitoring if you reach 10M+ member sets
Read caching layer — Memcached or application-level cache for high-volume read scenarios

None of these are insurmountable. Senior engineers build all of them regularly. The honest question is whether any of that work is the part of your product that differentiates you from competitors. If the answer is no (and for most consumer apps it is) Trophy provides the same Redis performance with that list already handled.

For a more detailed look at the segmentation design decisions and what breakdown attributes to use for your app category, How Strava Uses Segmented Leaderboards to Drive Engagement covers the psychology and configuration in more depth. For the full implementation walkthrough from first event to live rankings, see How to Build a Leaderboard for Your App, and the official Trophy leaderboard documentation.

FAQ

Does Trophy actually use Redis, or is that a simplification?

Trophy uses Redis sorted sets for real-time ranking — the same data structure described in this post. The O(log N) performance characteristics apply. The difference is that Trophy manages the Redis infrastructure, key schema, persistence configuration, and operational concerns. You interact with a REST API; the sorted set operations happen internally.

What's the performance difference between querying Trophy versus querying Redis directly?

A direct Redis ZRANK or ZREVRANGE call is a sub-millisecond in-memory operation — as fast as it gets. Trophy adds one HTTP round trip to that, typically 20–50ms depending on region. For leaderboard display (which is a UI interaction, not a hot path) this is imperceptible. For real-time ranking updates where you want the user's updated position returned inline (e.g., immediately after a score update), Trophy returns rank data in the event response within 200-300ms, eliminating the need for a separate ranking query after the write.

Should I cache Trophy's leaderboard responses?

For display use cases, yes. Caching for 30–60 seconds on your side reduces API calls and is consistent with standard leaderboard UX — users don't need rankings accurate to the millisecond when viewing a leaderboard screen. Trophy returns fresh data on every request; the caching decision is yours. For real-time feedback immediately after a user's own activity (showing their updated rank), use the rank data returned directly in the metric event response rather than polling the leaderboard endpoint.

What happens to my leaderboard if Trophy experiences downtime?

Design your integration to degrade gracefully — queue metric events for retry and serve cached leaderboard data during any outage. This is the same resilience pattern you'd apply to any external service and the same pattern you'd need to implement for a managed Redis provider. Trophy's 99.9% uptime SLA and infrastructure redundancy are detailed on the status page.

At what scale does building Redis leaderboards in-house become worth it?

The threshold is usually centered around unusual requirements that managed platforms don't support i.e. custom ranking algorithms, proprietary tie-breaking logic, or integration constraints specific to your stack. However for most apps with standard leaderboard requirements, the build-in-house path typically costs more in upfront engineering time and ongoing maintenance than it saves in platform fees.

Where to Go Next

The Trophy Leaderboards documentation covers the full configuration reference: leaderboard types, ranking methods, breakdown attribute setup, and the webhook event schema for leaderboard.rank_changed and leaderboard.finished.

For the implementation walkthrough — from first metric event to a live segmented leaderboard with rank-change notifications — see How to Build a Leaderboard for Your App.

The segmentation design decisions (when to split, what attributes to use, how small to make groups) are covered in How Strava Uses Segmented Leaderboards to Drive Engagement.

Streak Reminder Push Notifications: Prevention First

Charlie Brinicombe — Sat, 18 Apr 2026 12:43:56 +0000

Across Trophy's platform, only 0.9% of users return to start a new streak after losing a 2-3 day streak. That number climbs to 9.1% at 31-60 days and that trend dictates where push notification effort actually pays off.

This post covers why recovery-focused push strategies underperform, how Trophy's push primitives handle the parts that break when teams build them from scratch, and the decisions behind the defaults.

Length of streak that was lost (days)	Return rate (%)
2-3	0.90
4-7	1.42
8-14	1.54
15-30	2.49
31-60	9.09

Source: Trophy platform data, April 2026. Return rate is the percentage of users who started a new streak at any point after losing their previous one, segmented by the length of the streak they lost.

The actionable read of this table is that users who lose short streaks are, in practice, lost users. Recovery notifications sent to this cohort are an expensive way to move the 0.9% number slightly. Users who have invested more than 30 days in a streak are a different story: the return rate rises 3x between the 15-30 and 31-60 buckets. The operational implication is that push effort compounds most when it prevents loss on high-streak users, not when it tries to recover it on low-streak ones.

The naive approach

The default path when building streak reminder push notifications is to wire up Firebase Admin SDK (or direct APNs) behind a cron job that queries for users whose streak is about to expire.

Most teams don't have the time-series user interaction data required to calculate streaks properly, but for those who do the code would look something like this:

import admin from 'firebase-admin';

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount),
});

// Runs on a cron at 20:00 UTC
const atRiskUsers = await db.query(`
  SELECT u.id, u.device_tokens, s.current_streak_length
  FROM users u
  JOIN streaks s ON s.user_id = u.id
  WHERE s.current_streak_length > 0
    AND s.last_extended_at < NOW() - INTERVAL '20 hours'
`);

for (const user of atRiskUsers) {
  for (const token of user.device_tokens) {
    await admin.messaging().send({
      token,
      notification: {
        title: "Don't lose your streak!",
        body: `You're on a ${user.current_streak_length}-day streak. Open the app to keep it going.`,
      },
    });
  }
}

This code handles FCM only. For iOS you either add a separate APNs integration with its own SDK, auth flow, and error handling, or you standardise on Expo Push Service and accept its abstraction constraints. Either path starts a second maintenance stream.

The same shape of problem applies here as it did for streak reminder emails: a cron-plus-query-plus-send pipeline looks tractable on day one and then accumulates edge cases. The difference is that push is a more interruptive surface than email, which means the penalty for sending the wrong message at the wrong moment is proportionally higher. Users who lose trust in your push notifications disable them, and once they're disabled you have no way to earn that channel back.

Why the naive approach breaks in production

The failure modes cluster into five categories.

Platform fragmentation between APNs and FCM. iOS and Android use different services with different auth models, different error codes, and different rate-limit behaviours. Every feature you build is two implementations in parallel: token management, batch sends, delivery retries, content formatting. Expo Push Service abstracts most of this, but only if you standardise on it at the start.

Device token lifecycle. Push tokens rotate when users reinstall the app, switch phones, or in some cases on OS updates. If your server doesn't listen for Unregistered (APNs) or UNREGISTERED (FCM) errors and clean up stale tokens, you keep sending to dead addresses indefinitely. Dead addresses waste quota and count against your sender reputation on some platforms.

Race conditions around extension. A user opens the app at 7:59 PM local time, extends their streak, and closes the app. The cron job runs at 8:00 PM UTC, finds them as at-risk (the read replica was stale), and fires a push that says "don't lose your streak." On a mobile surface, that reads as the app being confused about what the user just did. This is exactly the kind of error that makes users turn push off for your app.

Rate limiting and batching. APNs and FCM both impose rate limits on bulk sends. Handling batch endpoints, back-off on 429 responses, and retry queues correctly is its own engineering track, and getting it wrong means silent delivery failures that you only notice through low engagement.

Content staleness. Push notification payloads are prepared at send time but delivered with some latency. A message that said "you have 3 hours left" can arrive when the user has 2 hours left, or none. For notifications that reference freeze state or progress toward an achievement, the window between payload construction and user-visible delivery becomes a correctness problem rather than a cosmetic one.

Each of these is solvable. The question is whether the team building the core product should be spending its time on them.

The Trophy approach

Trophy's push notifications are a built-in type, configured through the dashboard and dispatched based on the user state Trophy already tracks. Sending streak reminder pushes reduces to three pieces of work: pick a channel, identify users with their device tokens, and activate the streak template.

On the channel side, Trophy supports Apple Push Notification Service, Firebase Cloud Messaging, and Expo Push Service. For apps without an existing investment in APNs or FCM, Expo is the lowest-friction choice because it handles platform fragmentation automatically and means you don't maintain two sets of credentials. More detail on the full email and push feature set is on the features page.

Device tokens get associated with each user the same way timezone does, inline on metric events or via explicit identify:

import { TrophyApiClient } from "@trophy/sdk-node";

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

await trophy.metrics.event("flashcards-flipped", {
  user: {
    id: user.id,
    email: user.email,
    tz: user.timezone,
    deviceTokens: user.deviceTokens, // array of push tokens across devices
  },
  value: 1,
});

The client-side token capture depends on your stack. For Expo, it's a single call:

import * as Notifications from 'expo-notifications';

const { data: token } = await Notifications.getExpoPushTokenAsync();

For native iOS or Android, you capture the token through your own APNs or FCM integration and pass it into Trophy through the identify call above. Either way, the Trophy user record now knows where to send.

User preferences are managed through a dedicated preferences API rather than a single opt-out flag. This matters because "I want streak reminders by email but not push" is a common preference that a binary opt-out can't express:

await trophy.users.updatePreferences("user-123", {
  notifications: {
    streak_reminder: ["push"], // push only
    achievement_completed: ["email", "push"], // both
    recap: ["email"], // email only
    reactivation: [], // disabled
  },
});

Activate the streak template in the dashboard and the dispatch logic Trophy has already built takes over: timezone-aware scheduling, state checking at send time, and device-level coordination are all handled server-side.

The decisions behind the default

A few defaults encode opinions about what makes streak reminder pushes work, and they're worth explaining.

Streak pushes fire with reference to the user's local day-end, not UTC. The tz associated with each user drives every scheduling decision, including when "approaching end of day" actually means. A user who moves timezones gets correct reminders as soon as the tz is updated on the next identify call.

Push content is aware of freeze state. Users who have freezes available average longer streaks: 17.19 days on daily streaks with freezes, compared to 11.62 days without. That population is exactly the high-value cohort where push effort compounds, which means telling them to panic about a streak that a freeze will automatically protect is the fastest way to teach them your notifications don't know what's going on. Trophy's template system exposes freeze state, so the reminder can adjust tone accordingly.

Reactivation is a separate notification type from streak reminders. Once a streak is lost, the question isn't "extend your streak" but "come back and start a new one," and the return rate data above argues for sending that message selectively. Trophy's reactivation notifications are a distinct type with their own template, which means you can enable them for your long-streak cohort without firing them indiscriminately. The broader pattern of what happens when users lose streaks covers the full reactivation design space.

Timing draws on the same weekday pattern as email. We covered this in our streak reminder emails post: Friday is the peak day for daily streak loss across Trophy's platform, with a share roughly twice what random distribution would predict. Push notifications face the same distribution but with tighter delivery constraints, since pushes are more time-sensitive than email. The practical effect is that the late-afternoon window on Friday is where the highest-leverage streak pushes land.

FAQ

Do streak reminder pushes fire for users who don't have freezes available? Yes. The send decision is based on streak state, specifically whether the streak is at risk of expiring in the user's local timezone, not on freeze availability. Freezes change the copy and tone of the push rather than whether it fires. For users with freezes, the reminder can position the freeze as a backup; for users without, the reminder is more direct about the immediate risk.

Can I send push notifications for achievement completions as well as streaks? Yes. Trophy supports four notification types: achievement_completed, recap, reactivation, and streak_reminder. Each has its own template and its own per-channel preference. You can enable all four, or any subset, per user via the preferences API.

What happens if a user has multiple devices? Device tokens are stored as an array on the user record. A push notification for that user is dispatched across the associated tokens, so the user sees the notification on each device they've enabled push on. When a token expires or is rejected by APNs or FCM, Trophy handles the error response and removes the stale token from the user record.

Which channel should I use if I'm starting from scratch? For cross-platform apps built in Expo or React Native, use Expo Push Service. It's one integration instead of two and handles the APNs and FCM routing automatically. For native iOS or Android apps with existing push infrastructure, use APNs and FCM directly. The integration work is similar to what you've already done for other notification types, and Trophy supports both channels natively.

How do I let users opt in to push reminders during onboarding? The update preferences API accepts an array of channels per notification type, so enabling push specifically on streak reminders is one call. Combined with the OS-level permission prompt from your client SDK, this lets you build a preference flow where users see exactly what they're opting into and can toggle individual types rather than a single on/off switch.

What about users who signed up through the web and don't have device tokens? Users without device tokens won't receive pushes. There's nowhere to send them. For these users, Trophy falls back to email if email is enabled on the notification type in their preferences. This is why most apps configure streak_reminder with both email and push as default channels: the channel the user actually receives depends on what they've granted.

Conclusion

The return rate data at the top of this post is the short version of a longer argument: push notifications are leverage, and leverage compounds on users who are already engaged. A streak reminder sent to a user on a 3-day streak recovers the streak 0.9% of the time. The same reminder sent to a user on a 60-day streak recovers it at closer to 100%. Treating those two cohorts with the same urgency, copy, and cadence is the single most common push strategy failure in gamified apps, and the one with the clearest data correction.

For the full set of Trophy's push notification configuration options, the push notifications platform documentation covers every setting referenced here.

Streak Reminder Emails: The Timing That Drives Retention

Charlie Brinicombe — Sat, 18 Apr 2026 12:18:00 +0000

Across Trophy's platform, 25.35% of all daily streak losses happen on Fridays. That's a single-day concentration nearly twice what you'd expect from random distribution. It's also the clearest signal in our data for why streak reminder emails live or die on three specific decisions: when they fire, who gets them, and what they know about the user's current state.

This post covers the parts that go wrong when teams build streak reminders in-house, the Trophy primitives that handle them natively, and the decisions behind the defaults.

Weekday	Loss share (%)
Monday	7.07
Tuesday	12.04
Wednesday	17.74
Thursday	13.91
Friday	25.35
Saturday	19.07
Sunday	4.83

Source: Trophy platform data, April 2026. Distribution of daily streak losses by weekday, across all apps on Trophy's platform. Calculated on users with active daily streaks longer than three days at the time of loss.

The naive approach

The default instinct when building streak reminder emails is to stitch together three things: a database query that finds users with active streaks at risk of expiring, a scheduled job that runs on a fixed cadence, and an email service that delivers the actual message.

A lot of teams don't have the time-series user interaction data required to calculate streaks. But for those who do, in code that typically looks something like this:

// Runs on a cron at 20:00 UTC
const atRiskUsers = await db.query(`
  SELECT u.id, u.email, u.timezone, s.current_streak_length
  FROM users u
  JOIN streaks s ON s.user_id = u.id
  WHERE s.current_streak_length > 0
    AND s.last_extended_at < NOW() - INTERVAL '20 hours'
`);

for (const user of atRiskUsers) {
  await sendgrid.send({
    to: user.email,
    from: "reminders@yourapp.com",
    templateId: "d-streak-reminder",
    dynamicTemplateData: {
      streakLength: user.current_streak_length,
    },
  });
}

Compressed like this, it looks tractable: one join, one loop, one send. The query gets more complex in production, the schedule gets more nuanced, and the template gets more conditional, but the shape stays roughly the same.

What this shape doesn't handle is everything that makes the difference between a streak reminder that works and one that actively reduces retention.

Why the naive approach breaks in production

The failure modes cluster into four categories, all of which we see regularly when customers migrate to Trophy from in-house systems.

Race conditions around extension. A user opens the app at 7:59 PM local time, does the thing that extends their streak, closes the app. The cron job runs at 8:00 PM UTC, queries for at-risk users, finds them (because the last_extended_at field was still stale in the read replica), and sends a reminder for a streak they already extended. The user opens the email, sees "Don't lose your streak!", and loses trust in the product at the same moment the reminder was meant to reinforce it. This happens more often than teams expect, because the window between extension and send is exactly when users are most active.

Timezone drift. A user identifies as Europe/London, then flies to Tokyo for two weeks. The reminder logic is still using the stored London timezone, so they're getting reminders at 4 AM local. The streak logic is also still using London midnight as the rollover point, which means from the user's perspective the streak resets at a seemingly random time during the afternoon. Neither problem is technically unsolvable, but the solution requires knowing when a user's effective timezone has changed, and re-syncing it on every session is work most teams never get around to.

Reminder fatigue and the Friday cliff. A reminder that fires daily at the same UTC moment regardless of user context teaches users to ignore it. More usefully: daily streak losses cluster hard toward the end of the working week (see the weekday distribution above), and a one-size-fits-all reminder schedule misses that concentration entirely. Friday users need the reminder earlier and harder than Tuesday users. Users who have freezes available don't need an emergency reminder at all; they need a gentler nudge, because their streak is actually protected.

Deliverability and domain management. Streak reminders are transactional enough that they need reliable delivery but frequent enough that they can damage sender reputation if mishandled. SPF, DKIM, DMARC, bounce handling, list hygiene: these are full-time concerns for teams that send meaningful volume, and they're inherited the moment you decide to send any emails at all.

Each of these is solvable with enough engineering time. The question is whether solving them is the best use of the team that's supposed to be building the core product.

The Trophy approach

In Trophy, sending streak reminder emails is two pieces of work: identify the user with their timezone, and activate the template. Trophy handles all streak calculations automatically. All timezones and all edge cases are covered.

Identification happens wherever you're already tracking user activity. If you're incrementing a metric when the user completes their core action, you can identify them inline on the same call:

import { TrophyApiClient } from "@trophy/sdk-node";

const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });

// On any user action that should extend a streak, send event to Trophy, which automatically tracks streaks
await trophy.metrics.event("flashcards-flipped", {
  user: {
    id: user.id,
    email: user.email,
    tz: user.timezone, // IANA identifier, e.g. "Europe/London"
  },
  value: 1,
});

The timezone is the key piece. Trophy uses it for streak calculations, leaderboard rankings, and the send timing of every email type. On the browser side, fetching the current timezone is one line:

const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;

Capture that on each session and pass it into the user object on the next metric event. Trophy handles the rest server-side: tracking which users have active streaks at risk, in which timezones, with which freeze counts available automatically. When the reminder logic fires, it fires per-user and in the user's local clock.

The email template itself is designed in the Trophy dashboard. The block-based editor supports conditional rendering (show different content based on user state), smart blocks for things like current streak length and recent history, and email variables for personalisation in both the subject line and body.

Activate the template, and the send logic Trophy has already built takes over.

The comparison with the naive code is deliberate. The engineering work that made the naive approach brittle — the timezone handling, the race condition prevention, the freeze awareness, the deliverability setup — is all still happening. It's happening inside Trophy, refined across every customer app where it runs, and maintained by a team whose full-time job is the streak engine.

The decisions behind the default

A few defaults are worth explaining, because they encode opinions about what makes streak reminders work that would otherwise need to be reverse-engineered.

Daily streak reminders fire four hours before the end of the day in the user's timezone. Early enough to give the user real time to act, late enough that the reminder feels relevant rather than premature. The four-hour window has held up across enough app categories to make it the default. It's also configurable: the dashboard exposes the send timing directly, so teams with genuinely different rhythms (for example, apps where most usage happens in the morning) can override it.

Weekly streak reminders fire on Friday morning. This is the direct response to the Friday cliff in the platform data. Weekly-streak users need to know before the weekend whether they need to act, which means the reminder has to land on a day they're still checking work-adjacent email. Sending on Saturday, the next most likely loss day, is already too late for the cohort that forgets until Monday.

Reminders skip users who have already extended. Trophy's send logic checks current streak state at send time, not at query time. A user whose streak was extended twenty minutes before the reminder was scheduled will not receive it, because the state check happens after the template is prepared, not before. This eliminates the race-condition failure mode entirely. The cost of the additional check is borne by Trophy, not by the customer's infrastructure.

Users in unknown timezones default to Eastern Time. When the tz field isn't set on a user, Trophy defaults to Eastern Time for send scheduling. This is a pragmatic default rather than a correct one. The correct approach is to identify every user with their actual timezone, which the Intl API snippet above makes approximately free on the first session after sign-up.

FAQ

What timezone does Trophy use if I haven't identified the user with one? When the tz field isn't provided on a user, Trophy defaults to Eastern Time for both streak calculations and email send timing. This is a pragmatic default rather than a correct one. The correct approach is to identify every user with their actual timezone, which can be pulled from the browser with one line of JavaScript and passed in on the first metric event for that user.

Can I send reminder emails only to a specific user segment? Yes. Every email template in Trophy can be scoped to users with specific custom attribute values. If you've defined a plan attribute with values free and pro, you can create two different streak reminder templates (one for each plan), and each will only send to users matching that attribute. This is the right place to handle segmentation rather than filtering at the database level, because it also means the segmentation logic stays in one place as the template evolves.

What happens when users turn off email notifications? Trophy respects a per-user subscribeToEmails flag, and also exposes a user preferences API for more granular controls. When a user opts out through a preference center in your app, setting that flag through the SDK removes them from all email types until they opt back in. The check happens at send time, so there's no risk of a reminder going out in the window between the opt-out and the next sync.

How do I customise the email content and subject line? The email builder in the Trophy dashboard supports full template design: copy, subject line, smart blocks for streak history and progress charts, conditional blocks for showing different content based on user state, and email variables for personalisation. Subject lines support the same variables as the body, which is useful for making the subject line specific to the user's current streak length or time since last activity.

What domain do reminders send from? Trophy supports sending from your own domain out of the box. For production use, DNS verification lets you configure a full sending subdomain with DKIM and Return Path records, which gives you the benefit of your existing domain reputation and the best deliverability. Single Sender Verification is available for faster setup during development, which verifies a single email address without requiring DNS changes.

Can reminder emails include in-app deep links? Yes. The button block in the email builder accepts a URL, and that URL can include any user-specific parameters you want, including attribute values passed through as variables. A common pattern is to link the main call-to-action button to a deep link that opens the app directly on the relevant screen, with the user's current streak length and expiry time encoded as query parameters for in-app display.

Conclusion

Streak reminder emails are the last 5% of the streak system, not a separate infrastructure concern. If the streak logic underneath them knows each user's timezone, freeze state, and extension status in real time, the reminder itself becomes a toggle and a template. If it doesn't, the reminder becomes an ongoing maintenance burden that competes with the core product for engineering time, and one that breaks in ways that erode the trust the streak was designed to build.

For the full set of Trophy's streaks APIs and email configuration options, the streaks platform documentation and emails platform documentation cover every setting referenced here.

Guess what day most people lose their streak?

Charlie Brinicombe — Wed, 15 Apr 2026 09:45:08 +0000

Trophy is now powering over 24M streaks which is kind of crazy to think about considering we only launched 1.0 here in January this year.

One of the parts I find most interesting about building horizontal infrastructure is that as you scale and power more and more products you get to see insights that most teams building in isolation will only see a part of, and you can use those insights to make the the infrastructure better for everyone.

For example, because we power streaks for so many users, Trophy can tell that 25% of all streaks are lost on a Friday, closely followed by Saturday (19%) and then Wednesday (18%).

This is across all products Trophy powers, but we can use this to back up insights for each products specific use case and start powering advanced features for them.

The most obvious next step from here is to start working on improving our streak infrastructure to personalize streaks reminders for each user, including sending targeted reminders based on when each user is most likely to lose their streak.

Lot's more insights like this to follow!

Happy building!

Charlie

How We Built SaaS Calculators in Next.js (And Kept Them Shareable)

Charlie Brinicombe — Wed, 25 Mar 2026 15:51:13 +0000

When we built our calculator suite, we wanted more than "a form that outputs a number."

We wanted calculators that were:

fast and SEO-friendly,
easy to extend,
mathematically auditable,
and shareable via URL.

This post breaks down the architecture, design patterns, and trade-offs behind that implementation.

Motivation (and a bit about Trophy)

Trophy is a product aimed at helping teams make better decisions about growth and retention. In our space, the same few questions come up constantly:

What does our churn imply about retention over time?
If we reduce churn, what’s the revenue impact over the next 6–12 months?
Given ARPU and churn, what’s a reasonable LTV and customer lifespan?

We could have answered those with spreadsheets, PDFs, or one-off blog posts but those formats don’t travel well inside a team. We wanted something that:

turns “back-of-napkin” math into an interactive tool,
makes assumptions explicit,
produces a link you can drop into Slack/Notion, and
holds up technically (fast load, predictable state).

That’s why we built calculators as a first-class part of the web app: not just for lead-gen, but as a reusable, composable surface we can iterate on as the product evolves.

Anatomy of a Calculator Page (and why each section exists)

One thing we learned quickly: the calculation itself is only a small part of the user journey.

Each page section has a distinct job:

Header + description: establishes context fast ("what this calculator answers") so users know they’re in the right place before entering data.
Formula block: adds transparency and trust, especially for technical readers who want to validate assumptions before using outputs.

Input controls: collect the minimum viable assumptions needed to compute a meaningful result without overwhelming the user.
Primary result card(s): surface the key answer immediately (e.g. churn, retention, LTV), with lightweight interpretive context.

Impact chart section: translates one-off outputs into a forward-looking narrative ("what changes over 3, 6, 12 months"), which is where decision-making usually happens.

Share section: turns a result into a portable artifact via URL, so teams can discuss the same scenario in Slack/Notion/email.
Related calculators: supports natural next questions (e.g. from churn to LTV), increasing usefulness and reducing dead-ends.
FAQ + CTA: FAQ handles objections and clarification; CTA gives users a clear next step after insight.

In practice, this structure helped us balance three goals simultaneously: educational content, interactive analysis, and team communication.

Tech Stack at a Glance

Next.js App Router for server/client component boundaries
React + TypeScript for predictable UI and typed state
Tailwind CSS for consistent composable styling
Recharts for chart rendering
URL query params as the source of truth for shareable results

1) Server-First Page Composition

A key architectural choice: keep route pages as server components, and pass searchParams down.

That gives us:

better SSR/SEO behavior,
cleaner hydration boundaries,
no useSearchParams() at the page level (which can force Suspense/client boundaries).

Example page composition:

import { config } from './config'
import Calculator from './calculator'
import ChurnImpactChart from './churn-impact-chart'
import { CalculatorPage, createCalculatorMetadata } from '@/components/calculators'

export const metadata = createCalculatorMetadata(config)

interface Props {
  searchParams?: Record<string, string | string[] | undefined>
}

export default function ChurnRateCalculatorPage({ searchParams }: Props) {
  return (
    <CalculatorPage
      config={config}
      initialSearchParams={searchParams}
      calculator={<Calculator initialSearchParams={searchParams} />}
      impactChart={<ChurnImpactChart initialSearchParams={searchParams} />}
    />
  )
}

This is a clean "orchestration layer" pattern: the page wires dependencies together, while feature components do domain work.

2) URL-Driven State via a Dedicated Hook

Instead of each calculator calling useSearchParams() directly, we introduced one shared adapter hook:

export function useCalculatorStateFromParams(
  initialSearchParams: SearchParamsInput,
): UseCalculatorStateReturn {
  const pathname = usePathname()
  const router = useRouter()
  const params = initialSearchParams ?? {}

  const state = useMemo(() => parseParamsToState(params), [params])

  const setState = useCallback(
    (updates: Partial<CalculatorState>) => {
      const next = { ...params }
      for (const [key, value] of Object.entries(updates)) {
        if (value !== undefined) next[key] = String(value)
      }
      const query = paramsToSearchString(next)
      router.replace(query ? `${pathname}?${query}` : pathname, { scroll: false })
    },
    [pathname, params, router],
  )

  return useMemo(() => ({ state, setState }), [state, setState])
}

Why this pattern works

Single source of truth for query parsing/serialization.
No duplicated URL sync logic across calculators.
Share-by-default UX: every calculated result can be copied as a link.

This is effectively an adapter around Next routing primitives with a calculator-focused API.

3) Config-Driven Page Metadata and Content

We model each calculator with a typed CalculatorConfig.

export interface CalculatorConfig {
  slug: string
  name: string
  meta: { title: string; description: string }
  formula: string
  content: {
    description: string
    intro?: { title: string; content: string }
    calculatorSectionTitle?: string
    ctaTitle: string
    ctaDescription: string
  }
  // ...
}

Then metadata generation becomes deterministic and reusable:

export function createCalculatorMetadata(config: CalculatorConfig): Metadata {
  return {
    title: config.meta.title,
    description: config.meta.description,
    alternates: {
      canonical: `https://trophy.so/calculators/${config.slug}`,
    },
  }
}

This reduces drift between SEO tags and on-page content, while making it easier to add new calculators safely.

4) Composition Over Monoliths

The shared shell (CalculatorPage) receives three key inputs:

config
calculator node
impactChart node

export default function CalculatorPage({
  config,
  initialSearchParams,
  calculator,
  impactChart,
}: Props) {
  return (
    <CalculatorLayout config={config}>
      <CalculatorShell>{calculator}</CalculatorShell>
      {impactChart}
      <CalculatorShareSection
        config={config}
        initialSearchParams={initialSearchParams}
        hideUntilCalculated
      />
    </CalculatorLayout>
  )
}

This is a pragmatic slot-based composition pattern:

The layout remains consistent across calculators.
Each domain calculator can evolve independently.
Shared behavior (share section, formula, related calculators, CTA) stays centralized.

5) Domain Math Lives in Pure Functions

UI is stateful and interactive; math should be deterministic and testable.

So the formulas sit in standalone utility modules:

export function generateChurnDecayData(
  startingUsers: number,
  period: 1 | 7 | 30,
  churnPercent: number,
  maxDays: number = 90,
) {
  const clamped = Math.max(0, Math.min(100, churnPercent))
  const survivalPerPeriod = clamped >= 100 ? 0 : 1 - clamped / 100
  const points: { days: number; users: number }[] = []
  const step = Math.max(1, Math.floor(period / 2))

  for (let d = 0; d <= maxDays; d += step) {
    const periodsElapsed = d / period
    const survival = Math.pow(survivalPerPeriod, periodsElapsed)
    points.push({ days: d, users: Math.round(startingUsers * survival) })
  }

  return points
}

Benefits

easier unit testing,
less coupling to React render cycles,
clearer auditing for stakeholders who care about formula correctness.

6) Two-Layer Validation Strategy

Each calculator validates in two places:

Realtime input validity (isValid) to disable calculate actions.
Action-time validation inside handleCalculate for safety.

const isValid =
  Number.isFinite(startNum) &&
  Number.isFinite(remainingNum) &&
  startNum > 0 &&
  remainingNum >= 0 &&
  remainingNum <= startNum

const handleCalculate = () => {
  if (!isValid) {
    setResult(null)
    setState({ shareReady: 0 })
    return
  }

  const churn = calculateChurn(start, remaining)
  setResult(churn)
  setState({ startingUsers: start, remainingUsers: remaining, churnRate: churn, shareReady: 1 })
}

This avoids accidental invalid URL state and keeps result cards/charts consistent.

7) Performance and UX Choices

Some implementation details that made a big difference:

useMemo for chart data and derived values (half-life, domains).
route updates via router.replace with { scroll: false } to avoid janky navigation.
fixed, typed period options (1 | 7 | 30) to simplify math and UI consistency.
responsive chart containers (overflow-x-auto + minimum widths) for small screens.

8) Design Patterns We Reused Across Calculators

The biggest win was pattern consistency:

Template + Slots: one page shell, pluggable calculator + chart.
Adapter Hook: one URL-state bridge for all calculators.
Pure Domain Modules: math separated from rendering.
Config-Driven Metadata: SEO/content generated from typed config.
Feature Flags in Query: share readiness and parameterized results.

These patterns made adding new calculators substantially faster after the first one.

9) What We’d Improve Next

If we were extending this further, we’d likely add:

schema-based query parsing/validation (e.g. zod/valibot) for stricter runtime guarantees,
analytics events at "calculate" and "share" boundaries,
optional server-side persistence for comparison history,
benchmarking (e.g. “you’re in the 60th percentile for churn in fitness apps”) with clear cohort definitions and data provenance,
downloadable reports (PDF/CSV) that bundle inputs, assumptions, charts, and a narrative summary,
shareable team reports (invite colleagues, comments, pinned scenarios) so calculators become collaborative artifacts—not just individual tools,
scenario management (save multiple parameter sets, compare side-by-side, and track deltas over time),
permissions + workspace context so sharing can be public links, private links, or org-only depending on the audience.

Final Thoughts

The core idea is simple: treat calculators as a product surface, not a throwaway widget.

By combining server-first composition, URL-based state, and pure domain math, we ended up with calculators that are:

maintainable,
predictable,
and genuinely useful to share in real workflows.

If you’re building anything similar, start with these two constraints:

Every result should be reproducible from the URL.
Every formula should live outside the component tree.

Everything else gets easier from there.

How to Build an Achievements Feature

Charlie Brinicombe — Fri, 17 Oct 2025 15:21:22 +0000

You want achievements. Track user progress. Award badges for milestones. Display completion status. Seems straightforward. Three weeks later, you're debugging why some users didn't get achievements they qualified for, handling backdating for new achievements, and optimizing queries that check completion criteria for every user action.

Achievement systems appear simple until you implement them at scale. The core concept (recognize milestone completion) hides complexity. When do you check if achievements are complete? How do you handle users who qualified before the achievement existed? What about achievements that require checking historical data across multiple metrics?

Trophy handles achievement systems including completion logic, progress tracking, and backdating. The complete implementation guide walks through the full process. Integration takes 1 day to 1 week. But understanding what building from scratch involves helps you make informed build versus buy decisions.

Key Points

Technical challenges in achievement system implementation
Completion checking patterns that scale
Backdating strategies for fairness
Integration examples with Trophy's API
Build versus buy considerations for achievement features

The Technical Reality

Before building achievement systems, understand the problems beyond simple milestone tracking.

Completion checking logic needs efficiency at scale. Checking every achievement on every user action kills performance. You need smart triggering that only checks relevant achievements. Building this trigger system takes time.

Progress tracking for multi-step achievements adds complexity. "Complete 100 tasks" needs counting. Showing users "45/100" requires storing partial progress. Updating this efficiently as users act requires careful database design.

Backdating ensures fairness when you add new achievements. Users who qualified before the achievement existed should complete it automatically. Scanning historical data for every user takes time. Getting this right without overloading your database is tricky.

Badge hosting and delivery seems minor but adds infrastructure. Where do badge images live? How do you serve them efficiently? What formats work across platforms? These details accumulate.

Rarity calculations show how many users completed each achievement. This requires counting completions across your entire user base and keeping these counts updated as more users complete achievements.

Building production-ready achievement systems typically takes 3-5 weeks including completion logic, progress tracking, and backdating. Trophy's infrastructure handles these problems, reducing implementation to integration work.

Architecture Patterns

If building in-house, these patterns avoid common mistakes.

Event-based checking triggers achievement evaluation only when relevant events occur. Store achievement triggers. When events arrive, check only achievements that could complete based on that event type. This scales better than checking all achievements on every action.

Incremental progress updates maintain partial completion state. Store "tasks completed: 45" instead of recalculating from history on every check. Update incrementally as users act. Trophy uses this pattern for efficient progress tracking.

Async backdating processes achievement qualification in background jobs. When you create an achievement, queue a job that scans historical data and awards to qualified users. Don't block achievement creation on backdating completion.

Denormalized completion state stores which users completed which achievements in fast-access storage. Recompute from history only when needed. Trophy maintains completion state with millisecond query latency.

Trigger mapping links achievement requirements to specific events. Achievement requires metric X reaching value Y, so only check it when metric X events arrive. Trophy's configuration system includes this trigger mapping automatically.

Trophy implements these patterns. You configure achievement criteria. Trophy handles the infrastructure complexity.

Implementation Estimate

Here's realistic timeline for building achievements in-house:

Week 1: Basic implementation. Create achievements. Track completions. Display badges. Works in development with simple achievements.

Week 2: Progress tracking. Store partial progress for multi-step achievements. Update progress efficiently. Show users their advancement toward incomplete achievements.

Week 3: Completion logic. Build trigger system that checks relevant achievements on user actions. Optimize to avoid checking irrelevant achievements. Handle achievement criteria complexity.

Week 4: Backdating and edge cases. Implement fair backdating for new achievements. Handle concurrent completion attempts. Test with realistic data volumes.

Ongoing: Maintenance and expansion. New achievements need adding regularly. Badge management continues. Performance tuning as usage scales.

That's 4+ weeks of engineering time plus ongoing maintenance. Trophy's infrastructure eliminates this timeline, reducing implementation to 1 day to 1 week of integration work.

Building with Trophy

Trophy's integration is faster because achievement infrastructure already exists. Here's what implementation looks like.

Step 1: Create Achievements

In Trophy's dashboard, create achievements with:

Name and description
Badge image (Trophy hosts this for you)
Trigger type (metric-based, API-based, or streak-based)
Completion criteria

For metric achievements, specify which metric and what threshold completes the achievement. Trophy automatically tracks progress and awards completion when users reach the threshold.

Managing achievements online means future additions or changes happen in the dashboard and not in your codebase, preventing back and forth changes.

Step 2: Track User Actions

Send events to Trophy when users perform achievement-relevant actions:

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient(process.env.TROPHY_API_KEY);

// When user completes a task
const response = await trophy.metrics.event('tasks_completed', {
  user: {
    id: 'user-123'
  },
  value: 1
});

// Check if user completed any achievements
if (response.achievements && response.achievements.length > 0) {
  response.achievements.forEach(achievement => {
    console.log(`Unlocked: ${achievement.name}`);
    console.log(`Badge: ${achievement.badgeUrl}`);
    showAchievementNotification(achievement);
  });
}

Trophy processes events and automatically checks if any achievements should complete. The response includes newly completed achievements for immediate user feedback.

Step 3: Display User Achievements

Fetch achievements a user has completed:

// Get user's completed achievements
const achievements = await trophy.users.achievements('user-123', {
  includeIncomplete: 'false' // Only show completed
});

achievements.forEach(achievement => {
  console.log({
    name: achievement.name,
    description: achievement.description,
    badgeUrl: achievement.badgeUrl,
    completedAt: achievement.achievedAt,
    rarity: achievement.rarity // Percentage of users who completed it
  });
});

Trophy returns achievement data including badges, completion timestamps, and rarity statistics. The achievements API documentation covers all available fields.

Step 4: Show Achievement Progress

For incomplete achievements, show progress toward completion:

// Get all achievements including incomplete ones with progress
const allAchievements = await trophy.users.achievements('user-123', {
  includeIncomplete: 'true'
});

allAchievements.forEach(achievement => {
  if (achievement.achievedAt) {
    // Completed
    console.log(`✓ ${achievement.name}`);
  } else {
    // Incomplete - show progress if available
    if (achievement.progress) {
      const percent = (achievement.progress.current / achievement.progress.target) * 100;
      console.log(`${achievement.name}: ${percent}% complete`);
    }
  }
});

Trophy tracks progress for metric-based achievements automatically. Users see how close they are to completion.

Step 5: Complete API Achievements

For achievements that can't be automatically tracked via metrics (completing onboarding, linking accounts, etc.), use the complete achievement API:

// When user completes onboarding
await trophy.achievements.complete('user-123', 'onboarding_complete');

// Trophy marks it as complete and returns achievement data
const result = await trophy.achievements.complete('user-123', 'onboarding_complete');

if (result.achievement) {
  console.log(`Completed: ${result.achievement.name}`);
  showAchievementNotification(result.achievement);
}

This gives you control over when achievements complete for events Trophy can't track automatically.

Achievement Types and Strategies

Different achievement structures serve different product goals. Understanding when your app needs achievements helps you design effective systems.

Metric achievements track cumulative actions. "Complete 100 tasks" or "View 50 lessons." These recognize consistent usage and progress toward mastery. Trophy's metric system tracks these automatically.

Streak achievements recognize consistency. "Maintain a 30-day streak" celebrates sustained engagement. Trophy's streak tracking makes these simple to implement.

API achievements recognize specific one-time events. "Complete onboarding" or "Link social account." You trigger these manually when appropriate events occur.

Tiered achievements create progression. Bronze (10 tasks), silver (50 tasks), gold (100 tasks). Users see clear advancement path. Trophy's metric thresholds support tiered structures naturally.

Hidden achievements surprise users through discovery. Don't show them until completed.

Mix achievement types to serve different user motivations and engagement patterns.

Designing Achievement Structures

Effective achievement design requires understanding user psychology and product goals. Designing achievements for optimal engagement explores strategic frameworks for achievement creation.

Accessibility balance matters. Some achievements should be easy (first task completed) for quick wins. Others should be challenging (1,000 tasks completed) for long-term goals. Trophy's analytics show completion rates helping you tune difficulty.

Progressive revelation prevents overwhelming new users. Show basic achievements upfront. Reveal advanced achievements as users progress. Trophy's achievement system supports controlling visibility.

Meaningful milestones align with user goals. Achievements should recognize progress users care about, not arbitrary metrics. Trophy's flexible metric system lets you track what matters for your product.

Rarity indicators show prestige. "Only 5% of users have completed this" motivates completion. Trophy automatically calculates and displays rarity statistics.

Backdating Logic

When you create new achievements, users who already qualified should complete them automatically. Trophy handles this through backdating.

When you activate an achievement in Trophy:

Trophy scans historical data for users who meet completion criteria
Awards the achievement to qualified users with original completion timestamp
Updates completion counts and rarity statistics
Processes in background without blocking achievement activation

This ensures fairness without requiring manual intervention. Users who completed 100 tasks before that achievement existed get credit when you launch it.

Your code doesn't change. Trophy handles backdating automatically based on achievement configuration.

Notification Strategy

Achievement completions need communication without overwhelming users. Trophy's email system handles notification timing.

Configure achievement emails in Trophy's dashboard:

When to send (immediately, batched, specific times)
Email content and design
Which achievements trigger emails

Trophy sends notifications automatically when users complete achievements. No manual email logic needed in your code.

// Trophy handles notifications automatically
// Your code just tracks events
await trophy.metrics.event('tasks_completed', {
  user: { id: 'user-123' },
  value: 1
});

// If user completes achievement, Trophy sends configured emails

Performance Considerations

Trophy's infrastructure is built for scale, but your integration patterns affect performance.

Check achievements server-side only. Don't query achievement status on every page load. Cache achievement data and refresh periodically or after user actions.

Cache completion state for display-heavy scenarios. Achievement lists don't need real-time accuracy. Cache for 5-10 minutes:

const cache = new Map();

async function getCachedAchievements(userId: string) {
  const cached = cache.get(userId);
  if (cached && Date.now() - cached.timestamp < 300000) {
    return cached.data;
  }

  const fresh = await trophy.users.achievements(userId);
  cache.set(userId, { data: fresh, timestamp: Date.now() });
  return fresh;
}

Trophy handles backend scaling. These client-side patterns optimize your application's performance.

Analytics and Tuning

Trophy provides analytics for achievement system health.

Completion rates show whether achievements are appropriately difficult. Trophy's dashboard shows what percentage of users complete each achievement. Aim for variety: some easy (60%+), some moderate (30-60%), some difficult (5-30%).

Completion velocity reveals how long achievements take. If most users complete an achievement within days of starting, it might be too easy. If it takes months on average, consider whether it's appropriately challenging or frustratingly difficult.

Rarity distribution shows whether you have enough aspirational achievements. If all achievements have 40-60% completion, you might need harder goals for engaged users.

Abandonment patterns indicate where users give up. If users progress halfway toward an achievement then stop, the difficulty curve might be wrong or the achievement might not be compelling.

Use these insights to refine achievement thresholds and create new achievements that fill gaps. Trophy's dashboard configuration makes adjustments quick without code changes.

How to Build an Energy Feature

Charlie Brinicombe — Fri, 17 Oct 2025 11:47:21 +0000

Your want to add an energy feature to your platform. Users consume energy for actions. Energy regenerates over time. Cap it at a maximum. Seems like simple arithmetic. Three weeks later, you're debugging regeneration timing, handling edge cases around maximum caps, and dealing with race conditions when users perform rapid actions.

Energy systems appear straightforward until you implement them at scale. The core concept (limited resource that regenerates) hides complexity. When does regeneration happen? What if users act while at zero energy? How do you handle time zones for regeneration timing? What prevents users from gaming the system?

Trophy handles energy systems including regeneration, consumption, and metering. The complete implementation guide walks through the full process. Integration takes 1 day to 1 week. But understanding what building from scratch involves helps you make informed build versus buy decisions.

Key Points

Technical challenges in energy system implementation
Regeneration patterns and timing considerations
Consumption triggers and usage metering
Integration examples with Trophy's API
Build versus buy considerations for energy features

The Technical Reality

Before building energy systems, understand the problems beyond simple counters.

Time-based regeneration needs careful implementation. Energy regenerates hourly or daily, but when exactly? Server-scheduled jobs create spiky regeneration patterns. Per-user timers scale poorly. Event-driven regeneration requires complex triggering. Getting this right takes time.

Maximum cap handling prevents infinite accumulation. Users hit the cap and stop regenerating. But what if regeneration happens while they're at cap? Do they lose potential energy? How do you communicate this clearly? Edge cases around caps create complexity.

Consumption timing affects user experience. Immediate energy deduction prevents spam but blocks users at zero. Deferred consumption allows actions but creates debt states. Partial consumption for partial actions adds more complexity.

Race conditions happen when users perform rapid actions. Two actions at 5 energy each when user has 8 energy total. Which succeeds? Do they both check balance simultaneously and both succeed, overdrawing the account? Proper locking prevents this but adds latency.

Time zone handling for regeneration schedules requires per-user logic. Daily regeneration at midnight means different times for different users. Trophy handles time zones automatically, but building this yourself means complex timezone math.

Building production-ready energy systems typically takes 3-6 months including regeneration logic, consumption triggers, and edge cases. Trophy's infrastructure handles these problems, reducing implementation to integration work.

Architecture Patterns

If building in-house, these patterns avoid common mistakes.

Event-based consumption separates action tracking from energy deduction. Store user actions as events. Process energy changes asynchronously. This prevents blocking user actions on energy calculations but requires careful consistency management.

Scheduled regeneration jobs grant energy at fixed intervals. Cron jobs that run hourly or daily and grant energy to eligible users. This pattern is simple but creates load spikes. Trophy uses distributed scheduling that spreads regeneration load evenly.

Lazy regeneration computes energy only when queried. Store last check time. When user requests their balance, calculate regeneration since last check and update. This avoids scheduled jobs but complicates balance queries. Trophy uses hybrid approach with cached totals and lazy updates.

Optimistic locking prevents race conditions. Check energy balance, attempt consumption, verify balance didn't change during operation. If it changed, retry. This ensures consistency without blocking concurrent operations.

Denormalized balances for query performance. Maintain current energy in fast storage (Redis). Recompute from event history only when needed. Trophy caches current balances with millisecond query latency.

Trophy implements these patterns. You configure regeneration rules and consumption triggers. Trophy handles the infrastructure complexity.

Implementation Estimate

Here's realistic timeline for building energy systems in-house:

Week 1-2: Basic implementation. Track energy balance. Deduct for actions. Display totals. Works in development with simple cases.

Week 3-4: Regeneration logic. Implement time-based regeneration with scheduled jobs. Handle maximum caps. Make regeneration work across user sessions and time zones. Test edge cases around timing.

Week 5-6: Consumption triggers. Build system for deducting energy based on different actions. Implement variable consumption amounts. Handle insufficient energy cases gracefully.

Week 7: Concurrency and edge cases. Prevent race conditions. Handle rapid actions correctly. Test regeneration at scale. Fix performance issues.

Ongoing: Maintenance and tuning. As usage patterns change, regeneration rates need adjustment. New actions need consumption rules. This work continues indefinitely.

That's 7+ weeks of engineering time plus ongoing maintenance. Trophy's infrastructure eliminates this timeline, reducing implementation to 1 day to 1 week of integration work.

Building with Trophy

Trophy's integration is faster because energy infrastructure already exists. Here's what implementation looks like.

Step 1: Create Energy System

In Trophy's dashboard, create a points system called "Energy" (or your preferred name). Configure the maximum energy cap users can have. Trophy supports any maximum up to your requirements.

Energy systems are just points systems with specific regeneration and consumption rules. Trophy's flexible points infrastructure supports both XP-style accumulation and energy-style metering.

Step 2: Configure Regeneration Triggers

Set up how users gain energy over time. In Trophy's dashboard, create time-based triggers:

Hourly regeneration : Grant X energy every N hours

Award 1 energy every hour
Award 10 energy every 6 hours
Maximum caps prevent energy exceeding limits

Daily regeneration : Grant energy once per day

Award 20 energy at midnight user time
Award 50 energy every 24 hours
Trophy handles timezone timing automatically

Trophy's trigger system grants energy automatically based on your configuration. Users receive energy without manual processing.

Step 3: Configure Consumption Triggers

Set up how users spend energy. Create negative-value triggers for actions that consume energy:

Action-based consumption : Deduct energy when users perform specific actions

Deduct 1 energy per lesson viewed
Deduct 5 energy per workout started
Deduct 10 energy per premium feature access

Configure these through Trophy's dashboard as negative point awards. When users perform tracked actions, Trophy automatically deducts configured energy amounts.

Step 4: Track Energy-Consuming Actions

Send events for actions that consume energy:

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient(process.env.TROPHY_API_KEY);

// When user views a lesson (consumes 1 energy)
const response = await trophy.metrics.event('lesson_viewed', {
  user: {
    id: 'user-123'
  },
  value: 1 // 1 lesson viewed
});

// Check remaining energy
if (response.points?.energy) {
  const remaining = response.points.energy.total;
  const consumed = Math.abs(response.points.energy.added); // Will be negative
  console.log(`Consumed ${consumed} energy. ${remaining} remaining.`);
}

Trophy processes the event and automatically deducts energy based on trigger configuration. The response includes updated energy balance for immediate display.

Changes to energy consumption logic can be made in the Trophy dashboard, preventing back and forth code changes.

Step 5: Check Energy Before Actions

Before allowing energy-consuming actions, check if user has sufficient energy:

// Check user's current energy
const energy = await trophy.users.points('user-123', 'energy');

if (energy.total > 0) {
  // User has energy, allow action
  await performAction();

  // Track the action (consumes energy)
  await trophy.metrics.event('lesson_viewed', {
    user: { id: 'user-123' },
    value: 1
  });
} else {
  // User has no energy, prevent action or show paywall
  showInsufficientEnergyMessage();
}

This pattern prevents users from attempting actions they can't afford. The energy check happens before action processing, providing clear feedback.

Step 6: Display Energy Status

Show users their current energy and when it regenerates:

// Get detailed energy information
const energy = await trophy.users.points('user-123', 'energy', {
  awards: 5 // Last 5 energy changes
});

console.log({
  current: energy.total,
  maximum: energy.maximum,
  recentChanges: energy.awards.map(award => ({
    amount: award.points,
    trigger: award.trigger.name,
    time: award.timestamp
  }))
});

Trophy returns current energy, maximum cap, and recent energy changes. Use this data for UI showing energy status and regeneration timing. The points API documentation covers all available fields.

Regeneration Strategies

Different regeneration patterns serve different product goals.

Constant regeneration grants energy at fixed intervals regardless of usage. Users get 1 energy per hour even if they're at maximum. Simple but can waste potential energy when users hit caps.

Regeneration until cap stops when users reach maximum. Trophy's default behavior. Users don't waste regeneration but might feel pressure to spend energy before hitting cap.

Overflow to storage lets excess regeneration accumulate in separate pool. Complex but prevents waste. Trophy supports this through secondary points systems that have different caps.

Activity-based regeneration grants energy for specific actions beyond time. Complete a challenge, gain energy. This creates positive feedback loops where engagement grants resources for more engagement.

Trophy's time-based triggers handle first two patterns natively. Configure in dashboard without code. More complex patterns use multiple points systems or custom trigger logic.

Consumption Patterns

How you consume energy affects gameplay and user psychology.

Fixed consumption deducts the same amount for all instances of an action. 1 energy per lesson. Simple and predictable. Users understand cost clearly.

Variable consumption charges different amounts for different actions or contexts. 1 energy for basic lesson, 5 energy for advanced lesson. Creates strategic choice about energy spending.

Scaling consumption increases cost based on usage. First 5 lessons cost 1 energy each, next 5 cost 2 each. Encourages moderation and prevents grinding. Trophy implements through threshold-based triggers.

Partial refunds return energy if actions don't complete. User starts lesson (spends energy) but quits (refunds energy). Requires custom logic to track partial completions and issue refunds as positive point awards.

Trophy's trigger flexibility supports all these patterns. Configure consumption amounts through dashboard. Adjust based on player behavior without code changes.

Preventing Energy Gaming

Energy systems create incentives to game. Design prevents exploitation.

Maximum caps prevent infinite accumulation. Trophy's configurable maximum prevents users from stockpiling unlimited energy for later use. Choose caps based on intended session length.

Rate limiting beyond energy. If users can refresh energy artificially (time zone changes, system clock manipulation), add detection and rate limits. Trophy's server-side processing prevents client-side time manipulation.

Consumption verification ensures actions actually completed before deducting energy. Deduct energy only after verifying action succeeded. Trophy's event-based model supports this through proper event sequencing.

Account-level tracking prevents multi-account farming. If users create multiple accounts to bypass energy limits, implement account-level detection. Trophy tracks per-user; your authentication layer handles account limits.

Display and Communication

How you present energy affects user experience.

Clear cost indicators before actions. "This will cost 5 energy" prevents surprise when users can't afford actions. Trophy's balance checking enables this.

Regeneration timing transparency. "Energy regenerates in 2 hours" or "Full energy at 8 PM" gives users planning information. Trophy's time-based triggers have predictable schedules you can communicate.

Friendly empty states. "You're out of energy! It regenerates 1 per hour." explains situation without being punitive. Frame energy as pacing mechanic, not punishment.

Progress toward regeneration. "Energy: 3/10 (regenerating...)" shows both current state and that progress continues. Trophy's balance provides current amount; you track maximum for display.

Economic Tuning

Energy systems need careful tuning to feel fair without killing engagement.

Regeneration rate determines session frequency. Fast regeneration (hourly) encourages frequent short sessions. Slow regeneration (daily) encourages longer, less frequent sessions. Trophy makes rate adjustments through dashboard configuration.

Maximum cap determines session length. Cap of 10 with consumption of 1 per action allows 10 actions per session. Cap of 100 allows longer sessions but slower regeneration to full. Trophy's configurable cap lets you test different values.

Consumption amounts relative to regeneration define gameplay pace. If regeneration grants 20 energy daily and average session consumes 15, users can play daily with buffer. Trophy's analytics show consumption patterns informing tuning.

Monitor average energy levels across users. If most users sit at maximum constantly, regeneration is too generous or consumption too low. If most users sit at zero, consumption is too high or regeneration too slow. Trophy's analytics dashboard shows energy distribution.