Learner Map | WyzQuests Documentation

Feature Owner: James Derick Billate
Module: Develop (Content Production)
Priority: Should
Date: July 9, 2026

Executive Summary

What is this feature?

The Learner Map feature allows Learners to navigate their enrolled quests, see their progress, and identify which content is already available or completed. This feature gives Learners a guided map-like experience through quest content using active quest cards, progress indicators, quest navigation circles, completion states, and resume location.

Why does it matter?

Learners need a clear path through their quest experience. If the learning journey does not show progress, completed steps, and available next content, Learners may feel lost or unsure where to continue. The Learner Map keeps the experience guided, motivational, and easier to resume across sessions.

What's the MVP scope?

Learner dashboard entry point.
Active enrolled quest list.
Quest progress percentage and progress bar.
Completed lesson count and total lesson count.
Start or Continue action for each active quest.
Quest Player navigation map with active and completed steps.
Resume support from last saved quest location.
Unlocked content visibility through available quest navigation and current progression.

1. User Pain Point & Solution

John is enrolled in several learning quests but is not sure which one to continue or which lessons are already completed. He wants a visual way to know where he is in the quest, what content is available next, and how much progress remains before completion.

Pain Points

Emotional: Confused, uncertain, and less motivated when progress is not visible.
Functional: No clear view of enrolled quests, current progress, completed lessons, or next available content.
Business: Better learner guidance increases quest continuation, completion rates, and learner satisfaction.

2. 4D Framework Mapping

Diagnose: Shows Learners their current quest progress, completion status, and available learning path.

Design: Provides a guided learning map through quest cards, progress bars, and step navigation.

Develop: Supports continued learning by restoring the Learner's last visited location and showing completed steps.

Deliver: Helps Learners complete quests by making unlocked and available content easier to find and continue.

3. USER FLOWS

Entry Points: Learner logs in and navigates to the Learner Dashboard, opens My Quests, or selects an enrolled quest from /learner.

Success Criteria: Learner can view enrolled quests, see progress, open a quest, navigate available content, and continue from the last saved location.

Main Path (Happy Path)

Learner opens the Learner Dashboard.
System loads active enrolled quests.
Learner views quest cards with progress percentage, completed lessons, total lessons, and remaining time.
Learner selects Start Quest or Continue.
System opens the selected quest.
Quest Player loads quest details and canvas metadata.
System retrieves enrollment progress and saved location.
Learner sees the Quest Map navigation with active and completed steps.
Learner moves through available content.
System marks visited content and updates progress.
Learner sees completed steps reflected in the navigation map.

No Data: Display empty state message when the Learner has no enrolled quests.

API Error: Display error message when enrolled quests or progress cannot be loaded.

Permission Denied: Only authenticated Learners can view their enrolled quests and progress.

Decision Points:

IF Learner has enrolled quests THEN show active quest list ELSE show no-enrollment empty state.
IF quest progress is 0 THEN show Start Quest ELSE show Continue.
IF quest progress is 100 THEN show Completed state.
IF saved location exists THEN restore Learner to saved quest location ELSE start at quest details.
IF content step has been visited or completed THEN show completed state in navigation ELSE show available inactive state.
IF Learner advances to new content THEN update visited cards and progress percentage.

4. Information Architecture

Primary Information

Learner dashboard header.
Active enrolled quest list.
Quest title.
Quest progress percentage.
Completed lessons and total lessons.
Quest Map navigation steps.
Active step indicator.
Completed step indicator.

Secondary Information

Thumbnail image.
Introduction or description preview.
Tags.
Skills.
Duration.
Enrollment fee.
Quest mode.
Folder/project location.

Tertiary Information

Estimated remaining time.
Quest tags.
Quest introduction.
Quest thumbnail.
Enrollment status.
Last saved location.
Achievement summary.
Tertiary Information
Recent activity.
Achievement badges.
Reset progress action for completed quests.
Quest details page.

Actions

Primary CTA
- "Start Quest" for a new quest.
- "Continue" for an in-progress quest.
Secondary Actions
- View All quests.
- Navigate previous or next Quest Map steps.
- Return to Library.
- Complete current activity or question.
- Reset progress for completed quest.

5. Data Requirements

Frontend Needs

Learner enrolled quest list.
Quest title, duration, tags, introduction, thumbnail, and publishing status.
Enrollment status.
Progress percentage.
Visited cards.
Completed nodes.
Last saved location.
Quest canvas metadata with nodes, edges, children, archived flags, and quest mode.
Achievement data.

API Calls Frontend Will Make

GET /api/learner/enrolled-quests
GET /api/learner/get-enrollment?quest_id={questId}
POST /api/learner/update-progress
POST /api/learner/complete-node
GET /api/learner/global-achievements
GET /api/learner/get-quest

6. Performance Considerations

Database Optimization

Filter enrolled quests by authenticated learner ID.
Return only active, in-progress, or ongoing enrollments.
Only show quests with published status.
Batch count content cards or lesson nodes to avoid repeated queries.
Use indexed fields for learner_id, quest_id, status, and publishing_status.

7. Security & Authorization

Who Can Access This Feature?

Administrator: No direct access.
Reviewer: No access.
Creator: No access to Learner's personal quest map.
Learner: Full access to their own enrolled quests and progress.
Agency Admin: No direct access to personal learner map unless through separate agency reporting tools.

8. Error Handling

Current Existing Error Handling

Invalid credentials -> 401 Unauthorized.
Expired session -> 401 Unauthorized with redirect to login.
Learner with no enrollment -> 404 Enrollment not found.
Missing quest_id -> validation error.
Quest not found -> 404 Quest not found.
Node not found in quest canvas -> 404 Node not found in quest canvas.
Failed enrolled quest fetch -> error state in My Quests list.
Failed progress update -> 500 Internal Server Error.
Malformed or legacy progress data -> normalize to default progress structure.

9. Testing Checklist

Happy Path

Learner navigates to Learner Dashboard.
Active enrolled quests load successfully.
Quest card displays progress percentage, completed lessons, total lessons, and remaining time.
New quest shows Start Quest.
In-progress quest shows Continue.
Completed quest shows Completed.
Learner opens a quest from the dashboard.
Quest Player loads details and Quest Map navigation.
Learner advances through available content.
Visited steps are marked completed in the Quest Map.
Progress is saved through update progress API.
Learner exits and returns to the quest.
System restores the saved location.
Quest reaches 100% when completed.

Edge Cases

Learner has no enrolled quests.
Learner tries to open a quest without enrollment.
Learner opens a quest that is no longer published.
Quest contains archived nodes.
Quest has no canvas nodes.
Quest has a long map with more steps than visible navigation slots.
Progress exists in legacy numeric format.
Progress exists but saved location references missing node.
Progress update fails while Learner continues viewing content.
Unauthorized user cannot access learner dashboard or progress APIs.

10. OPEN QUESTIONS

Should locked future content be visually shown as locked, or should the map only show currently available navigation steps?
Should exploration-mode quests allow Learners to jump to any unlocked node, or only follow completed path history?
Should completed quests allow review mode without resetting progress?
Should achievements be tied directly to Quest Map milestones?
Should the Learner Map show lesson titles for every step, or keep compact numbered navigation only?

11. OUT OF SCOPE

Instructor-facing learner progress map.
Manual unlocking by Creator or Admin.
Prerequisite rules across multiple quests.
Advanced branching map visualization.
Offline progress sync.
SCORM cmi.location persistence improvements.

12. SUCCESS METRICS

Learner can view enrolled quests from the Learner Dashboard.
Learner can see quest progress and completed lesson count.
Learner can navigate the Quest Map inside Quest Player.
Learner can identify completed and active steps.
Learner can resume from saved progress.
Learner can complete a quest and see completed state.

18. DEPENDENCIES

This feature depends on

Clerk Authentication
Supabase Database
Quest Enrollments
Quest Canvas Metadata
Learner Progress API
Quest Player
Quest Navigation UI
Gamification and Achievements

This feature depends on this

Learner Dashboard
Quest Detail Page
Quest Player Rendering Engine
Progress Tracking
Achievement Display

This feature depends on this

Quest Editor
Adventure Editor
Creator Content Library
Trash Content Management
Publishing Status Workflow

19. TIMELINE & OWNERSHIP

Backend: James Derick Billate

Frontend: James Derick Billate

QA: Internal development testing

Estimated Completion: Feature completed.

Note: API Endpoints and Schema please refer to its Technical Documentation