View Content

Feature Owner : Joylynne Esportuno
Module : Player
Priority : P1
Sprint #4: Fully Implemented
Date : July 2, 2026

EXECUTIVE SUMMARY

What is this feature ?
View Content is the learner-facing Quest Player that renders published quest content from quests.canvas_metadata.

Why does it matter ?
Learners need one reliable runtime for quests across authenticated access, previews, share links, embeds, and SCORM launches.

What's the MVP scope ?
Render quest details, content nodes, scenario children, questions, progress, and completion states. Advanced offline playback is out of scope.

1. USER PAIN POINT & SOLUTION

Without View Content

Without the player, authored quests cannot be consumed in a consistent runtime.

Pain Point

Emotional : Learners are confused by incomplete playback.
Functional : Progress and branching can become inconsistent.
Business Impact : Published content cannot reliably deliver learning outcomes.

Current State (Already Implemented)

Learners open a quest and move through supported content with progress saved where applicable.

Marketing Hook

"Turn authored quests into playable learning journeys."

2. 4D FRAMEWORK MAPPING

Diagnose

Shows learner runtime issues through progress/completion behavior.

Design

Consumes the creator's canvas design as source of truth.

Develop

Supports content, quiz, scenario, discussion, and media renderers.

Deliver

Delivers quests through app, share, embed, SCORM, and xAPI-aware contexts.

3. USER FLOWS

Entry Point

app/quests/[id]/page.tsx, app/share/[hash]/page.tsx, or app/scorm/[questID]/page.tsx.

Success Criteria

Learner can view content, navigate, answer activities, and persist progress if authenticated.

Main Flow

1. Load quest.

2. Render details step.

3. Render active node or scenario child.

4. Save visit/completion state.

5. Continue until end state.

Edge Cases

• Show unavailable/not found state

• On API errors, show error and allow retry/reload

• Block unpublished or unauthorized content

Decision Points

• IF shared link + anonymous user, continue without durable progress

• ELSE save progress to enrollment

4. INFORMATION ARCHITECTURE

Primary Information

• Quest title

• Current node content

• Navigation state

Secondary Information

• Completion/progress status

• Question feedback

Actions

Primary CTA : Next / Submit
Secondary Actions : Back, copy/share, open linked content

5. WIREFRAMES

Excluded — Feature fully implemented.

6. WIREFLOWS

Excluded — Feature fully implemented.

7. PROTOTYPE

Excluded — Feature fully implemented.

8. BACKEND SCHEMA

Database Tables

• quests.canvas_metadata

• quest_enrollments.progress

• Activity/question result tables where applicable

9. API ENDPOINTS

Endpoint 1: GET /api/learner/get-quest

Purpose: Loads the published quest payload for authenticated learner playback.
Auth: Required for normal learner route.
Frontend Use: Called before initializing the player state.

Endpoint 2: GET /api/learner/get-enrollment

Purpose: Loads learner enrollment and saved progress.
Auth: Required.
Frontend Use: Determines visited nodes, completed nodes, and resume behavior.

Endpoint 3: POST /api/learner/update-progress

Purpose: Persists node visit/progress updates.
Auth: Required.
Frontend Use: Called when learner reaches a new node or step.

Endpoint 4: POST /api/learner/complete-node

Purpose: Persists completion metadata for interactive nodes.
Auth: Required.
Frontend Use: Called after valid completion of quiz/reflection/question/code-style nodes.

Endpoint 5: POST /api/learner/submit-activity-answers

Purpose: Submits activity answers and receives scoring/feedback.
Auth: Required for durable learner progress.
Frontend Use: Called from activity/question submit actions.

Endpoint 6: GET /api/creator/public-share/view

Purpose: Loads quest content for public shared links.
Auth: Public share token/hash.
Frontend Use: Used by share-link player entry points.

10. DATA REQUIREMENTS

Frontend Needs

• Quest ID, title, description, introduction, duration, tags, skills, and cover/profile image.

• canvas_metadata.nodes, canvas_metadata.edges, and quest_mode.

• Node data for each supported renderer: text, media, quiz/question, reflection, code, discussion, file, link, and scenario children.

• Enrollment progress including visited node IDs and completed node map.

• SCORM/xAPI launch configuration when loaded from LMS routes.

API Calls Frontend Will Make

• Quest payload load on page entry.

• Enrollment/progress load after authentication.

• Progress update when learner visits a new node.

• Completion/answer submission when learner finishes an interactive node.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

• Quest load should retrieve the published quest and its canvas metadata in one request where possible. Enrollment queries should filter by learner ID and quest ID.

Client Optimization

• Avoid re-rendering the entire player when only answer selection changes. Progress writes should not fire repeatedly for the same node visit.

Caching Strategy

• Keep loaded quest metadata in local component state for the runtime session. Do not cache learner-specific progress globally because it can change after every node completion.

API Response Time

• Target initial quest load should feel interactive within 1-2 seconds on normal connections. Activity submission should return quickly enough that learners do not double-submit.

12. SECURITY & AUTHORIZATION

Who Can Access This Feature?

• Learner: Can view published/enrolled quests.

• Creator: Can preview owned quests through editor/preview routes.

• Reviewer: Can view only through authorized review contexts.

• Anonymous Shared Viewer: Can view only through valid public share links.

Authorization Logic

• Normal learner routes require authenticated access and a published/enrolled quest. Preview routes must verify creator ownership or authorized role. Share routes must verify the share hash/token and any expiration/revocation rules.

13. ERROR HANDLING

401 Unauthorized: Show a sign-in prompt for protected quest routes. For shared links, only require login if the share mode or progress-saving behavior requires an authenticated learner.

403 Forbidden: Show an access-denied message when the learner is not enrolled, the quest is unpublished, or the user does not have permission to preview. Do not expose creator-only details in the message.

404 Not Found: Show a quest unavailable state when the quest ID, share hash, or SCORM quest ID cannot be resolved.

500 Server Error: Show a generic retry message and keep the current local player state when possible. Avoid clearing selected answers or navigation history unless reload is required.

14. TESTING CHECKLIST

Happy Path

• Published quest loads for enrolled learner.

• Learner progresses through details, content, and interactive nodes.

• Progress updates and survives refresh.

• Share link renders public quest content.

• SCORM launch renders hosted player.

Edge Cases

• Unauthorized unpublished quest is blocked.

• Invalid activity payload does not advance progress.

• Share link expired/missing shows unavailable state.

• Progress API failure keeps learner on current step.

15. OPEN QUESTIONS

For Frontend:

• Should anonymous share progress persist locally between browser sessions?

• Should the player show a different progress warning for share-link users?

For Backend:

• Should SCORM resume support be expanded beyond current location tracking?

• Should player progress writes be batched to reduce API calls?

16. OUT OF SCOPE

• Offline bundled playback

17. SUCCESS METRICS

• Quest start-to-completion rate

• Player error rate

• Activity submission success rate

18. DEPENDENCIES

This feature depends on:

• Quest publishing and validation

• Canvas metadata being saved correctly

• Enrollment APIs for authenticated learner progress

• Renderer components for each supported node/card type

These features depend on this:

• Multi-SCO Export

• Social Debrief runtime

• Scenario Logic runtime

• Learner completion/progress reporting

19. TIMELINE & OWNERSHIP

Backend: Joylynne Esportuno
Frontend: Joylynne Esportuno
QA: Christian Denzon
Estimated Completion: Fully implemented