Adventure Folder Structure | WyzQuests Documentation

Feature Owner: scorevi (Sean Patrick Caintic)
Module: Organization
Priority: P1
Sprint #12: Fully Implemented & Deployed
Date: 2026-06-29

EXECUTIVE SUMMARY

What is this feature?
Parallel folder hierarchy system for adventures, mirroring [11.1] Project Folder Structure. Uses a separate adventure_folders table and API routes. Includes orphan detection for tree integrity and an atomic reorder RPC to prevent partial state during drag-drop operations.

Why does it matter?
Adventures represent courses and need their own organizational structure separate from individual quests. A training agency might have dozens of adventures organized by client, industry, or difficulty level.

What's the MVP scope?
Fully deployed. Adventure folder CRUD with nesting. Orphan detection for corrupted trees. Atomic reorder RPC. Move adventures between folders.

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

Adventures share the flat-list problem of quests. No course-level organization.

Pain Point

Emotional: "My courses are mixed in with individual quests. I need them organized separately."
Functional: No adventure-specific folder structure.
Business Impact: Course management becomes unwieldy at scale.

Future State (With Feature)

Adventures organized into their own folder tree. Marketing courses, compliance training, client-specific adventures — all in dedicated folders.

Marketing Hook

"Organize your courses. Keep adventures and quests in their own world."

2. 4D FRAMEWORK MAPPING

Diagnose

Not directly applicable.

Design

Adventure folder structure supports course-level curriculum design.

Develop

Not directly applicable.

Deliver

Not directly applicable.

3. USER FLOWS

Identical to [11.1] Project Folder Structure, but operating on adventure_folders table and adventures.adventure_folder_id.

4. INFORMATION ARCHITECTURE

Same pattern as project folders.

5. WIREFRAMES

Excluded — same UI components as project folders.

6. WIREFLOWS

Excluded.

7. PROTOTYPE

Excluded.

8. BACKEND SCHEMA

Database Tables

CREATE TABLE adventure_folders (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  creator_id UUID NOT NULL REFERENCES app_users(id),
  name TEXT NOT NULL,
  description TEXT,
  parent_folder_id UUID REFERENCES adventure_folders(id),
  order_index INTEGER NOT NULL,
  is_archived BOOLEAN DEFAULT FALSE,
  archived_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
-- Note: No is_expanded column (different from project_folders)
 
ALTER TABLE adventures ADD COLUMN adventure_folder_id UUID REFERENCES adventure_folders(id);

Distinguishing Features

Orphan Detection: Tree builder detects folders referencing missing parent → marks isOrphan: true → counts orphanCount. Response includes roots + orphanCount. (From PR #436 feedback)

Atomic Reorder RPC: reorder_adventure_folders() function ensures all-or-nothing updates — prevents partial state during concurrent drag-drop.

RLS Policies

Mirror project_folders pattern:

adventure_folders_select_own/select_agency/insert_own/update_own/delete_own

9. API ENDPOINTS

GET    /api/creator/adventure-folders?parentFolderId=&treeView=&includeArchived=
POST   /api/creator/adventure-folders
PUT    /api/creator/adventure-folders/[folderId]
DELETE /api/creator/adventure-folders/[folderId]
POST   /api/creator/adventure-folders/reorder
POST   /api/creator/adventure-folders/move-adventures
GET    /api/creator/adventure-folders/search?query=

10. DATA REQUIREMENTS

Same pattern as project folders.

11. PERFORMANCE CONSIDERATIONS

Same pattern as project folders. Atomic reorder RPC prevents partial writes.

12. SECURITY & AUTHORIZATION

Who can access this feature?

Creators for their own folders. Agency admins for team member folders.

Authorization Logic

RLS enforces ownership. Same circular-reference prevention as project folders.

13. ERROR HANDLING

Same patterns as project folders.

14. TESTING CHECKLIST

Happy Path
□ Create adventure folder → appears in tree
□ Move adventure into folder → FK updated
□ Reorder → atomic update via RPC

Edge Cases
□ Orphan folder → detected and flagged, not blocking
□ Concurrent reorder → atomic RPC prevents partial state

15. OPEN QUESTIONS

None — fully implemented.

16. OUT OF SCOPE (v1.1+)

Same scope as project folders.

17. SUCCESS METRICS

Same metrics as project folders, applied to adventures.

18. DEPENDENCIES

This feature depends on:

[11.1] Project Folder Structure — shares folder-helpers.ts and folder-permissions.schema.
[1.8] Adventure Builder — content management.
[W1.4] ApiResponse + [6.1.1] RBAC.

These features depend on this:

Adventure dashboard organization.

19. TIMELINE & OWNERSHIP

Sprint #12: Already deployed.
Backend: scorevi
Frontend: scorevi
Estimated Completion: Complete.

Document Version

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

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