Feature Owner : Joylynne Esportuno
Module : Design (Dual Editor)
Priority : P1
Sprint #4 : Fully Implemented
Date : July 2, 2026
EXECUTIVE SUMMARY
What is this feature ?
Scenario Logic enables branching quest paths using scenario/decision-style nodes, child content, and edge-driven navigation.
Why does it matter ?
Creators need learners to make choices and see different content paths based on those choices.
What's the MVP scope ?
Store scenario nodes, render children, support decision choices, and route through edges. Advanced scoring/feedback gates are follow-up work.
1. USER PAIN POINT & SOLUTION
Wihout Scenario Logic
Linear content cannot represent simulations, branching cases, or consequence-based learning.
Pain Point
Emotional : Creators feel limited.
Functional : Decision paths require manual workarounds.
Business Impact : Scenario-based training is less compelling.
Current State
Creators design branches and learners navigate based on selected choices.
Marketing Hook
"Build decision-based quests where choices shape the journey."
2. 4D FRAMEWORK MAPPING
Diagnose
Reveals missing branch outcomes and incomplete decision paths.
Design
Maps choices, consequences, and scenario children.
Develop
Stores scenario children and branching edges in canvas metadata.
Deliver
Runs branches in Quest Player.
3. USER FLOWS
Entry Point
Visual Canvas scenario or question/decision node.
Success Criteria
Learner choice routes to the intended next node.
Main Flow
Creator creates scenario path.
Creator connects decision outcomes.
Learner reaches decision.
Learner selects choice.
Player routes to target branch.
Edge Cases
When there’s no target edge, show fallback next/end behavior
If there’s an invalid node, skip archived/missing content safely
When permission is denied, block editing by unauthorized users
Decision Points
IF choice has mapped edge, route to target node.
ELSE use linear next behavior or completion fallback.
4. INFORMATION ARCHITECTURE
Primary Information
Scenario prompt
Choices
Branch target
Secondary Information
Feedback/consequence copy
Child nodes
Tertiary Information
xAPI/SCORM response metadata
Actions
Primary CTA : Select choice / Continue
Secondary Actions : Back, preview branch
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.nodesquests.canvas_metadata.edges
Indexes
quests.idis the primary lookup for loading branch graphs
Constraints
Branch edges must reference existing non-archived node IDs before publish
Choice IDs should remain stable so runtime can resolve selected paths
Scenario child data should match supported node schemas
9. API ENDPOINTS
Endpoint 1: GET /api/creator/update-quest-canvas?quest_id=
Purpose: Loads scenario, decision, question, and edge data for editing.
Auth: Creator/editor access required.
Endpoint 2: PUT /api/creator/update-quest-canvas
Purpose: Saves scenario nodes, choices, and branch edges.
Auth: Creator/editor access required.
10. DATA REQUIREMENTS
Frontend Needs
Scenario node ID, label, prompt/context, and child nodes
Choice IDs, choice labels, feedback/outcome text, and status where applicable
Edge source, target, source handle, target handle, and branch label/logic
Archived state so runtime does not route into hidden content
API Calls Frontend Will Make
Editor loads/saves canvas metadata through Visual Canvas APIs
Player loads quest metadata through View Content APIs
Player writes progress/completion through learner APIs
Caching Strategy
Use the already-loaded canvas graph for branch lookup. Do not make a network call for every decision unless analytics are later introduced.
11. PERFORMANCE CONSIDERATIONS
Database Optimization
No additional tables are required for MVP. Branch data lives in
canvas_metadata.edges, avoiding extra joins during playback.
Client Optimization
Branch lookup should be in-memory from loaded canvas metadata.
Caching Strategy
Cache the loaded graph for the runtime session.
API Response Time
Decision selection should feel instant. Progress writes may happen after selection, but navigation should not require a slow branch-resolution API call.
12. SECURITY & AUTHORIZATION
Who Can Access This Feature?
Creator: Can author scenario and branch logic
Learner: Can execute published/shared branch logic at runtime
Reviewer: Can inspect scenario logic through review/preview surfaces
Authorization Logic
Creators must own or be allowed to edit the quest before saving scenario changes. Learners can only access scenario runtime through published, enrolled, or shared quests.
13. ERROR HANDLING
Missing edges or node data will block quest publish action due to the Validation Error feature. For reference, see
lib/validation/quest-validation.ts.
14. TESTING CHECKLIST
Happy Path
Choice routes to expected target
Multiple choices route to distinct valid nodes
Progress tracks visited branch
Preview matches published runtime
Edge Cases
Missing edge fallback works
Archived node is skipped/blocked
Invalid choice data does not crash player
Disconnected branch is flagged by validation
15. OPEN QUESTIONS
For Frontend:
Should wrong/partial/correct choices gate progression?
For Backend:
Should branch outcomes have dedicated analytics?
Should decision responses be persisted as first-class result records?
16. OUT OF SCOPE
Adaptive scoring
AI branch generation polish
17. SUCCESS METRICS
Branch completion rate
Decision interaction success rate
Scenario publish validation success
18. DEPENDENCIES
This feature depends on:
Visual Canvas nodes and edges
Quest Player branch navigation
Canvas validation
Question/choice schemas
These features depend on this:
Social Debrief paths after learner decisions
xAPI/SCORM response tracking for decision choices
19. TIMELINE & OWNERSHIP
Backend: Joylynne Esportuno
Frontend: Joylynne Esportuno
QA: Patrick Babala
Estimated Completion: Fully implemented
