Gamification

Spec Source: Document 8 -- Gamification System | Last Updated: Feb 2026

DoCurious uses gamification to motivate real-world experiences, not screen time. The system rewards completing challenges offline, not browsing, clicking, or staying logged in. Everything in the gamification layer -- XP, levels, badges, streaks, leaderboards, and the Journey Map -- exists to celebrate what users do in the real world, and to encourage them to keep exploring.

STATUS: BUILT

Types: src/types/gamification.types.ts (402 lines) + src/types/learningPath.types.ts | Store: src/store/useGamificationStore.ts | API: src/api/gamification.api.ts + gamification.real.api.ts | Components: 13 gamification components including LevelProgress, BadgeCard, BadgeGrid, BadgeCollection, BadgeShowcase, LeaderboardTable, LeaderboardOptIn, NewBadgeModal, LevelUpModal, XPGainToast, StreakDisplay, JourneyMap | Pages: XPHistory, Badges, JourneyMap (all in src/pages/profile/) | Storybook: stories for BadgeCard, BadgeGrid, LevelProgress, StreakDisplay, XPGainToast, LeaderboardTable | School: LearningPathDesigner page in src/pages/school/ | Community: CommunityGoals page + GoalCard + GoalDetail components + useCommunityGoalStore + communityGoal.api.ts | Group: GroupChallenge page in src/pages/challenges/

---

Philosophy

The gamification system is grounded in Self-Determination Theory (SDT), which identifies three core human needs: autonomy, competence, and relatedness. Every gamification decision maps back to at least one of these:

Human Need	How DoCurious Satisfies It
Autonomy	Choice in what challenges to pursue, Bucket List curation, Dealer's Choice selection
Competence	Clear progression (levels, Journey Map), appropriate difficulty, mastery badges
Relatedness	Community participation, cooperative goals, celebrating shared achievements

The design priorities are intentionally ordered:

1. Mastery and Collection (Primary) -- Levels that show personal growth over time. Badges as collectible achievements. Journey Map revealing exploration progress. Learning Paths for structured skill building.
2. Cooperation (Secondary) -- Community goals everyone contributes to. Group challenges with shared success. Celebrating others' achievements. Partner/buddy completion bonuses.
3. Competition (Tertiary, Opt-In) -- Leaderboards available but not prominent. Limited visibility (top performers only, not full rankings). Opt-in at school/class level. Never the default experience.

Additional psychological principles applied throughout: collection motivation (badges, category completion, "catch 'em all" instinct), progress visualization (Journey Map, level bars, streak counters), variable rewards (Dealer's Choice card reveals, rare badge surprises), and social proof ("47 people completed this" -- information, not pressure).

Age Considerations

The core gamification system is identical for all ages. The underlying data model is the same regardless of user age. Presentation adapts:

Age Group	Emphasis	De-Emphasis
Under 10	Visual rewards, collection, simple progress	Complex stats, competition
10--12	Mastery progression, streaks, cooperative goals	Individual rankings
13+	Full system access including opt-in leaderboards	--

---

What We Don't Do

These are not accidental omissions. Each is a deliberate design decision grounded in the platform's philosophy of encouraging real-world experiences without creating unhealthy digital habits.

• No loss mechanics -- Users never lose XP or progress. (One exception: Dealer's Choice abandonment; see XP System below.)
• No daily login rewards -- No pressure to open the app every day. Streaks are weekly, not daily.
• No time-limited pressure -- No "complete in 24 hours or lose your chance" mechanics.
• No public shame -- Never show who is "last place" or struggling. Leaderboards only show the top tier.
• No pay-to-win -- XP, badges, and progression cannot be purchased.
• No notification spam -- Gamification events are discovered in-app, not pushed via notifications. Zero push notifications for any gamification event.

---

XP System

STATUS: BUILT

Types: XPEvent, XPTransaction, XPEventType, XP_VALUES constant in src/types/gamification.types.ts | Store actions: fetchStats, refreshXp in useGamificationStore | API: addXPEvent, getUserTotalXP, getXPEvents in gamification.api.ts | Components: XPGainToast (animated +XP notification), LevelProgress (progress bar) | Page: XPHistory (full ledger view with running balance)

XP (Experience Points) is the primary progression currency. It accumulates over time and never decreases (with one exception). XP is always tied to real-world activity that has been verified.

XP Earning Events

Event	Base XP	Notes
Challenge completed (verified)	By difficulty	See difficulty table below
Milestone completed	Proportional	Total challenge XP / milestone count
First challenge ever	+100 bonus	Welcome reward
First challenge in a category	+50 bonus	Encourages breadth
Dealer's Choice completion	Base x DC multiplier	1.5x--2.0x per card type
Learning Path checkpoint	+25 bonus	At designated path milestones
Learning Path completed	+100 bonus	Finishing entire path
Community goal contribution	+25 bonus	When community goal is met
Group challenge completion	+25 bonus	When all group members complete
Streak milestone	+25 to +500	At 2, 4, 8, 12, 26, 52 weeks

What does NOT earn XP: Logging in, browsing or searching, time spent on platform, social actions (comments, thumbs up), adding to Bucket List.

Difficulty-Based XP

Challenge creators set difficulty. DoCurious staff may adjust if miscategorized.

Difficulty	Base XP
Beginner	50 XP
Intermediate	100 XP
Advanced	200 XP

XP Multipliers

Multipliers stack as noted. Dealer's Choice multipliers are exclusive of each other (you can only have one DC multiplier at a time), but streak and Learning Path multipliers stack on top.

Condition	Multiplier	Stacks
Dealer's Choice: Comfort Push	1.5x	No (DC multipliers exclusive)
Dealer's Choice: Rarely Tried	1.75x	No
Dealer's Choice: Uncharted	2.0x	No
Active streak (4+ weeks)	1.1x	Yes
Active streak (12+ weeks)	1.2x	Yes (replaces 1.1x)
Learning Path challenge	1.1x	Yes

Example: An Intermediate challenge (100 XP) dealt via DC Uncharted (2.0x) with a 12-week streak (1.2x): 100 x 2.0 x 1.2 = 240 XP.

Diminishing Returns on Repeats

To encourage variety over farming, repeating the same challenge earns progressively less XP:

Completion #	XP Earned
1st	100%
2nd	50%
3rd	25%
4th+	10% (floor)

Users can still repeat challenges; they just earn less XP each time.

XP Display

• Dashboard: Current XP and level progress bar
• Profile: Total XP, current level
• On completion: "+X XP" animation (rendered by XPGainToast component)
• History: Full viewable log of XP-earning events with running balance (the XPHistory page)

No Negative XP (General Rule)

XP only increases. Users cannot lose accumulated XP.

Exception -- Dealer's Choice abandonment: DC challenges use symmetric XP penalties as specified in Explore & Discovery. When a user abandons a DC challenge, they lose the XP they would have gained. This is the only mechanism in the platform where XP can decrease. The penalty is intentional: the risk/reward symmetry makes the DC choice meaningful and prevents abuse (dealing repeatedly until getting an easy challenge).

Under-13 exception to the exception: Under-13 users playing "Practice DC" do not receive abandonment penalties (XP cannot go negative for minors).

---

Levels and Progression

STATUS: BUILT

Types: LevelDefinition, LEVEL_DEFINITIONS constant (15 levels), MAX_LEVEL, calculateLevel(), calculateXpProgress() in src/types/gamification.types.ts | Store: currentLevel, xpProgress, totalXp in useGamificationStore | Components: LevelProgress (progress bar with level badge), LevelUpModal (celebration with confetti)

Levels provide long-term progression and status. They are recognition-based, not feature gates. Every user starts at Level 1 (Newcomer) and progresses through 15 named levels.

The 15 Levels

Level	Title	XP Required	Cumulative XP
1	Newcomer	0	0
2	Curious	100	100
3	Explorer	250	350
4	Adventurer	500	850
5	Pathfinder	750	1,600
6	Trailblazer	1,000	2,600
7	Pioneer	1,500	4,100
8	Voyager	2,500	6,600
9	Wayfinder	3,500	10,100
10	Discoverer	5,000	15,100
11	Seeker	7,000	22,100
12	Ranger	10,000	32,100
13	Champion	15,000	47,100
14	Master	20,000	67,100
15	Legend	30,000	97,100

Beyond Level 15: Continue with "Legend II," "Legend III," etc. at 30,000 XP increments.

Pacing rationale: Level 2 takes about 2 Beginner challenges (a quick first win). Level 5 requires roughly 20 challenges (a consistent month of activity). Level 10 takes about 100 challenges (a dedicated user over several months). Level 15 requires 500+ challenges (a long-term committed user).

Level-Up Experience

When a user reaches a new level, the LevelUpModal component fires with:

• Celebration modal with confetti animation using Scout Green (#2D5016) and Brass Gold (#C49B2A) brand colors
• New title revealed: "You've become a [Title]!"
• Level badge added to collection
• Optional prompt to share the achievement
• No push notification (discovered in-app only)

Level Display

Level is shown in multiple contexts: profile (level badge and title), Track Record cards (small level indicator), community feeds (level visible on posts), and challenge galleries (level shown on featured TRs).

Level Unlocks

DECISION PENDING

The level unlock model is under review. Three options are being evaluated.

Option	Description	Tradeoff
A: Recognition Only	Levels are status/achievement markers. All features available from start.	Simplest, most inclusive
B: Cosmetic Unlocks	Profile customization unlocks at levels (frames, colors, themes). All functionality still available.	Adds reward feeling without barriers
C: Feature Unlocks	Certain features require minimum level (e.g., Dealer's Choice at Level 3).	Creates "grind to unlock" dynamic. May frustrate new users.

---

Badges

STATUS: BUILT

Types: Badge, UserBadge, BadgeCategory (9 values), BadgeRarity (5 tiers) in src/types/gamification.types.ts | Store: allBadges, userBadges, newBadgeEarned, fetchAllBadges, fetchUserBadges, checkForNewBadges in useGamificationStore | API: getAllBadges, getUserBadges, awardBadge, checkAndAwardBadges in gamification.api.ts | Components: BadgeCard (rarity-styled single badge), BadgeGrid (grid with earned/locked states), BadgeCollection (full collection with category filters and detail modal), BadgeShowcase (profile top-5 showcase), NewBadgeModal (celebration with confetti) | Page: Badges in src/pages/profile/ | Mock data: 12 default badges seeded in gamification.api.ts

Badges are collectible achievements -- trophies that recognize specific accomplishments. The badge system is designed around the "catch 'em all" collection instinct.

Badge Categories

There are 7 main categories plus 2 special types (9 total values in BadgeCategory):

1. Milestone Badges -- Earned for reaching completion counts.

Badge	Criteria	Rarity
First Steps	Complete 1 challenge	Common
Getting Started	Complete 5 challenges	Common
Double Digits	Complete 10 challenges	Common
Quarter Century	Complete 25 challenges	Uncommon
Half Century	Complete 50 challenges	Uncommon
Century Club	Complete 100 challenges	Rare
Bicentennial	Complete 200 challenges	Rare
High Achiever	Complete 500 challenges	Epic

2. Category Mastery Badges -- Earned for exploring and mastering categories. Each category gets its own badge tier.

Badge	Criteria	Rarity
[Category] Curious	1 completion in category	Common
[Category] Explorer	5 completions in category	Uncommon
[Category] Enthusiast	15 completions in category	Rare
[Category] Master	30 completions in category	Epic

3. Breadth Badges -- Earned for exploring across categories.

Badge	Criteria	Rarity
Variety Seeker	Complete challenges in 3 categories	Common
Well-Rounded	Complete challenges in 5 categories	Uncommon
Renaissance Soul	Complete challenges in all categories	Rare
Category Completionist	Reach "Explorer" in all categories	Epic

4. Streak Badges -- Earned for consistent weekly activity.

Badge	Criteria	Rarity
Getting Regular	2-week streak	Common
Steady Pace	4-week streak	Uncommon
Dedicated	8-week streak	Rare
Committed	12-week streak	Rare
Marathon Runner	26-week streak	Epic
Year of Curiosity	52-week streak	Legendary

5. Dealer's Choice Badges -- Earned through DC participation.

Badge	Criteria	Rarity
Card Shark	Complete 5 DC challenges	Uncommon
Dealer's Favorite	Complete 15 DC challenges	Rare
High Roller	Complete 5 Uncharted DC challenges	Rare
All In	Complete 50 DC challenges	Epic

6. Learning Path Badges -- Earned through path completion.

Badge	Criteria	Rarity
Path Finder	Complete 1 Learning Path	Uncommon
Path Walker	Complete 3 Learning Paths	Rare
Path Master	Complete 10 Learning Paths	Epic
[Path-Specific]	Complete a specific path	Varies

7. Cooperation Badges -- Earned through community participation.

Badge	Criteria	Rarity
Team Player	Contribute to 1 community goal	Common
Community Champion	Contribute to 5 community goals	Uncommon
Group Finisher	Complete 3 group challenges	Uncommon
Reliable Partner	Complete 10 group challenges	Rare

Special Badges -- Limited or unique circumstances.

Badge	Criteria	Rarity
Early Adopter	Join during launch period	Legendary
Challenge Creator	Have user-created challenge approved	Rare
Inspiration	Have TR featured in challenge gallery	Rare
Helpful	Receive 100 total thumbs-up on TRs	Rare

Challenge-Specific Badges -- Some challenges award unique badges on completion (defined by the challenge creator).

Badge Rarity

Rarity determines both the visual presentation and the XP bonus awarded when earned.

Rarity	Visual	XP Bonus	Typical Criteria
Common	Bronze border	+10 XP	Early milestones, easy to achieve
Uncommon	Silver border	+25 XP	Moderate effort
Rare	Gold border	+50 XP	Significant dedication
Epic	Purple border, subtle glow	+100 XP	Exceptional achievement
Legendary	Prismatic/rainbow, animated	+250 XP	Extremely rare or limited

The BadgeCard component renders these rarity tiers with distinct colors (gray, green, blue, purple, yellow) and glow effects that intensify with rarity.

Badge Display

Profile showcase: Users select up to 5 badges to display prominently (rendered by BadgeShowcase). The full collection is viewable in the "My Badges" tab (rendered by BadgeCollection), organized by category and sortable by date earned or rarity. Unearned badges are shown as locked silhouettes with criteria.

Badge detail view (via the modal in BadgeCollection): Badge image, name, description, date earned, rarity, how many users have it, source (which challenge/action earned it), and a "How to earn" section for unearned badges.

Badge notifications: In-app celebration via NewBadgeModal when earned (confetti, rarity-colored gradient header, XP bonus display). Added to collection immediately. No push notifications for badges. Optional sharing prompt.

Design Decisions on Badges

• Badge trading/gifting: No. Badges are personal achievements and cannot be traded or gifted to other users.
• Assigned vs. self-chosen XP: Challenges assigned by a school or teacher award the same XP as challenges the user selects independently. There is no XP distinction based on how a challenge was initiated.

---

Journey Map

STATUS: BUILT

Component: JourneyMap in src/components/gamification/JourneyMap.tsx | Page: JourneyMap in src/pages/profile/JourneyMap.tsx | Data: categoryCounts from UserGamificationStats type; currently uses hardcoded mock data in page | 12 territory regions defined

The Journey Map is a visual representation of exploration across all challenge categories -- the centerpiece of the mastery/collection experience.

Concept

A stylized map where each region represents a challenge category. The core appeal is watching the map fill in over time -- the satisfaction of revealing new territory and developing mastery.

Region States

State	Criteria	Visual
Unexplored	0 completions	Dense fog, only silhouette. Lock icon. Dimmed to 50% opacity.
Discovered	1+ completions	Fog clearing, terrain visible. Completion count shown.
Explored	5+ completions	Full terrain, landmarks appear.
Advanced	15+ completions	Rich detail, special features.
Mastered	30+ completions	Golden border, "Mastered" banner. Checkmark icon.

The current JourneyMap component implements Unexplored, Discovered (1+ completions), and Mastered (5+ completions) states as a grid of territory cards. Each territory has an emoji, name, color, and completion count.

STATUS: PARTIAL

The current implementation uses a flat grid layout with emoji icons and basic fog/reveal. The spec envisions a richer stylized world map with interconnected territories, zoom levels (zoomed-out full map vs. zoomed-in single region), individual challenge markers within regions, and pulsing indicators for in-progress challenges. The 5-tier region state system (Unexplored/Discovered/Explored/Advanced/Mastered) is partially implemented -- the component currently treats 5+ completions as "Mastered" rather than the spec's 30+ threshold. Integration with real category data from the backend is pending.

Map Interactions

Tap/click a region shows: Region name and category, completion count and progress to next tier, "Explore This Category" button (filters Explore page), and list of completed challenges in the region.

Zoom levels: Zoomed out shows the entire map with overall exploration progress. Zoomed in shows a single region with individual challenge markers.

Progress stats: "X of Y regions discovered," "X regions explored, Y regions mastered," and percentage of total map revealed.

Integration with Other Features

• Dealer's Choice: DC "Uncharted" cards highlight unexplored regions. Completing Uncharted DC triggers a map reveal animation.
• Best Fit algorithm: Can suggest challenges to fill in map gaps. "Discover a new region" option in recommendations.
• Badges: Category badges appear as landmarks when earned. "Reveal the whole map" is an implicit collection goal.

---

Weekly Streaks

STATUS: BUILT

Types: STREAK_CONFIG constant (grace period + milestone thresholds) in src/types/gamification.types.ts | Store: currentStreak in useGamificationStore | API: calculateStreak() function in gamification.api.ts (uses ISO week keys for consecutive-week tracking) | Component: StreakDisplay (flame icon with color intensity based on streak length)

Streaks reward consistent activity without creating daily pressure.

Streak Definition

A streak is maintained by completing at least one challenge per week (7-day rolling window).

Why weekly, not daily: Real-world challenges take time. It respects that users have lives outside the app, reduces anxiety and guilt, and aligns with the "off-screen first" principle.

How it works: User completes a challenge. A 7-day window begins. Complete another challenge within 7 days to continue the streak. Streak count equals consecutive weeks with at least one completion.

Streak Rewards

Milestone	Bonus XP	Badge	Ongoing Multiplier
2 weeks	+25 XP	Getting Regular	--
4 weeks	+50 XP	Steady Pace	1.1x on completions
8 weeks	+75 XP	Dedicated	1.1x
12 weeks	+100 XP	Committed	1.2x
26 weeks	+150 XP	Marathon Runner	1.2x
52 weeks	+500 XP	Year of Curiosity	1.2x (cap)

The StreakDisplay component uses color intensity to reflect streak length: gray for under 4 weeks, yellow from 4 weeks, orange from 12 weeks, and red from 26 weeks. The flame icon uses a CSS flicker animation when the streak is active.

Streak Forgiveness

Grace period: If the 7-day window expires, the user has an additional 3 days to complete a challenge and save their streak. The messaging is: "Your streak is at risk! Complete a challenge by [date] to keep it going." The grace period can only be used once per streak (resets after a completion).

DECISION PENDING

Streak freeze mechanic: Under review as part of the broader gamification strategy evaluation. A freeze would allow users to "bank" freeze days to preserve a streak during vacations or unavoidable breaks. The grace period above is sufficient for the initial implementation.

Streak Display

Current streak is prominently shown on the dashboard. The streak flame icon grows at milestones. "Streak at risk" warning appears when in the grace period (in-app only, no push). Longest streak ever is recorded on the profile.

Streak Break

If a streak breaks: Gentle message -- "Your streak ended at X weeks. Start a new one today!" No punishment, shame, or loss of anything already earned. Previous streak badges remain (you cannot un-earn a badge). Longest streak stat is preserved.

---

Learning Paths

STATUS: BUILT

Types: LearningPath, UserPathProgress, PathCheckpoint, PathStatus, UserPathStatus in src/types/learningPath.types.ts | Page: LearningPathDesigner in src/pages/school/LearningPathDesigner.tsx (drag-and-drop builder with search, category filters, step reordering, required/optional toggle, teacher notes) | Mock data: sample "Science Explorers -- 5th Grade" path with 5 steps

Learning Paths are curated challenge sequences for structured progression.

Path Types

Platform Paths -- Created by DoCurious staff. Available to all users. Featured in Explore. Examples: "Outdoor Explorer: Backyard to Backcountry" (12 challenges, Beginner to Advanced), "Kitchen Fundamentals" (8 challenges, cooking skills progression), "Creative Maker Journey" (10 challenges), "Family Adventure Series" (6 challenges, designed for parent-child).

School Paths -- Created by School Admins or teachers. Visible within school context only. Examples: "5th Grade Science Curriculum" (semester-long), "Summer Reading Challenge" (8-week program), "After-School STEM Club" (year-long progression).

Path Structure

Field	Required	Description
Title	Yes	Max 100 characters
Description	Yes	What users will learn/experience (max 500 chars)
Cover image	Yes	Visual representation
Challenges	Yes	Ordered list of 4--20 challenges
Ordering mode	Yes	Recommended (any order) or Strict (sequential)
Checkpoints	No	Milestones with bonus XP
Estimated duration	Yes	"4 weeks," "One semester," etc.
Path badge	No	Unique badge awarded on completion

Path Progression

Recommended ordering (default): All challenges visible from start. Suggested sequence shown but not enforced. User can complete in any order.

Strict ordering: Next challenge unlocks only after previous is verified. Progress shown as a linear path with "You are here" marker. School paths often use strict ordering for curriculum purposes.

Progress tracking: Progress bar showing X of Y challenges completed. Checkpoints award bonus XP when reached. Completion requires all challenges verified.

Starting and Managing Paths

Starting a path: Discover path in Explore (or receive as school assignment), click "Start This Path," path appears in "My Paths" on dashboard, first challenge (or all) ready to begin.

Abandoning a path: User can abandon incomplete paths at any time. No penalty -- completed challenges still count and XP is retained. Can re-start later from scratch.

Path completion: All challenges verified, path badge awarded (if defined), +100 XP bonus, path marked "Completed" on profile.

Path Creation (School Context)

STATUS: BUILT

The LearningPathDesigner page provides a full drag-and-drop builder with challenge search, category filtering, step reordering (up/down), required/optional toggle per step, teacher notes per step, path stats (total steps, total XP, estimated hours, required count), and draft/published/archived status.

Teachers and SAs can create paths: navigate to "Create Learning Path" in dashboard, enter title, description, and cover image, add challenges from library (search/browse), set ordering mode and checkpoints, optionally assign to classes, path available to assigned students.

Editing paths: Can edit before anyone enrolls. After enrollment, can add to the end but cannot remove or reorder.

Design decision -- School path approval: No -- schools are trusted to create appropriate learning paths without DoCurious staff approval.

---

Cooperative Social Features

STATUS: BUILT

Community Goals: CommunityGoals page in src/pages/communities/, GoalCard and GoalDetail components in src/components/community/, useCommunityGoalStore in src/store/, communityGoal.api.ts + communityGoal.real.api.ts in src/api/, types in src/types/communityGoal.types.ts | Group Challenges: GroupChallenge page in src/pages/challenges/

Social gamification emphasizes contribution over competition.

Community Goals

A community sets a collective target that all members contribute to. Example: "Our community will complete 100 challenges this month!"

Field	Description
Title	Goal name
Target	Numeric (completions, XP, or category-specific)
Duration	Start and end dates
Eligibility	Which challenges count (all, category, specific list)
Reward	XP bonus and/or badge for contributors
Minimum participation	Completions required to receive reward (default: 1)

Progress: Visible progress bar in community feed ("73 of 100 -- keep going!"). Recent contributor names shown (celebration, not ranking). Milestone announcements ("Halfway there!").

Completion: When goal is met, celebration in community feed. All contributors meeting minimum participation get the reward. Community earns bragging rights / community badge.

Group Challenges

A group of users commits to complete the same challenge together.

How it works: User initiates group challenge, selects a challenge. Invites 1--4 friends/community members. All participants see shared progress. When all complete: everyone gets +25 XP group bonus. If some complete and others don't: completers get normal XP, no penalty for non-completers.

Visibility: Shared progress visible to group members. Can cheer each other on in group chat (simple, not full messaging). Completion celebrated together.

Difference from Group DC: Group DC (see Explore & Discovery) is a specific Dealer's Choice variant with card dealing. Group Challenges work with any challenge.

Celebration Moments

When users achieve milestones, shareable celebration cards are created:

• Level up: "I just became an Adventurer on DoCurious!"
• Badge earned: Card with badge image and how it was earned
• Path completed: Card with path name and duration
• Streak milestone: "12 weeks and counting!"

Sharing is always user-initiated, never auto-posted. Users can share to communities or export as an image for external sharing (social media, messaging).

Social Proof in Discovery

Gamification data informs challenge discovery without pressure: "47 people completed this" (validation), "Trending: 23 completions this week" (momentum), "Popular with Explorers" (level-based affinity), community feed showing what others are doing. This is information, not ranking or competition.

---

Leaderboards (Opt-In)

STATUS: BUILT

Types: LeaderboardEntry in src/types/gamification.types.ts | Store: leaderboard, leaderboardType, fetchLeaderboard in useGamificationStore | API: getLeaderboard in gamification.api.ts (supports xp/challenges/streak ranking) | Components: LeaderboardTable (ranked list with avatars, top-3 highlighting, current user highlighting), LeaderboardOptIn (settings panel with granular visibility controls, display name options, public/community/school/global toggles)

Leaderboards exist for users who want competitive motivation, but are not the default experience.

Design Principles

• Not prominent: Leaderboards are a feature to seek out, not a homepage element.
• Top performers only: Show top 10--20, not full rankings.
• No shame: Users outside the top tier see their own score, not their rank among lower performers.
• Opt-in at school level: SAs decide whether leaderboards are visible to students.
• Time-bounded: Monthly resets prevent permanent hierarchies.

Leaderboard Types

Leaderboard	Scope	Default State
Platform: Monthly XP	All users platform-wide	Visible (opt-in to view)
Dealer's Choice: Monthly	DC participants	Visible to DC participants
School: Monthly	Students in school	SA controls (default: off)
Class: Monthly	Students in class	Teacher controls (default: off)
Community: Monthly	Community members	Creator controls (default: off)

Age separation: Platform-wide leaderboards separate under-13 and 13+. School/class leaderboards do not separate (same community context).

What Users See

Top performers: Names, levels, XP earned this period (rank 1--10 or 1--20). The LeaderboardTable component highlights the top 3 with colored rank badges (gold, silver, bronze).

Own position: "Your XP: 1,234" -- shown regardless of rank. The current user's row is highlighted with a blue background and a "You" badge.

What is NOT shown: Full rankings below top tier. "You're #47 of 200" for non-top users. Who is at the bottom. Comparative language ("You're behind Sarah by 50 XP").

Leaderboard Opt-In Settings

The LeaderboardOptIn component provides granular controls:

• Master toggle: Show me on public leaderboards (yes/no)
• Granular controls (when opted in): Show on community leaderboards, Show on school leaderboards, Show on global leaderboards
• Display name: Choose between real name, username, or anonymous
• When opted out: Informational panel explaining that progress is still tracked privately, and the user can opt back in at any time

Design decision -- Student leaderboard opt-out: All users (not just students) can opt in or out of leaderboards at any time from their gamification settings.

School Leaderboard Configuration

SAs configure in School Settings:

Setting	Options	Default
School leaderboard visible	Yes / No	No
Class leaderboards visible	Yes / No	No
Who can see	Students only / Students + Parents / All	Students only
Display top N	10 / 20 / 50	10

Teacher override: Teachers can enable class leaderboards for their classes even if school-wide is disabled, with SA permission.

Where to Find Leaderboards

Leaderboards are found in: user Profile ("Leaderboards" tab), Community ("Leaderboard" section, if enabled), School Dashboard ("Leaderboard" section, if enabled). They are NOT on the home dashboard or primary navigation.

---

Anti-Gaming Measures

The system prevents exploitation while keeping the experience positive.

Verification Requirement

XP is only awarded for verified Track Records. Submission alone does not earn XP. See Track Records & Verification for the verification flow.

Rate Limits

Limit	Value	Purpose
Verifications per day	10	Prevent mass-submission
DC rounds per week	5	Prevent DC farming
Streak XP multiplier cap	1.2x	Limit streak advantage

These constants are defined in RATE_LIMITS in src/types/gamification.types.ts.

Quality over Quantity

Track Record verification considers quality (meaningful entries, appropriate documentation). Low-effort TRs may be rejected.

Monitoring

Staff can review suspicious patterns: unusually rapid completions, repeated easy challenges, bot-like behavior. Manual review and adjustment are available. Users can be warned or have XP frozen if abuse is confirmed.

---

Notifications

No push notifications for any gamification event. Everything is discovered in-app.

Event	Channel	Timing
XP earned	In-app animation (XPGainToast)	Immediate
Level up	In-app celebration (LevelUpModal)	Immediate
Badge earned	In-app celebration (NewBadgeModal)	Immediate
Streak at risk	In-app banner	2 days before expiry
Streak broken	In-app message	On next login after expiry
Path checkpoint	In-app celebration	Immediate
Path completed	In-app celebration	Immediate
Community goal milestone	Community feed	On milestone
Community goal achieved	In-app notification	Immediate
Group challenge update	In-app notification	When groupmate completes

---

Roles and Permissions

Action	General User	Student	Parent	Teacher	School Admin	Platform Admin
Earn XP and badges	Yes	Yes	Yes	Yes	--	--
View own stats and XP history	Yes	Yes	Yes	Yes	Yes	Yes
Manage badge showcase (select 5)	Yes	Yes	Yes	Yes	--	--
View Journey Map	Yes	Yes	Yes	Yes	--	--
Opt in/out of leaderboards	Yes	Yes	Yes	Yes	--	--
View leaderboards	Yes	If SA enables	Via student	If SA enables	Yes	Yes
Create Learning Paths	--	--	--	Yes	Yes	Yes
Assign Learning Paths to classes	--	--	--	Yes	Yes	--
Create community goals	Yes (if community creator)	--	--	Yes	Yes	Yes
Enable/disable school leaderboards	--	--	--	--	Yes	Yes
Configure level definitions	--	--	--	--	--	Yes
Manage badge library	--	--	--	--	--	Yes
Manage platform paths	--	--	--	--	--	Yes
Set XP values and multipliers	--	--	--	--	--	Yes
Adjust anti-gaming thresholds	--	--	--	--	--	Yes
Review suspicious XP patterns	--	--	--	--	--	Yes

---

Constraints and Limits

Constraint	Value	Source
Maximum level (standard)	15 (Legend)	MAX_LEVEL constant
XP for Level 15	97,100 cumulative	LEVEL_DEFINITIONS
Prestige levels beyond 15	30,000 XP each	Spec Doc 8 Section 3.1
Badge showcase slots	5	BadgeCollection maxShowcase prop
Streak window	7 days	STREAK_CONFIG
Grace period	3 days	STREAK_CONFIG.gracePeriodDays
Grace period uses per streak	1	Spec Doc 8 Section 6.3
Max streak multiplier	1.2x	RATE_LIMITS.max_streak_multiplier
Max verifications per day	10	RATE_LIMITS.max_verifications_per_day
Max DC rounds per week	5	RATE_LIMITS.max_dc_rounds_per_week
Learning Path challenges	4--20	Spec Doc 8 Section 7.2
Group challenge members	1--4 invitees	Spec Doc 8 Section 8.2
Leaderboard top N (default)	10	getLeaderboard default
Monthly leaderboard reset	Monthly	Spec Doc 8 Section 9.1
Repeat XP floor	10% of base	XP_VALUES.repeat_multiplier
Celebration animations	User can disable	Accessibility setting

---

Design Decisions

These decisions have been resolved and are documented in the spec:

Decision	Resolution	Rationale
Dealer's Choice penalties	XP loss for DC abandonment is confirmed. Sole exception to "No Negative XP" rule. Under-13 exempt.	Risk/reward symmetry makes the DC choice meaningful and prevents abuse.
Leaderboard defaults	Default to off. Users and schools must opt in.	Avoids unintended competitive pressure, especially for younger users.
Streak freeze	Under review. Grace period is sufficient for initial implementation.	Need more data on user behavior before deciding.
School path approval	No staff approval needed. Schools are trusted.	Reduces friction for educators.
Badge trading/gifting	Not allowed. Badges are personal achievements.	Preserves meaning of individual accomplishment.
Assigned vs. self-chosen XP	Same XP regardless of how challenge was initiated.	No perverse incentive to avoid school assignments.
Student leaderboard opt-out	All users can opt in or out at any time.	Respects user autonomy across all roles and ages.

---

Technical Implementation

Key Files

Purpose	File Path
Types -- Gamification	src/types/gamification.types.ts
Types -- Learning Paths	src/types/learningPath.types.ts
Types -- Community Goals	src/types/communityGoal.types.ts
Store -- Gamification	src/store/useGamificationStore.ts
Store -- Community Goals	src/store/useCommunityGoalStore.ts
API -- Gamification (mock)	src/api/gamification.api.ts
API -- Gamification (real)	src/api/gamification.real.api.ts
API -- Community Goals (mock)	src/api/communityGoal.api.ts
API -- Community Goals (real)	src/api/communityGoal.real.api.ts

Components

Component	File Path	Description
LevelProgress	src/components/gamification/LevelProgress.tsx	XP progress bar with level badge. Sizes: sm/md/lg.
BadgeCard	src/components/gamification/BadgeCard.tsx	Single badge with rarity styling and earned/locked states.
BadgeGrid	src/components/gamification/BadgeGrid.tsx	Grid of badges. Filters, sorts earned-first, rarity ordering.
BadgeCollection	src/components/gamification/BadgeCollection.tsx	Full collection with category filter tabs and detail modal.
BadgeShowcase	src/components/gamification/BadgeShowcase.tsx	Profile top-5 showcase with tier-based styling and tooltips.
NewBadgeModal	src/components/gamification/NewBadgeModal.tsx	Celebration modal with confetti and rarity gradients.
LevelUpModal	src/components/gamification/LevelUpModal.tsx	Level-up celebration with confetti, Scout Green/Brass Gold branding.
XPGainToast	src/components/gamification/XPGainToast.tsx	Animated "+X XP" toast with shimmer effect.
StreakDisplay	src/components/gamification/StreakDisplay.tsx	Streak counter with flame icon and color intensity.
JourneyMap	src/components/gamification/JourneyMap.tsx	Category exploration grid with territory states.
LeaderboardTable	src/components/gamification/LeaderboardTable.tsx	Ranked user list with top-3 highlighting.
LeaderboardOptIn	src/components/gamification/LeaderboardOptIn.tsx	Settings panel for leaderboard visibility controls.
GoalCard	src/components/community/GoalCard.tsx	Community goal progress card.
GoalDetail	src/components/community/GoalDetail.tsx	Community goal detail view.

Pages

Page	File Path	Description
XPHistory	src/pages/profile/XPHistory.tsx	Full XP ledger with filters, running balance, and level summary.
Badges	src/pages/profile/Badges.tsx	Badge collection with showcase selector.
JourneyMap	src/pages/profile/JourneyMap.tsx	Full-page Journey Map view.
LearningPathDesigner	src/pages/school/LearningPathDesigner.tsx	Drag-and-drop path builder for teachers/SAs.
CommunityGoals	src/pages/communities/CommunityGoals.tsx	Community goal management page.
GroupChallenge	src/pages/challenges/GroupChallenge.tsx	Group challenge creation and tracking.

Constants and Utilities

The src/types/gamification.types.ts file exports several critical constants and functions:

• LEVEL_DEFINITIONS -- Array of 15 LevelDefinition objects with level number, name, minXp, maxXp, and color.
• MAX_LEVEL -- 15
• XP_VALUES -- Object with all base XP values, multipliers, penalties, and badge XP bonuses.
• RATE_LIMITS -- Anti-gaming rate limits.
• STREAK_CONFIG -- Grace period days and milestone thresholds with XP bonuses.
• calculateLevel(xp) -- Returns the LevelDefinition for a given cumulative XP total.
• calculateXpProgress(xp) -- Returns { progress, toNext } with percentage and XP remaining.

Database Schema (Backend)

The backend PostgreSQL schema (from the spec) includes these tables: user_progression, xp_events, user_badges, badges, user_streaks, learning_paths, learning_path_challenges, user_path_enrollment, community_goals, community_goal_contributions, group_challenges, group_challenge_members, level_definitions, leaderboard_settings, leaderboard_snapshots. All IDs are UUIDs. All timestamps in UTC. The adapter layer in src/adapters/ handles SQL-to-FE type mapping.

---

Related Features

• Challenge System -- Challenges are the core content that generates all XP. Difficulty levels drive base XP values.
• Track Records & Verification -- Verification is the gate that determines when XP is awarded. No verification, no XP.
• Explore & Discovery -- The Explore page is where users discover challenges, Dealer's Choice, and Learning Paths. DC multipliers are a major gamification mechanic.
• Communities & Social -- Community goals and group challenges are cooperative gamification features that live within the community system.
• School Administration -- School Admins and teachers create Learning Paths, configure leaderboard visibility, and manage class-level gamification settings.
• Accounts & Authentication -- User roles determine gamification permissions. Age determines UI adaptation and DC penalty exemptions.