Project Folder Structure | WyzQuests Documentation

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

EXECUTIVE SUMMARY

What is this feature?
Hierarchical folder organization for quests and adventures. Supports drag-and-drop via @dnd-kit, breadcrumb navigation, infinite-depth tree view (max 20 levels), folder search, and bulk move operations. Folder-level permissions (view/edit/admin/owner) provide granular access control.

Why does it matter?
Creators accumulate dozens or hundreds of quests. Without folders, the content library is a flat, unmanageable list. Folders enable project-based organization, team sharing via permissions, and quick content discovery.

What's the MVP scope?
Fully deployed. Folder CRUD with nesting. Drag-and-drop reorder and move. Tree view with expand/collapse. Breadcrumb navigation. Search across folder paths. Bulk move projects into folders. Folder permissions.

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

All quests and adventures appear in a flat list. Creators with 50+ items must scroll and search with no organizational structure.

Pain Point

Emotional: "I have 100 quests and I can't find the one I need. It's chaos."
Functional: No content organization beyond search.
Business Impact: Creator productivity severely limited as content scales.

Future State (With Feature)

Creators organize content into nested folders: "Client Projects → Acme Corp → Onboarding Quest". Drag and drop to reorganize. Tree view navigates the hierarchy. Search finds content across all folders.

Marketing Hook

"Organize your content library like a pro. Folders, drag-and-drop, instant search."

2. 4D FRAMEWORK MAPPING

Diagnose

Folder structure helps diagnose content organization gaps.

Design

Project-based folder structure supports the Design methodology.

Develop

Not directly applicable.

Deliver

Not directly applicable.

3. USER FLOWS

Entry Point

Creator navigates to Content Library in their dashboard.

Success Criteria

Content organized into folders. Tree view navigable. Drag-and-drop functional.

Main Flow (Happy Path)

Creator clicks "New Folder" → FolderModal opens
Enters folder name → folder created at current level (or as child)
Drag-and-drop:
- Drag folder onto another → becomes child (max depth 20)
- Drag quest/adventure into folder → project_folder_id updated
- Drag to reorder → order_index updated (10,000-gap sparse ordering)
Tree view (FolderTreeView) shows expandable hierarchy
Breadcrumb (FolderBreadcrumb) shows: Home > Client Projects > Onboarding
Click folder in tree → list filters to that folder's contents
Right-click folder → context menu: Rename, Delete, Move, Permissions

Edge Cases

No data: Empty folder → "This folder is empty" state.
API error: Move creates circular reference → checkIsDescendant() blocks it.
Permission denied: Non-owner accessing → folder not visible.

Decision Points

IF depth exceeds 20 → move blocked: "Maximum folder depth reached."
IF folder has children → delete warns about content relocation.
IF folder is archived → hidden unless ?includeArchived=true.

4. INFORMATION ARCHITECTURE

Primary Information (Always visible)

Tree View: Hierarchical folder list with expand/collapse arrows.
Breadcrumb: Current path from root.
Content Grid: Quest/adventure cards in current folder.

Secondary Information

Item count per folder.
Archive status.

Actions

Primary CTA: "New Folder", "Add Content".
Secondary Actions: "Rename", "Delete", "Move To", "Permissions".

5. WIREFRAMES

Excluded — UI is fully developed (FolderTreeView, FolderBreadcrumb, FolderCard, etc.).

6. WIREFLOWS

Excluded.

7. PROTOTYPE

Excluded — production deployed.

8. BACKEND SCHEMA

Database Tables

CREATE TABLE project_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 project_folders(id),  -- Self-ref, NULL = root
  order_index INTEGER NOT NULL,                           -- Sparse gaps of 10,000
  is_archived BOOLEAN DEFAULT FALSE,
  archived_at TIMESTAMPTZ,
  is_expanded BOOLEAN DEFAULT FALSE,                      -- Tree view UI state
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
 
-- FK columns on content tables
ALTER TABLE quests ADD COLUMN project_folder_id UUID REFERENCES project_folders(id);
ALTER TABLE adventures ADD COLUMN project_folder_id UUID REFERENCES project_folders(id);

RLS Policies

project_folders_select_own: Creator owns folder
project_folders_select_agency: Agency admin can view team member folders
project_folders_insert_own, update_own, delete_own: Full CRUD for owner

Folder Helpers

MAX_FOLDER_DEPTH = 20
checkIsDescendant(folderId, potentialChildId) — prevents circular references
escapeWildcards(text) — sanitizes search input

9. API ENDPOINTS

GET    /api/creator/project-folders?parentFolderId=&treeView=&includeArchived=
POST   /api/creator/project-folders                  (create folder)
PUT    /api/creator/project-folders/[folderId]        (update name/description)
DELETE /api/creator/project-folders/[folderId]        (delete + relocate children)
POST   /api/creator/project-folders/reorder            (drag-drop reorder)
POST   /api/creator/project-folders/move-projects      (bulk move into folder)
GET    /api/creator/project-folders/search?query=       (search paths)

All routes return ApiResponse envelope.

10. DATA REQUIREMENTS

Frontend Needs

Tree structure for FolderTreeView (recursive component).
Breadcrumb path array.
Selected folder ID for content filtering.

Caching Strategy

Folder tree fetched fresh on library mount. Sparse ordering prevents re-fetch on reorder.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

Index on parent_folder_id for tree queries.
Index on creator_id for RLS filtering.
Sparse ordering avoids full-table rewrites.

API Response Time

Target: <300ms for tree view (recursive CTE query).

12. SECURITY & AUTHORIZATION

Who can access this feature?

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

Authorization Logic

RLS enforces creator_id = auth.uid(). Circular reference prevention at API level.

Data Validation

All inputs validated with Zod (project-folder.schema.ts). Folder name length and depth limits enforced.

13. ERROR HANDLING

Error	Response
Max depth exceeded	400: "Maximum folder depth (20) reached"
Circular reference	400: "Cannot move a folder into itself or its children"
Folder not found	404: "Folder not found"

14. TESTING CHECKLIST

Happy Path
□ Create folder → appears in tree
□ Create subfolder → nested correctly
□ Drag folder to new parent → depth validated
□ Move project into folder → FK updated

Edge Cases
□ Delete non-empty folder → children relocated
□ Max depth 20 → blocked
□ Circular reference → blocked
□ Archived folder → hidden by default

15. OPEN QUESTIONS

None — fully implemented.

16. OUT OF SCOPE (v1.1+)

Folder-level publishing status (publish/archive all contents).
Folder templates for project scaffolding.
Folder color/sorting customization.

17. SUCCESS METRICS

70% of creators use folders to organize content.
Average folder depth: 2-3 levels.
Tree view renders <300ms for 100+ folders.

18. DEPENDENCIES

This feature depends on:

[W1.4] ApiResponse — all folder APIs.
[6.1.1] Multi-role RBAC — folder-permissions.schema.ts.

These features depend on this:

[1.1] Project Creation Wizard — folder assignment on create.
[11.3] Adventure Folders — shared folder-helpers utilities.

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