Feature Owner: Krizha Onise T. Cortez (armaminter) and James Derick Billate
Updated by: Patrick Babala
Module: Develop
Priority: P0
Status: Handoff — Updated and Published (v2.0)
Date: 2026-09-30
Issue: wyzlab/WyzQuests #35 — [3.2] Gamification. Related issue: #39 — [3.8] Custom Badges.
PRs covered by this revision: #671 (admin global-achievement/trigger fetching + badge/trigger UI), #680 (motivation pop-ups), #749 (per-quest achievement notifications + agency badge requirements), #791 (per-quest milestone XP rewards), #803 (badge-upload refactor + cleanup).
Companion doc: Internal Technical Guide — Internal-Technical-Guide-Gamification.md (architecture, DB schema, API specs, helpers, ops, testing). This Hand-Off stays product-facing; where engineering depth is needed it cross-references the ITG instead of duplicating it.
Note: sub-issue numbers beneath #35 / #39 could not be enumerated without GitHub access and are intentionally not fabricated here. Add them when GitHub is reachable.
Executive Summary
What is this feature?
The Gamification System allows creators to configure quest rewards while enabling administrators to manage platform-wide achievements, badge triggers, and agency-wide badge requirements. Learners automatically earn XP (including milestone XP along the way), motivation points, badges, achievement progress, and leaderboard rankings as they complete quests — and are notified in-app and by email when a badge unlocks.
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 per-quest milestone XP (10% / 50%)
Configure quest completion badges
Configure leaderboard participation
Manage global achievements
Manage global badge triggers
Manage agency-wide badge requirements
Automatically synchronize learner achievements
Notify learners on achievement unlock (in-app + email)
Display learner leaderboard rankings
Per node XP configuration
Learner XP acquisition per node navigation
Save state and reset progress XP acquisition logic
Shipped scope added in v2.0:
Per-quest milestone XP (PR #791): creators set XP granted at 10% ("First Steps") and 50% ("Halfway Hero"), plus the completion reward at 100% ("Quest Champion"). Each milestone is paid once per learner and stored in an idempotent ledger, so progress resets cannot re-farm XP.
Agency-wide badge requirements (PR #749): admins define a badge across an entire agency with conditions (quest completion, perfect score, record time, first attempt).
Per-quest badge conditions and ownership (PR #749): a badge is either creator-managed or agency-managed; agency-managed badges expose condition thresholds (perfect score %, record time minutes, first attempt).
Achievement notifications (PR #749): fresh badge unlocks generate an in-app notification and an email, honoring learner preferences.
Badge-upload UX (PR #803): the badge image is deferred until Save, can be picked from existing assets, and orphaned uploads are cleaned up.
Admin badge/trigger management fixes (PR #671): global achievements and badge triggers load, edit, and delete reliably.
Motivation pop-ups (PR #680): attach a motivational text/image/video/GIF/audio pop-up to a card or node; shown once per card after Continue.
Still deferred: push notifications, seasonal leaderboard resets, custom achievement scripting, manual learner achievement editing, physical/monetary rewards.
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 (completion XP plus 10%/50% milestone XP) while achievements, agency badges, notifications, and leaderboard rankings are synchronized across the platform.
Marketing Hook
"Every step forward is rewarded — milestones, badges, and a place on the leaderboard."
2. 4D Framework Mapping
Diagnose
Identifies learner progress through accumulated statistics, quest completion, and per-quest milestone thresholds.
Design
Allows creators and administrators to configure rewards, achievement rules, agency badge requirements, and notification behavior.
Develop
Automatically synchronizes learner achievements and leaderboard rankings and awards milestone/badge XP server-side.
Deliver
Displays rewards, badges, achievement progress, notifications, and rankings throughout learner-facing pages.
3. USER FLOWS
Entry Points
Creator
/creator/gamification
Administrator
/admin/gamification
Learner
Achievements (/learner/achievements) and Leaderboard (/learner/leaderboard) pages.
Corrected in 2.0: the original Hand-Off listed the Administrator entry point as /admin/global-achievements; the live admin gamification page is /admin/gamification (it hosts Global Badges, Badge Triggers, Agency Badge Requirements, and per-quest configuration).
Success Criteria
Quest rewards (including milestone XP) save successfully.
Global achievements and badge triggers are managed successfully.
Agency badge requirements are managed successfully.
Learners are notified when a badge unlocks.
Learner achievements synchronize automatically.
Leaderboard rankings display correctly.
Main Flow
Creator selects a quest.
Configure quest rewards (base XP, bonus XP, 10%/50% milestone XP, motivation points).
Configure badge (optional): ownership, name, description, triggers/thresholds, image.
Save gamification settings.
Administrator manages global achievements, badge triggers, and agency badge requirements.
Learner progresses through quests.
At 10% / 50% / 100%, the system awards the configured milestone/completion XP (once each).
At 100%, the system evaluates creator badges and agency badge requirements and awards any that pass.
Fresh badge unlocks generate in-app + email notifications.
Achievement progress synchronizes and the 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 an upload error without saving an invalid badge; the orphaned upload is cleaned up.
Milestone XP not configured (0) — No XP is awarded and no ledger row is recorded, so enabling it later still pays.
Quest progress reset — Completion and milestone XP are not re-armed; a learner cannot re-farm rewards.
Agency badge condition not met — The badge stays locked until the condition (perfect score / record time / first attempt) passes.
Learner opted out of notifications — The badge still unlocks; only the notification/email is suppressed.
Decision Points
IF a quest already has gamification settings → Load existing configuration.
ELSE → Create a new configuration.
IF a badge is agency-managed → The condition thresholds and agency-wide requirement apply.
ELSE → The creator-managed quest badge applies.
4. Information Architecture
Primary Information
Quest Rewards
XP Rewards (base, bonus, 10%/50% milestone)
Motivation Points
Badges (quest, global, agency)
Achievement Progress
Leaderboard
Secondary Information
Completion Message
Badge Trigger / condition thresholds
Badge ownership (creator vs agency)
XP Progress Display
Achievement notifications
Tertiary Information
Badge Images
Upload Status
Actions
Primary CTA — Save Configuration
Secondary Actions — Upload Badge, Edit Achievement, Manage Badge Trigger, Manage Agency Badge Requirements
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, including
xp_reward,bonus_xp,points_reward,xp_milestone_10,xp_milestone_50, and badge fields (badge_managed_by,badge_description,perfect_score_threshold,record_time_minutes,first_attempt_required).global_achievements — Stores administrator-managed platform achievements.
global_badge_trigger — Stores reusable badge trigger definitions (corrected in 2.0: the table is singular, not
global_badge_triggers).learner_global_stats — Stores learner statistics used for achievement progression and leaderboard ranking.
learner_achievements — Stores learner achievement progress and unlocked achievements (global and per-quest).
agency_badge_requirements — Stores administrator-defined agency-wide badge requirements.
quest_milestone_earnings — Idempotent ledger recording which milestone XP (
10,50,100) each enrollment has already been paid.
New in 2.0: agency_badge_requirements and quest_milestone_earnings; new columns on quest_gamifications (xp_milestone_10, xp_milestone_50, badge_managed_by, badge_description, perfect_score_threshold, record_time_minutes, first_attempt_required) and on learner_achievements (quest_id). See ITG §4 (Data Model/Schema) for full column lists.
9. API Endpoints
Quest Gamification
GET
/api/creator/list-quests— Returns 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.GET
/api/creator/global-badge-triggers— Returns badge triggers for the creator dropdown.POST
/api/creator/upload-assets— Uploads badge images.DELETE
/api/creator/delete-badge-upload— Cleans up an orphaned badge upload (new in 2.0).
Global & Agency Gamification (Admin)
GET/POST/PATCH/DELETE
/api/admin/global-achievements— Manage achievements (PATCH/DELETE take?id=).GET
/api/admin/global-achievements/badge?id=— Returns a single achievement.GET/POST/PATCH/DELETE
/api/admin/global-achievements/trigger— Manage badge triggers (PATCH/DELETE take?id=).GET
/api/admin/global-achievements/get-trigger?id=— Returns a single badge trigger.GET/POST/PATCH/DELETE
/api/admin/agency-badge-requirements— Manage agency-wide badge requirements (new in 2.0).
Learner
GET
/api/learner/global-achievements— Returns learner achievement progress.PATCH
/api/learner/global-achievements— Synchronizes achievement progress / unlocks.GET
/api/learner/global-stats— Returns learner statistics.GET
/api/learner/quest-achievements— Returns quest-specific and agency badges (locked + earned) (new in 2.0).POST
/api/learner/update-progress— Saves progress and triggers milestone/completion XP and badge evaluation.POST
/api/learner/reset-quest— Resets quest progress (does not re-arm rewards).GET
/api/learner/leaderboard— Returns leaderboard rankings.
Full request/response shapes, auth checks, and the milestone/badge engine are in the ITG §4 (API Specification).
10. Data Requirements
Frontend Needs
Quest information
Reward configuration (base/bonus/milestone XP, motivation points)
Badge trigger list and condition thresholds
Badge image
Achievement definitions (global and agency)
Learner statistics
Achievement notifications and preferences
Leaderboard rankings
API Calls Frontend Will Make
Load/save quest configuration
Load/save global achievements
Load/save agency badge requirements
Upload/clean up badge images
Synchronize learner achievements
Retrieve quest + agency badges
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. Milestone and completion XP are awarded through an idempotent ledger (quest_milestone_earnings) so repeated progress updates never double-pay. Badge images are uploaded only on Save, avoiding orphaned uploads on abandoned forms.
12. Security & Authorization
Who Can Access This Feature?
Creator — Configure quest gamification (scoped to owned or agency resources).
Agency members — Access scoped to agency resources (
verifyAgencyResourceOwnership).Administrator — Manage global achievements, badge triggers, and agency badge requirements.
Learner — View achievements, rewards, notifications, and leaderboard rankings.
Updated in v2.0: authentication is Supabase Auth (not Clerk). The legacy-named app_users.clerk_id column now stores the Supabase auth UUID.
13. Error Handling
Current Existing Error Handling
Invalid reward values (XP 10–1000, milestone XP 0–1000, non-negative bonus/points) are rejected through shared validation schemas.
Creating a configuration for a quest that already has one returns
"Config already exists"— use PATCH.Invalid badge uploads return upload errors; failed saves trigger orphan cleanup.
Missing quests return not-found responses; missing achievements/badges return appropriate API errors.
Re-unlocking an already-unlocked achievement returns HTTP 409 (guarded by
unlocked_at IS NULL).Failed learner synchronization is logged and returns an error response.
Leaderboard retrieval failures return server errors without exposing internal details.
Milestone XP awards are idempotent; a duplicate update is silently ignored (
ON CONFLICT DO NOTHING).Achievement notification/email failures are logged and never block the unlock.
More Details
Validation schemas and gamification logic live in shared/schemas/gamificationSchema.ts, shared/schemas/agencyBadgeRequirementSchema.ts, and lib/gamification/quest-achievements.ts. See ITG §5 (Monitoring & Alerting).
14. Testing Checklist
Happy Path
Create quest gamification
Update quest gamification
Configure and verify 10% / 50% milestone XP and 100% completion XP
Upload badge image (including from the "Pick from assets" overlay)
Create/update/delete global achievement
Create/update/delete badge trigger
Create/update/delete agency badge requirement
Complete a quest and confirm creator badge + agency badge awards
Confirm in-app and email achievement notifications
Synchronize learner achievements
Display leaderboard
Edge Cases
Invalid reward values
Missing badge image
Orphaned badge upload cleaned up after a failed save
Missing learner statistics
Duplicate badge triggers / trigger edit failure (see ITG Known Limitations)
Quest reset does not re-award milestone or completion XP
Achievement already unlocked (no duplicate unlock or notification)
Learner with notifications disabled still unlocks the badge
Leaderboard with no learner data
Agency badge requirement disabled or non-matching agency
Badge configured only with
streak_bonus(not currently awarded — see ITG Known Limitations)
15. OPEN QUESTIONS
Should seasonal leaderboard resets be supported? — Still open. No reset mechanism exists.
Should achievement unlocks generate notifications? — Resolved (v2.0). Yes: fresh unlocks now generate in-app notifications and email, honoring learner preferences (PR #749). Push notifications remain out of scope.
Should custom achievement formulas be supported in future releases? — Still open. Achievements remain limited to predefined learner statistic columns.
16. OUT OF SCOPE
Physical or monetary rewards — still out of scope.
Push notifications — still out of scope.
Email notifications— Resolved (v2.0): email notifications are now in scope and implemented (PR #749).Seasonal leaderboard resets — still out of scope.
Custom achievement scripting — still out of scope.
Manual learner achievement editing — still out of scope.
Per node grading — still out of scope.
Grading module for all other node types — still out of scope.
17. SUCCESS METRICS
Quest reward configuration success rate
Milestone XP award correctness (once per milestone per learner)
Badge unlock rate (quest, global, agency)
Achievement notification delivery rate (in-app + email)
Achievement synchronization success rate
Leaderboard retrieval success rate
Learner engagement after quest completion
18. DEPENDENCIES
This feature depends on
Quest Management
Authentication (Supabase Auth — corrected in v2.0; was "Clerk")
Supabase Database
Supabase Storage
Asset Upload Service
Email service (achievement notifications)
These features depend on this
Quest Completion
Learner Dashboard
Leaderboard
Achievement Pages
Quest Player
Motivation Pop-ups (Form Editor / Visual Canvas)
19. TIMELINE & OWNERSHIP
Original owner / Hand-Off author: Krizha Onise T. Cortez (armaminter) and James Derick Billate.
Implementation updates & current owner: Patrick Babala (author/co-author of PRs #671, #680, #749, #791, #803).
Reviewers: Sean Patrick Caintic (scorevi), Jethro Lagmay (dyorgie) — original review.
Backend: Krizha Onise Cortez and James Derick Billate (original); Patrick Babala (v2.0 updates). Frontend: Krizha Onise Cortez and James Derick Billate (original); Patrick Babala (v2.0 updates).
QA: Internal development testing.
Shipped: core Gamification (Feb–Jul 2026); v2.0 updates merged 2026 (PRs #671, #680, #749, #791, #803).
Estimated Completion: core complete; remaining items are the Out of Scope list above.
References
Issue: wyzlab/WyzQuests #35 — [3.2] Gamification.
Related issue: #39 — [3.8] Custom Badges.
Milestone: [3] Develop (Content Production).
v2.0 PRs: #671 — admin global-achievement/trigger fetching + badge/trigger UI; #680 — motivation pop-ups; #749 — per-quest achievement notifications + agency badge requirements; #791 — per-quest milestone XP rewards; #803 — badge-upload refactor + cleanup.
Companion ITG:
Internal-Technical-Guide-Gamification.md.Offline limitation: sub-issue numbers beneath #35 / #39 could not be resolved without GitHub access.
Version History
2.0 — 2026-09-30 — Patrick Babala. Hand-Off overhaul. Updated the original v1.0 outline in place: Executive Summary and shipped scope; Administrator entry point corrected to
/admin/gamification; Backend Schema corrected (global_badge_trigger, plusagency_badge_requirements,quest_milestone_earnings, new columns); API section extended with milestone, agency, notification, quest-achievements, and badge-cleanup endpoints; per-quest milestone XP, agency badge requirements, achievement notifications, badge-upload UX, and motivation pop-ups added; Clerk → Supabase Auth; References and version history added; Open Questions and Out of Scope retained with status notes. Summary of PRs: #671, #680, #749, #791, #803.1.0 — July 2026 — Krizha Onise T. Cortez and James Derick Billate. Original Hand-Off (quest reward configuration, global achievements, badge triggers, learner synchronization, leaderboard).