Adventure Builder

Feature Owner: scorevi (Sean Patrick Caintic)
Module: Diagnose
Priority: P0
Sprint #12: Fully Implemented
Date: 2026-06-29

EXECUTIVE SUMMARY

What is this feature? The Adventure Builder enables creators to compose adventures by sequencing multiple quests using drag-and-drop ordering. It includes a full-page adventure editor, quest sequencer with @dnd-kit, sparse ordering with 10,000 gaps, and multi-SCO SCORM export capability.
Why does it matter? Adventures are the core monetizable content unit on the platform. Creators need an intuitive way to arrange quests into coherent learning journeys, control enrollment settings, and export for LMS distribution.
What's the MVP scope? Full adventure editor page, drag-and-drop quest sequencing, auto-sequencing from AI wizard suggestions, computeQuestOrder() with sparse gaps, adventure metadata management, and multi-SCO SCORM export dialog.

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

Quests exist in isolation. Creators have no way to bundle multiple quests into a structured learning path, control enrollment, or export as a cohesive package for LMS platforms.

Pain Point

Future State

Creators compose adventures by dragging quests into sequence order. They configure enrollment limits, fees, accessibility settings, and export the entire adventure as a multi-SCO SCORM package for any LMS.

Marketing Hook

"Build learning journeys, not just lessons. Drag, drop, and deliver complete adventures."

2. 4D FRAMEWORK MAPPING

3. USER FLOWS

Entry Point

• Creator Dashboard → Adventures tab → "Create Adventure" or "Edit Adventure"

• AI Wizard → auto-created adventure from suggested quests

Success Criteria

• Adventure created with correct metadata

• Quests sequenced with correct order_index values

• Enrollment settings configured and persisted

• SCORM export generates valid multi-SCO package

Main Flow

1. Creator navigates to edit-adventure/[adventureId]/page.tsx (1064 lines)

2. Sets adventure metadata: title, introduction, description, duration, tags, skills

3. Sets enrollment settings: enrollment_count, enrollment_limit, enrollment_fee

4. Configures accessibility_status and is_count_visible

5. Uploads profile_img_url, background_img_url, background_audio_url

6. Opens AdventureQuestSequencer.tsx (464 lines) for quest ordering

7. Drags and drops quests to arrange sequence order

8. System calls computeQuestOrder() to calculate order_index with 10,000 gaps

9. Saves adventure with adventure_sequences junction records

10. Optionally exports via MultiScoExportDialog.tsx

Edge Cases

• Sparse ordering accommodates insertions without re-indexing all quests

• Suggested quests from AI wizard are auto-sequenced on adventure creation

• Empty adventure (no quests): Allowed — quests can be added later

• Large number of quests: Drag-and-drop may require scroll virtualization at scale

• Concurrent edits: Last-write-wins (no optimistic locking in MVP)

Decision Points

• Quest ordering: Manual drag-and-drop vs. AI-suggested order

• Enrollment: Free vs. paid (enrollment_fee)

• Visibility: Public enrollment count visible or hidden

4. INFORMATION ARCHITECTURE

Primary

• Adventure metadata (title, introduction, description, duration, tags, skills)

• Quest sequence order (order_index in adventure_sequences)

• Enrollment settings (enrollment_count, enrollment_limit, enrollment_fee)

Secondary

• Profile image, background image, background audio

• Accessibility status, enrollment count visibility

• adventureFolderId, projectFolderId (DB columns only, not in Zod)

Actions

• Create Adventure, Edit Adventure, Sequence Quests (drag-and-drop), Export SCORM

5. WIREFRAMES

Excluded — existing UI implemented.

6. WIREFLOWS

Excluded — existing UI implemented.

7. PROTOTYPE

Excluded — feature is fully implemented.

8. BACKEND SCHEMA

adventures table (verified columns)

adventure_sequences table

Zod adventureSchema (verified fields)

The Zod schema includes: id, creator_id, title, introduction, description, duration, tags, skills, publishing_status, is_count_visible, accessibility_status, enrollment_count, enrollment_limit, enrollment_fee, profile_img_url, background_img_url, background_audio_url.

The Zod schema does NOT include: adventureFolderId, projectFolderId.

9. API ENDPOINTS

create-adventure special handling (line 34)

When creating an adventure, suggestedQuests is extracted from the request body BEFORE Zod schema parsing. If present:

1. Each suggested quest is auto-created

2. adventure_sequences records are created linking each quest to the adventure

3. order_index is computed with sparse ordering

This allows the AI wizard to suggest a complete quest sequence that gets persisted atomically with the adventure creation.

computeQuestOrder() (adventure-sequence/route.ts:160)

Uses sparse ordering: assigns order_index values with 10,000 gaps between consecutive quests. This allows inserting new quests between existing ones without re-indexing the entire sequence. Example: Quest 1 = 10000, Quest 2 = 20000, Quest 3 = 30000. Inserting between Quest 1 and 2 → 15000.

SCORM Export

• MultiScoExportDialog.tsx handles multi-SCO export

• Each quest becomes a separate SCO within the SCORM package

• Adventure metadata becomes the manifest metadata

10. DATA REQUIREMENTS

Frontend Needs

• Adventure editor page with form fields for all metadata

• AdventureQuestSequencer.tsx with @dnd-kit drag-and-drop

• Quest picker/selector to add quests to adventure

• MultiScoExportDialog.tsx for SCORM export

• Adventure card in content library

API Calls

• POST create-adventure (with optional suggestedQuests)

• GET adventure-sequence (fetch current ordering)

• PATCH adventure-sequence (update ordering after drag-and-drop)

• GET quest list (to populate quest picker)

Caching

• Adventure metadata: Fetch on page load, invalidate on save

• Quest sequence: Refetch after drag-and-drop reorder

• Quest list for picker: Cache briefly, invalidate on new quest creation

11. PERFORMANCE CONSIDERATIONS

DB Optimization

• adventure_sequences: order_index INTEGER for efficient sorting

• Sparse ordering (10,000 gaps) minimizes re-index operations

• GIN index on adventures.skills for filtering

• FK CASCADE on adventure_sequences deletes when adventure is removed

Response Time

• Adventure creation with suggestedQuests: Multiple inserts in single request (may benefit from transaction)

• Drag-and-drop reorder: Single PATCH with new order_index array

• SCORM export: Generation time scales with number of quests and assets

12. SECURITY & AUTHORIZATION

Access Control

• Clerk authentication required on all adventure endpoints

• Creator can only edit/manage their own adventures (RLS)

• verifyContentOwnership() used for edit operations

Auth Logic

• creator_id is TEXT (Clerk string), not UUID

• adventureFolderId and projectFolderId exist in DB but not exposed via Zod — prevents client manipulation

Validation

• adventureSchema (Zod) validates all user-provided fields

• Folder IDs excluded from Zod to prevent unauthorized folder assignment

• Quest sequence order validated server-side

13. ERROR HANDLING

14. TESTING CHECKLISTHappy Path

• Create adventure with metadata only (no quests)

• Add quests to adventure via drag-and-drop sequencer

• Reorder quests and verify order_index updates with sparse gaps

• Insert quest between two existing quests (verify gap usage)

• Create adventure with AI-suggested quests (auto-sequencing)

• Set enrollment_limit and enrollment_fee

• Upload profile image and background media

• Export adventure as multi-SCO SCORM package

• View adventure in content library

Edge Cases

• Adventure with zero quests (should be allowed)

• Adventure with single quest

• Adventure with large number of quests (drag-and-drop performance)

• Reorder to same position (no-op)

• Sparse gap exhaustion (theoretical — 10,000 gaps are large)

• Concurrent sequence edits (last-write-wins behavior)

• Delete quest that is part of adventure (FK cascade removes from sequence)

15. OPEN QUESTIONS

• Should Zod adventureSchema include adventureFolderId and projectFolderId for folder organization features?

• Is pagination needed for the quest picker when creator has many quests?

• Should the sequencer support nested quests (quest groups/chapters)?

16. OUT OF SCOPE

• Quest grouping/chapters within adventures

• Adventure templates (pre-built adventure structures)

• Adventure analytics dashboard

• Prerequisite quest chains (quest B requires quest A completion)

• Learner progress tracking within adventures

17. SUCCESS METRICS

• Number of adventures created per creator

• Average quests per adventure

• Drag-and-drop sequencer engagement (reorder events)

• SCORM export success rate

• Enrollment conversion rate (free → paid adventures)

18. DEPENDENCIES

• @dnd-kit library (drag-and-drop)

• adventure_sequences table with FK cascade

• computeQuestOrder() function (sparse ordering)

• AI Wizard (suggestedQuests auto-sequencing)

• SCORM/xAPI export module (MultiScoExportDialog.tsx)

• quests table (quests must exist before sequencing)

• Migration 20260421 (adventureFolderId), Migration 20260512 (projectFolderId)

19. TIMELINE

Completed — Feature is fully implemented in Sprint #12.

Document Version

1.0 - Initial version - 2026-06-29 08:18 UTC

1.1 - Added Document Version section and update author to have full name - 2026-06-29 08:45 UTC