Gamification Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use compose:subagent (recommended) or compose:execute to implement this plan task-by-task.

Goal: Add gamification UI — level display, progress bars, leaderboard, and profile integration.

Architecture: Gamification data (total_points, current_level, level_progress) comes from public_profile endpoint. No dedicated gamification API exists. We display stats on profiles and create a leaderboard by aggregating member data.

Tech Stack: React 19, TanStack Router, TanStack React Query, shadcn/ui

---

File Structure

src/
├── components/gamification/
│   ├── LevelBadge.tsx                  # Level badge with icon + name
│   ├── ProgressBar.tsx                 # Points progress bar
│   ├── GamificationStats.tsx           # Full stats display
│   └── Leaderboard.tsx                 # Top members by points
├── routes/
│   └── leaderboard.tsx                 # Leaderboard page

---

Task 1: LevelBadge Component

Files:

• Create: src/components/gamification/LevelBadge.tsx

• [ ] Step 1: Create level badge

Props: level (number), levelName (string), size ('sm' | 'md' | 'lg')

Display:

• Colored badge with level number

• Level name text

• Gradient background based on level tier:

  • 1-3: gray (iniciante)
  • 4-6: blue (intermediário)
  • 7-9: purple (avançado)
  • 10+: gold (expert)

• Size variants for different contexts

• [ ] Step 2: Commit

---

Task 2: ProgressBar Component

Files:

• Create: src/components/gamification/ProgressBar.tsx

• [ ] Step 1: Create progress bar

Props: current (number), max (number), label? (string)

Display:

• Horizontal bar with gradient fill

• Percentage text

• Points text: "{current}/{max} pontos"

• Animated fill on mount

• [ ] Step 2: Commit

---

Task 3: GamificationStats Component

Files:

• Create: src/components/gamification/GamificationStats.tsx

• [ ] Step 1: Create stats display

Props: stats (gamification_stats object)

Display:

• LevelBadge with current level

• Total points with Trophy icon

• ProgressBar showing progress to next level

• Points to next level text

• Card layout with icon decorations

• [ ] Step 2: Commit

---

Task 4: Leaderboard Component

Files:

• Create: src/components/gamification/Leaderboard.tsx

• [ ] Step 1: Create leaderboard

This is a client-side leaderboard since there's no API endpoint. It uses useCommunityMembers() to get members, then sorts by gamification_stats.total_points.

Implementation:

• Fetch members via useCommunityMembers from '@/lib/api/spaces'

• Sort by gamification_stats.total_points (descending)

• Show top 20 members

• Each row: rank (#), avatar, name, level badge, total points

• Current user highlighted

• Loading skeleton

• Empty state

• [ ] Step 2: Commit

---

Task 5: Leaderboard Page Route

Files:

• Create: src/routes/leaderboard.tsx

• [ ] Step 1: Create leaderboard page

Standard shell layout with Leaderboard component.

• [ ] Step 2: Commit

---

Task 6: Enhance Profile Pages

Files:

• Modify: src/routes/profile.tsx

• Modify: src/routes/members/$memberId.tsx

• [ ] Step 1: Add gamification to profiles

Add GamificationStats component to both profile pages when gamification_stats is available.

• [ ] Step 2: Commit

---

Task 7: Add Leaderboard Link

Files:

• Modify: src/components/circle/Sidebar.tsx

• [ ] Step 1: Add leaderboard to sidebar

Add a "Leaderboard" link with Trophy icon in the sidebar navigation.

• [ ] Step 2: Commit

---

Task 8: Verify Build

• [ ] Step 1: Run typecheck
• [ ] Step 2: Run build
• [ ] Step 3: Fix any issues