[1.8] Adventure Builder

1. Front Matter

• Title: Adventure Builder

• Author: scorevi (Sean Patrick Caintic)

• Reviewers: dyorgie (Jethro Lagmay)

• Created: February 2026

• Status: Approved

• References:

  • Issue: [1.8] Adventure Builder #30

  • Milestone: [1] Diagnose (Project Setup)

2. Introduction & Goals

• Problem Summary: Creators need to group multiple quests into sequential learning paths called "Adventures" to provide structured curriculum design for learners.

• Goals:

  • Enable grouping of published quests into adventures

  • Provide drag-and-drop ordering capability

  • Support adventure metadata (title, description, thumbnail)

  • Ensure only published quests can be added

• Non-Goals:

  • Nested adventures

  • Quest auto-ordering based on dependencies

  • Adventure templates

• Glossary:

  • Adventure: A curated sequence of quests forming a learning path

  • DnD: Drag and drop (UI interaction pattern)

3. High-Level Architecture

• System Diagram:

• Technologies Used:

  • @dnd-kit/core - Drag and drop framework

  • @dnd-kit/sortable - List reordering

  • React Hook Form - Form management

  • Supabase - Data persistence

4. Detailed Design & Implementation

• Data Model / Schema: adventures table:

• API Specification:

  • POST /api/creator/create-adventure - Create adventure

  • GET /api/creator/adventures/[id] - Fetch adventure

  • PATCH /api/creator/adventures/[id] - Update adventure

  • DELETE /api/creator/adventures/[id] - Delete adventure

  • Create request body: title (string, required), description (string, optional), quest_ids (UUID[], required)

• Logic & Workflows: Adventure creation flow:

  1. Creator clicks "Create Adventure"

  2. Fill in title, description

  3. Select published quests from picker

  4. Drag to reorder quests

  5. Submit → API creates record

  6. Redirect to adventure detail

• Quest Selection:

  • Filter: Published quests only

  • Search: By title

  • Preview: Quest details before adding

  • Validation: No duplicates

• Key Files:

  • app/creator/adventure-builder/page.tsx - Builder page

  • components/creator/QuestSelector.tsx - Quest picker

  • components/creator/QuestOrderList.tsx - DnD reorder list

5. Infrastructure & Operations

• Dependencies:

  • Supabase - Adventure storage

  • Supabase Storage - Thumbnail storage

• Monitoring & Alerting: No specific monitoring required.

• Deployment Plan:

  1. Run adventures table migration

  2. Deploy UI components

  3. No feature flags needed

6. Testing & Quality Assurance

• Test Strategy:

  • Manual: Create, reorder, update adventure

  • E2E: Full adventure creation flow

• Known Limitations:

  • Max 50 quests per adventure (UI performance)

  • No nested adventures

  • Only published quests can be added

7. Maintenance & Support

• Troubleshooting:

  • Quests not showing in picker → Verify quest is PUBLISHED

  • Drag not working → Check DnD sensors, touch support

  • Order not saving → Verify quest_ids array format

• Changelog:

  • 1.0 (Feb 2026): Initial implementation

Document Version

1.0 - Approved, Feature deployed to production, 02/25/2026