Gamification Config and Custom Badges

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

  1. Creator selects a quest.

  2. Configure quest rewards (base XP, bonus XP, 10%/50% milestone XP, motivation points).

  3. Configure badge (optional): ownership, name, description, triggers/thresholds, image.

  4. Save gamification settings.

  5. Administrator manages global achievements, badge triggers, and agency badge requirements.

  6. Learner progresses through quests.

  7. At 10% / 50% / 100%, the system awards the configured milestone/completion XP (once each).

  8. At 100%, the system evaluates creator badges and agency badge requirements and awards any that pass.

  9. Fresh badge unlocks generate in-app + email notifications.

  10. 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, plus agency_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).


Was this article helpful?