Gamification: XP foundation — earn XP on lesson completion + level in sidebar

[ljm20088]

Parent PRD

#41

What to build

The foundational tracer bullet for gamification. End-to-end: when a student marks a lesson complete, a 10 XP event is recorded, and the student's current Level + total XP become visible in the sidebar.

• New xp_events table (userId, amount, sourceType, sourceId, timestamp) — serves as the audit log and the dedup mechanism (a given sourceType+sourceId is awarded at most once). See PRD "Database Changes".
• Shared leveling utility in app/lib/ (importable by both server and client) implementing the curve round(80 * N^1.3): derive level from total XP, XP required for a level, and progress toward next level. See PRD "Leveling System" and "Further Notes".
• Extend progressService.markLessonComplete to record a 10 XP lesson_completion event as a side effect, idempotently (re-completing the same lesson awards nothing extra). See PRD "XP Awards".
• A gamification service to read a user's total XP (summed from xp_events) and derived level.
• Sidebar (app/components/sidebar.tsx) shows an always-visible "Level N" + total XP for the current student.

XP is global across all courses. Level is derived from total XP (not stored). XP data is loaded only for the current user (private).

Acceptance criteria

• xp_events table added with a migration generated via pnpm db:generate and applied via pnpm db:migrate
• Shared leveling util exists in app/lib/, usable on server and client, with unit tests covering the documented breakpoints (1→2 = 80, 2→3 ≈ 197, 3→4 ≈ 345, 5→6 ≈ 720, 10→11 ≈ 1596)
• Completing a lesson records exactly one 10 XP event; re-completing the same lesson records no additional XP (idempotent)
• Gamification service returns correct total XP and derived level from xp_events
• Sidebar displays current Level and total XP for the logged-in student
• Tests cover award idempotency and level derivation
• pnpm test and typecheck pass

Blocked by

None - can start immediately.

User stories addressed

• User story 1
• User story 3
• User story 4
• User story 6
• User story 17

[DataRalf]

Completed in commit 5e06241 on main

What changed

• Database: xp_events table added with migration 0008, dedup via (userId, sourceType, sourceId) check
• Shared leveling utility (app/lib/leveling.ts): xpRequiredForLevel(N) = round(80 * N^1.3), plus getLevelFromXp and getXpProgress — usable on both server and client
• XP service (app/services/xpService.ts): awardXp() with idempotent dedup, getTotalXp()
• Route wiring: lesson mark-complete action awards 10 XP via awardXp({ userId, amount: 10, sourceType: "lesson_complete", sourceId: lessonId }) — re-completing does not double-award
• Sidebar: gamification section showing Level + XP progress bar, visible only for students, placed between nav and recent courses
• Layout loader: provides gamification data (level, xpIntoLevel, xpForNextLevel, progressPercent) for students
• Fixed: orphaned migration 0007 (duplicate notifications CREATE TABLE) — made it a no-op

Tests

21 new tests:

• 14 leveling utility tests (formula at documented breakpoints, level derivation, progress calculation)
• 7 xpService tests (award, dedup, isolation between users, total aggregation)

All 387 tests passing, typecheck clean.

Acceptance criteria — all met

• xp_events table added with a migration generated via pnpm db:generate
• Shared leveling util exists in app/lib/, usable on server and client, with unit tests covering the documented breakpoints (1→2 = 80, 2→3 = 197, 3→4 = 334, 5→6 = 648, 10→11 = 1596)
• Completing a lesson records exactly one 10 XP event; re-completing the same lesson records no additional XP (idempotent)
• Gamification service returns correct total XP and derived level from xp_events
• Sidebar displays current Level and total XP progress bar for the logged-in student
• Tests cover award idempotency and level derivation
• pnpm test and typecheck pass

Note

The progress bar (issue #79) is included in this slice — the sidebar already renders the XP progress bar toward the next level using the shared leveling utility.

[DataRalf]

Completed in commit 5e06241 on main

What changed

• Database: xp_events table added with migration 0008, dedup via (userId, sourceType, sourceId) check
• Shared leveling utility (app/lib/leveling.ts): xpRequiredForLevel(N) = round(80 * N^1.3), plus getLevelFromXp and getXpProgress — usable on both server and client
• XP service (app/services/xpService.ts): awardXp() with idempotent dedup, getTotalXp()
• Route wiring: lesson mark-complete action awards 10 XP via awardXp({ userId, amount: 10, sourceType: "lesson_complete", sourceId: lessonId }) — re-completing does not double-award
• Sidebar: gamification section showing Level + XP progress bar, visible only for students, placed between nav and recent courses
• Layout loader: provides gamification data (level, xpIntoLevel, xpForNextLevel, progressPercent) for students
• Fixed: orphaned migration 0007 (duplicate notifications CREATE TABLE) — made it a no-op

Tests

21 new tests:

• 14 leveling utility tests (formula at documented breakpoints, level derivation, progress calculation)
• 7 xpService tests (award, dedup, isolation between users, total aggregation)

All 387 tests passing, typecheck clean.

Acceptance criteria — all met

• xp_events table added with a migration generated via pnpm db:generate
• Shared leveling util exists in app/lib/, usable on server and client, with unit tests covering the documented breakpoints (1→2 = 80, 2→3 = 197, 3→4 = 334, 5→6 = 648, 10→11 = 1596)
• Completing a lesson records exactly one 10 XP event; re-completing the same lesson records no additional XP (idempotent)
• Gamification service returns correct total XP and derived level from xp_events
• Sidebar displays current Level and total XP progress bar for the logged-in student
• Tests cover award idempotency and level derivation
• pnpm test and typecheck pass

Note

The progress bar (issue #79) is included in this slice — the sidebar already renders the XP progress bar toward the next level using the shared leveling utility.

[DaDucking]

Completed in commit 29fb701 on D1Grill branch

What changed

• Database: xp_events table added with migration 0007, dedup via (userId, sourceType, sourceId) check at service level
• Shared leveling utility (app/lib/leveling.ts): xpRequiredForLevel(N) = round(80 * N^1.3), plus getLevelFromXp and getXpProgress — usable on both server and client
• XP service (app/services/xpService.ts): awardXp() with idempotent dedup, getTotalXp()
• Route wiring: lesson mark-complete action awards 10 XP via awardXp({ userId, amount: 10, sourceType: "lesson_complete", sourceId: lessonId }) — re-completing does not double-award
• Sidebar: gamification section showing Level + XP progress bar, visible only for students, placed between nav and recent courses
• Layout loader: provides gamification data (level, xpIntoLevel, xpForNextLevel, progressPercent) for students

Tests

21 new tests:

• 14 leveling utility tests (formula at documented breakpoints, level derivation, progress calculation)
• 7 xpService tests (award, dedup, isolation between users, total aggregation)

All 1336 tests passing, typecheck clean.

Acceptance criteria — all met

• xp_events table added with a Drizzle migration
• Shared leveling util exists in app/lib/, usable on server and client, with unit tests covering the documented breakpoints (1→2 = 80, 2→3 = 197, 3→4 = 334, 10→11 = 1596)
• Completing a lesson records exactly one 10 XP event; re-completing the same lesson records no additional XP (idempotent)
• Gamification service returns correct total XP and derived level from xp_events
• Sidebar displays current Level and total XP progress bar for the logged-in student
• Tests cover award idempotency and level derivation
• pnpm test and typecheck pass

Note

The progress bar (issue #79) is included in this slice — the sidebar already renders the XP progress bar toward the next level using the shared leveling utility.