Building a Duolingo-Style Streak System: The Complete Developer Guide

-- Player streak state: the current computed state of each user's streak
CREATE TABLE player_streaks (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    player_id       UUID NOT NULL REFERENCES players(id),
    project_id      UUID NOT NULL REFERENCES projects(id),
 
    -- Current streak state
    current_count   INTEGER NOT NULL DEFAULT 0,
    longest_count   INTEGER NOT NULL DEFAULT 0,
 
    -- Tracking timestamps (stored in UTC)
    last_activity_at    TIMESTAMPTZ,        -- Last qualifying activity
    streak_started_at   TIMESTAMPTZ,        -- When current streak began
 
    -- Timezone handling
    timezone        VARCHAR(64) NOT NULL DEFAULT 'UTC',  -- IANA timezone
 
    -- Freeze inventory
    freezes_available   INTEGER NOT NULL DEFAULT 0,
    max_freezes         INTEGER NOT NULL DEFAULT 2,
 
    -- Grace period configuration
    grace_period_hours  INTEGER NOT NULL DEFAULT 6,
 
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 
    UNIQUE(player_id, project_id)
);
 
-- Activity log: immutable record of all qualifying activities
CREATE TABLE streak_activities (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    player_id       UUID NOT NULL REFERENCES players(id),
    project_id      UUID NOT NULL REFERENCES projects(id),
 
    -- When the activity occurred (UTC)
    activity_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 
    -- What local calendar day this counts for
    local_date      DATE NOT NULL,
 
    -- Activity metadata
    activity_type   VARCHAR(64) NOT NULL,
    metadata        JSONB DEFAULT '{}',
 
    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
 
CREATE INDEX idx_streak_activities_player_date
    ON streak_activities(player_id, project_id, local_date DESC);
 
-- Freeze consumption log: tracks when freezes were used
CREATE TABLE streak_freeze_log (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    player_id       UUID NOT NULL REFERENCES players(id),
    project_id      UUID NOT NULL REFERENCES projects(id),
 
    -- Which calendar day the freeze covered
    freeze_date     DATE NOT NULL,
    consumed_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 
    UNIQUE(player_id, project_id, freeze_date)
);
 
-- Streak milestones: tracks which milestones have been achieved
CREATE TABLE streak_milestones (
    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    player_id       UUID NOT NULL REFERENCES players(id),
    project_id      UUID NOT NULL REFERENCES projects(id),
 
    milestone_days  INTEGER NOT NULL,  -- e.g., 7, 30, 100, 365
    achieved_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    reward_claimed  BOOLEAN NOT NULL DEFAULT FALSE,
 
    UNIQUE(player_id, project_id, milestone_days)
);

import { TZDate, tz } from '@date-fns/tz';
import { startOfDay, differenceInCalendarDays } from 'date-fns';
 
interface StreakDates {
  now: Date;
  todayStart: Date;
  timezone: string;
}
 
function getStreakDates(userTimezone: string): StreakDates {
  const timezone = userTimezone || 'UTC';
  const now = new Date();
  const userNow = new TZDate(now, timezone);
  const todayStart = startOfDay(userNow);
 
  return { now, todayStart, timezone };
}
 
function getLocalDate(utcTimestamp: Date, timezone: string): string {
  // Convert a UTC timestamp to a local calendar date string (YYYY-MM-DD)
  const localDate = new TZDate(utcTimestamp, timezone);
  const year = localDate.getFullYear();
  const month = String(localDate.getMonth() + 1).padStart(2, '0');
  const day = String(localDate.getDate()).padStart(2, '0');
  return `${year}-${month}-${day}`;
}

function isStreakBroken(
  lastActivityAt: Date | null,
  timezone: string,
  gracePeriodHours: number,
): boolean {
  if (!lastActivityAt) return false;
 
  const { todayStart } = getStreakDates(timezone);
  const lastActivityLocal = new TZDate(lastActivityAt, timezone);
  const lastActivityDay = startOfDay(lastActivityLocal);
 
  const daysDiff = differenceInCalendarDays(todayStart, lastActivityDay);
 
  // Same day or yesterday = streak is alive
  if (daysDiff <= 1) return false;
 
  // Check grace period: if we're within grace hours of "today",
  // the user might still be counting for "yesterday"
  const now = new Date();
  const nowLocal = new TZDate(now, timezone);
  const hoursSinceMidnight = nowLocal.getHours() + nowLocal.getMinutes() / 60;
 
  if (hoursSinceMidnight < gracePeriodHours && daysDiff === 2) {
    // We're in the grace period window, and the gap is exactly 2 days
    // This means the user missed "yesterday" but we're being lenient
    return false;
  }
 
  return true;
}

async function handleTimezoneChange(
  playerId: string,
  projectId: string,
  newTimezone: string,
): Promise<void> {
  const streak = await getPlayerStreak(playerId, projectId);
 
  if (streak.timezone === newTimezone) return;
 
  const oldLocalDate = getLocalDate(new Date(), streak.timezone);
  const newLocalDate = getLocalDate(new Date(), newTimezone);
 
  // If the date is different in the new timezone, check if this
  // would break the streak and apply protection if needed
  if (oldLocalDate !== newLocalDate) {
    const wouldBreak = isStreakBroken(
      streak.last_activity_at,
      newTimezone,
      streak.grace_period_hours,
    );
 
    if (
      wouldBreak &&
      !isStreakBroken(
        streak.last_activity_at,
        streak.timezone,
        streak.grace_period_hours,
      )
    ) {
      // Streak is only broken due to timezone change
      // Grant a temporary grace or auto-consume a freeze
      await consumeFreeze(playerId, projectId, newLocalDate);
    }
  }
 
  // Update the stored timezone
  await updatePlayerTimezone(playerId, projectId, newTimezone);
}

import { TZDate } from '@date-fns/tz';
import { startOfDay, differenceInCalendarDays, subDays } from 'date-fns';
 
interface StreakState {
  currentCount: number;
  longestCount: number;
  lastActivityAt: Date | null;
  streakStartedAt: Date | null;
  timezone: string;
  freezesAvailable: number;
  maxFreezes: number;
  gracePeriodHours: number;
}
 
interface StreakResult {
  currentCount: number;
  longestCount: number;
  isActive: boolean;
  isAtRisk: boolean; // Haven't completed today's activity yet
  expiresAt: Date | null; // When the streak will break if no action
  freezesAvailable: number;
  todayCompleted: boolean;
  milestoneReached: number | null;
}
 
class StreakService {
  // The main entry point: record an activity and update the streak
  async recordActivity(
    playerId: string,
    projectId: string,
    activityType: string,
    metadata: Record<string, unknown> = {},
  ): Promise<StreakResult> {
    const streak = await this.getStreakState(playerId, projectId);
    const { timezone, gracePeriodHours } = streak;
    const now = new Date();
    const localDate = getLocalDate(now, timezone);
 
    // Check if the user already has activity for today
    const existingActivity = await this.getActivityForDate(
      playerId,
      projectId,
      localDate,
    );
 
    // Always log the activity
    await this.insertActivity(
      playerId,
      projectId,
      now,
      localDate,
      activityType,
      metadata,
    );
 
    // If already completed today, just return current state
    if (existingActivity) {
      return this.computeStreakResult(streak, timezone);
    }
 
    // This is the first activity of the day — update the streak
    return this.extendStreak(playerId, projectId, streak, now, localDate);
  }
 
  private async extendStreak(
    playerId: string,
    projectId: string,
    streak: StreakState,
    now: Date,
    localDate: string,
  ): Promise<StreakResult> {
    const { timezone, gracePeriodHours } = streak;
 
    let newCount: number;
    let streakStartedAt: Date;
 
    if (!streak.lastActivityAt) {
      // First ever activity
      newCount = 1;
      streakStartedAt = now;
    } else {
      const lastLocalDate = getLocalDate(streak.lastActivityAt, timezone);
      const daysDiff = differenceInCalendarDays(
        new Date(localDate),
        new Date(lastLocalDate),
      );
 
      if (daysDiff === 0) {
        // Same day — shouldn't reach here, but handle gracefully
        return this.computeStreakResult(streak, timezone);
      } else if (daysDiff === 1) {
        // Consecutive day — extend the streak
        newCount = streak.currentCount + 1;
        streakStartedAt = streak.streakStartedAt || now;
      } else {
        // Gap detected — check for freezes
        const gapDays = daysDiff - 1; // Number of missed days
        const freezesNeeded = gapDays;
 
        if (freezesNeeded <= streak.freezesAvailable) {
          // Cover the gap with freezes
          await this.consumeFreezes(
            playerId,
            projectId,
            lastLocalDate,
            gapDays,
            timezone,
          );
          newCount = streak.currentCount + 1; // Continue the streak
          streakStartedAt = streak.streakStartedAt || now;
 
          // Deduct freezes
          await this.updateFreezes(
            playerId,
            projectId,
            streak.freezesAvailable - freezesNeeded,
          );
        } else {
          // Streak is broken — start fresh
          newCount = 1;
          streakStartedAt = now;
        }
      }
    }
 
    const newLongest = Math.max(newCount, streak.longestCount);
 
    // Persist the updated streak
    await this.updateStreakState(playerId, projectId, {
      currentCount: newCount,
      longestCount: newLongest,
      lastActivityAt: now,
      streakStartedAt: streakStartedAt,
    });
 
    // Check for milestones
    const milestone = this.checkMilestone(newCount);
    if (milestone) {
      await this.recordMilestone(playerId, projectId, milestone);
    }
 
    const updatedStreak = await this.getStreakState(playerId, projectId);
    const result = this.computeStreakResult(updatedStreak, timezone);
    result.milestoneReached = milestone;
 
    return result;
  }
 
  // Compute the user-facing streak result from raw state
  private computeStreakResult(
    streak: StreakState,
    timezone: string,
  ): StreakResult {
    const now = new Date();
    const todayLocalDate = getLocalDate(now, timezone);
    const todayCompleted = streak.lastActivityAt
      ? getLocalDate(streak.lastActivityAt, timezone) === todayLocalDate
      : false;
 
    const isActive = streak.currentCount > 0 && !this.isExpired(streak);
    const isAtRisk = isActive && !todayCompleted;
 
    // Calculate when the streak expires (end of today + grace period)
    let expiresAt: Date | null = null;
    if (isActive && !todayCompleted) {
      const todayEnd = new TZDate(now, timezone);
      todayEnd.setHours(23, 59, 59, 999);
      // Add grace period
      expiresAt = new Date(
        todayEnd.getTime() + streak.gracePeriodHours * 60 * 60 * 1000,
      );
    }
 
    return {
      currentCount: isActive ? streak.currentCount : 0,
      longestCount: streak.longestCount,
      isActive,
      isAtRisk,
      expiresAt,
      freezesAvailable: streak.freezesAvailable,
      todayCompleted,
      milestoneReached: null,
    };
  }
 
  private isExpired(streak: StreakState): boolean {
    if (!streak.lastActivityAt || streak.currentCount === 0) return true;
    return isStreakBroken(
      streak.lastActivityAt,
      streak.timezone,
      streak.gracePeriodHours,
    );
  }
 
  private checkMilestone(count: number): number | null {
    const milestones = [7, 30, 50, 100, 150, 200, 365, 500, 1000];
    return milestones.includes(count) ? count : null;
  }
 
  // Consume freezes for missed days between last activity and now
  private async consumeFreezes(
    playerId: string,
    projectId: string,
    lastLocalDate: string,
    gapDays: number,
    timezone: string,
  ): Promise<void> {
    for (let i = 1; i <= gapDays; i++) {
      const missedDate = new Date(lastLocalDate);
      missedDate.setDate(missedDate.getDate() + i);
      const missedDateStr = missedDate.toISOString().split('T')[0];
 
      await this.insertFreezeLog(playerId, projectId, missedDateStr);
    }
  }
 
  // --- Database methods (implement with your ORM) ---
 
  private async getStreakState(
    playerId: string,
    projectId: string,
  ): Promise<StreakState> {
    // SELECT * FROM player_streaks WHERE player_id = ? AND project_id = ?
    throw new Error('Implement with your database layer');
  }
 
  private async getActivityForDate(
    playerId: string,
    projectId: string,
    localDate: string,
  ): Promise<boolean> {
    // SELECT 1 FROM streak_activities
    // WHERE player_id = ? AND project_id = ? AND local_date = ?
    // LIMIT 1
    throw new Error('Implement with your database layer');
  }
 
  private async insertActivity(
    playerId: string,
    projectId: string,
    activityAt: Date,
    localDate: string,
    activityType: string,
    metadata: Record<string, unknown>,
  ): Promise<void> {
    // INSERT INTO streak_activities (...)
    throw new Error('Implement with your database layer');
  }
 
  private async updateStreakState(
    playerId: string,
    projectId: string,
    updates: Partial<StreakState>,
  ): Promise<void> {
    // UPDATE player_streaks SET ... WHERE player_id = ? AND project_id = ?
    throw new Error('Implement with your database layer');
  }
 
  private async updateFreezes(
    playerId: string,
    projectId: string,
    count: number,
  ): Promise<void> {
    // UPDATE player_streaks SET freezes_available = ?
    // WHERE player_id = ? AND project_id = ?
    throw new Error('Implement with your database layer');
  }
 
  private async insertFreezeLog(
    playerId: string,
    projectId: string,
    freezeDate: string,
  ): Promise<void> {
    // INSERT INTO streak_freeze_log (...)
    throw new Error('Implement with your database layer');
  }
 
  private async recordMilestone(
    playerId: string,
    projectId: string,
    days: number,
  ): Promise<void> {
    // INSERT INTO streak_milestones (...) ON CONFLICT DO NOTHING
    throw new Error('Implement with your database layer');
  }
}

async function grantStreakFreeze(
  playerId: string,
  projectId: string,
  source: 'purchase' | 'reward' | 'subscription' | 'promo',
  quantity: number = 1,
): Promise<{ freezesAvailable: number }> {
  const streak = await getStreakState(playerId, projectId);
 
  const newCount = Math.min(
    streak.freezesAvailable + quantity,
    streak.maxFreezes, // Cap at maximum (e.g., 2)
  );
 
  await updateFreezes(playerId, projectId, newCount);
 
  // Log the grant for audit purposes
  await logFreezeGrant(playerId, projectId, source, quantity);
 
  return { freezesAvailable: newCount };
}

// Run this job daily, e.g., at 6 AM UTC
async function processExpiredStreaks(): Promise<void> {
  // Find all active streaks where last activity was 2+ days ago
  // (accounting for grace periods and timezone differences)
  const atRiskStreaks = await findAtRiskStreaks();
 
  for (const streak of atRiskStreaks) {
    const localNow = getLocalDate(new Date(), streak.timezone);
    const lastLocal = getLocalDate(streak.lastActivityAt, streak.timezone);
    const daysDiff = differenceInCalendarDays(
      new Date(localNow),
      new Date(lastLocal),
    );
 
    // Still within grace period? Skip.
    if (daysDiff <= 1) continue;
 
    const missedDays = daysDiff - 1;
 
    if (missedDays <= streak.freezesAvailable) {
      // Auto-consume freezes
      await consumeFreezes(
        streak.playerId,
        streak.projectId,
        lastLocal,
        missedDays,
        streak.timezone,
      );
      await updateFreezes(
        streak.playerId,
        streak.projectId,
        streak.freezesAvailable - missedDays,
      );
    } else {
      // Not enough freezes — streak breaks
      await breakStreak(streak.playerId, streak.projectId);
 
      // Emit event for notifications ("Your streak was lost")
      await emitStreakBroken(
        streak.playerId,
        streak.projectId,
        streak.currentCount,
      );
    }
  }
}

interface CalendarDay {
  date: string; // YYYY-MM-DD
  status: 'completed' | 'frozen' | 'missed' | 'future' | 'today';
  activityCount: number;
}
 
async function getStreakCalendar(
  playerId: string,
  projectId: string,
  startDate: string, // YYYY-MM-DD
  endDate: string, // YYYY-MM-DD
): Promise<CalendarDay[]> {
  // Fetch all activities in the date range
  const activities = await getActivitiesInRange(
    playerId,
    projectId,
    startDate,
    endDate,
  );
 
  // Fetch all freeze consumptions in the date range
  const freezes = await getFreezesInRange(
    playerId,
    projectId,
    startDate,
    endDate,
  );
 
  const activityDates = new Map<string, number>();
  for (const a of activities) {
    const count = activityDates.get(a.local_date) || 0;
    activityDates.set(a.local_date, count + 1);
  }
 
  const freezeDates = new Set(freezes.map((f) => f.freeze_date));
 
  const today = getLocalDate(
    new Date(),
    (await getStreakState(playerId, projectId)).timezone,
  );
 
  const calendar: CalendarDay[] = [];
  let current = new Date(startDate);
  const end = new Date(endDate);
 
  while (current <= end) {
    const dateStr = current.toISOString().split('T')[0];
 
    let status: CalendarDay['status'];
    if (dateStr > today) {
      status = 'future';
    } else if (dateStr === today) {
      status = activityDates.has(dateStr) ? 'completed' : 'today';
    } else if (activityDates.has(dateStr)) {
      status = 'completed';
    } else if (freezeDates.has(dateStr)) {
      status = 'frozen';
    } else {
      status = 'missed';
    }
 
    calendar.push({
      date: dateStr,
      status,
      activityCount: activityDates.get(dateStr) || 0,
    });
 
    current.setDate(current.getDate() + 1);
  }
 
  return calendar;
}

async function getCachedStreak(
  playerId: string,
  projectId: string,
): Promise<StreakResult> {
  const cacheKey = `streak:${projectId}:${playerId}`;
  const cached = await redis.get(cacheKey);
 
  if (cached) {
    return JSON.parse(cached);
  }
 
  const streak = await computeStreakResult(playerId, projectId);
  await redis.setex(cacheKey, 300, JSON.stringify(streak)); // 5 min TTL
 
  return streak;
}

import { EngageFabric } from '@playpulse/sdk';
 
const client = new EngageFabric({
  apiKey: 'your-project-api-key',
});
 
// Record an activity — the platform handles streak computation,
// timezone conversion, freeze consumption, and milestone detection
const result = await client.streaks.recordActivity(playerId, {
  type: 'lesson_completed',
  timezone: userTimezone,
});
 
// result includes: currentCount, isActive, isAtRisk,
// expiresAt, freezesAvailable, milestoneReached