Feature Owner: Krizha Onise T. Cortez and James Derick Billate
Module: Develop
Priority: P0
Date: July 2026
Executive Summary
What is this feature?
The Gamification System allows creators to configure quest rewards while enabling administrators to manage platform-wide achievements and badge triggers. Learners automatically earn XP, motivation points, badges, achievement progress, and leaderboard rankings as they complete quests.
Why does it matter?
Gamification encourages learner engagement by providing visible progress, rewards, and achievements throughout the learning journey while reducing manual reward management for creators and administrators.
What's the MVP scope?
Configure quest XP rewards
Configure motivation point rewards
Configure quest completion badges
Configure leaderboard participation
Manage global achievements
Manage badge triggers
Automatically synchronize learner achievements
Display learner leaderboard rankings
Per node XP configuration
Learner XP acquisition per node navigation
Save state and reset progress XP acquisition logic
1. User Pain Point & Solution
Without Gamification
Learners complete quests without meaningful recognition or long-term progression.
Pain Points
Emotional
Learners have little motivation to continue progressing.
Functional
Reward tracking and achievement management would require manual administration.
Business
Reduced learner engagement and lower platform retention.
Current State
Quest completion automatically rewards learners while achievement progress and leaderboard rankings are synchronized across the platform.
2. User Pain Point & Solution
Diagnose
Identifies learner progress through accumulated statistics and quest completion.
Design
Allows creators and administrators to configure rewards and achievement rules.
Develop
Automatically synchronizes learner achievements and leaderboard rankings.
Deliver
Displays rewards, badges, achievement progress, and rankings throughout learner-facing pages.
3. USER FLOWS
Entry Points
Creator
/creator/gamification
Administrator
/admin/global-achievements
Learner
Leaderboard and Achievement pages
Success Criteria
Quest rewards save successfully.
Global achievements are managed successfully.
Learner achievements synchronize automatically.
Leaderboard rankings display correctly.
Main Flow
Creator selects a quest.
Configure quest rewards.
Upload badge (optional).
Save gamification settings.
Administrator manages global achievements.
Learner completes quests.
Achievement progress synchronizes.
Leaderboard updates automatically.
Edge Cases
No existing configuration
Load default gamification values.
Invalid reward configuration
Prevent saving and display validation errors.
Asset upload failure
Display upload error without saving invalid badge.
Decision Points
IF a quest already has gamification settings
→ Load existing configuration.
ELSE
→ Create a new configuration.
4. Information Architecture
Primary Information
Quest Rewards
XP Rewards
Motivation Points
Badges
Achievement Progress
Leaderboard
Secondary Information
Completion Message
Badge Trigger
Bonus XP
XP Progress Display
Tertiary Information
Badge Images
Upload Status
Actions
Primary CTA
Save Configuration
Secondary Actions
Upload Badge
Edit Achievement
Manage Badge Trigger
5. Wireframes
Excluded — Feature fully implemented.
6. WIREFLOWS
Excluded — Feature fully implemented.
7. PROTOTYPE
Excluded — Feature fully implemented.
8.BACKEND SCHEMA
Database Tables
quest_gamifications
Stores quest-specific reward configuration.
global_achievements
Stores administrator-managed platform achievements.
global_badge_triggers
Stores reusable badge trigger definitions.
learner_global_stats
Stores learner statistics used for achievement progression.
learner_achievements
Stores learner achievement progress and unlocked achievements.
9. API Endpoints
Quest Gamification
GET
/api/creator/list-questsReturns available quests.
GET
/api/creator/gamification/[questId]Loads existing quest gamification configuration.
POST
/api/creator/gamification/[questId]Creates a new configuration.
PATCH
/api/creator/gamification/[questId]Updates an existing configuration.
POST
/api/creator/upload-assetsUploads badge images.
Global Gamification
GET /api/admin/global-achievements
Returns all achievements.
POST /api/admin/global-achievements
Creates an achievement.
PATCH /api/admin/global-achievements
Updates an achievement.
DELETE /api/admin/global-achievements
Deletes an achievement.
GET /api/admin/global-achievements/trigger
Returns badge triggers.
POST /api/admin/global-achievements/trigger
Creates a trigger.
PATCH /api/admin/global-achievements/trigger
Updates a trigger.
DELETE /api/admin/global-achievements/trigger
Deletes a trigger.
Learner
GET /api/learner/global-achievements
Returns learner achievement progress.
GET /api/learner/global-stats
Returns learner statistics.
PATCH /api/learner/global-achievements
Synchronizes achievement progress.
GET /api/learner/leaderboard
Returns leaderboard rankings.
10. Data Requirements
Frontend Needs
Quest information
Reward configuration
Badge trigger list
Badge image
Achievement definitions
Learner statistics
Leaderboard rankings
API Calls Frontend Will Make
Load quest configuration
Save quest configuration
Load global achievements
Save global achievements
Upload badge images
Synchronize learner achievements
Retrieve leaderboard data
11. Performance Considerations
Database Optimization
Quest gamification data is stored separately from learner progress to reduce redundant updates. Learner achievements are synchronized only when required rather than recalculating all progress on every request.
12. Security & Authorization
Who Can Access This Feature?
Creator
Configure quest gamification.
Administrator
Manage global achievements and badge triggers.
Learner
View achievements, rewards, and leaderboard rankings.
13. Error Handling
Current Existing Error Handling
Invalid reward values are rejected through shared validation schemas.
Invalid badge uploads return upload errors.
Missing quests return not-found responses.
Missing achievements return appropriate API errors.
Failed learner synchronization is logged and returns an error response.
Leaderboard retrieval failures return server errors without exposing internal details.
More Details
Validation schemas and gamification logic are located within the shared validation and gamification modules used by both creator and learner APIs.
14. Testing Checklist
Happy Path
Create quest gamification
Update quest gamification
Upload badge image
Create global achievement
Update global achievement
Delete global achievement
Create badge trigger
Synchronize learner achievements
Display leaderboard
Edge Cases
Invalid reward values
Missing badge image
Missing learner statistics
Duplicate badge triggers
Leaderboard with no learner data
15. OPEN QUESTIONS
Should seasonal leaderboard resets be supported?
Should achievement unlocks generate notifications?
Should custom achievement formulas be supported in future releases?
16. OUT OF SCOPE
Physical or monetary rewards
Push notifications
Email notifications
Seasonal leaderboard resets
Custom achievement scripting
Manual learner achievement editing
Per node grading
Grading module for all other node types
17. SUCCESS METRICS
Quest reward configuration success rate
Achievement synchronization success rate
Badge unlock rate
Leaderboard retrieval success rate
Learner engagement after quest completion
18. DEPENDENCIES
This feature depends on
Quest Management
Authentication (Clerk)
Supabase Database
Supabase Storage
Asset Upload Service
This feature depends on this
Quest Completion
Learner Dashboard
Leaderboard
Achievement Pages
Quest Player
19. TIMELINE & OWNERSHIP
Backend: Krizha Onise Cortez (armaminter) and James Derick Billate
Frontend: Krizha Onise Cortez (armaminter) and James Derick Billate
QA: Internal development testing
Estimated Completion: Feature completed.
