Project Creation Wizard

  1. Overview
  2. Hand Off Documentation
  3. Project Creation Wizard

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 Project Creation Wizard is an AI-assisted content creation flow that enables creators to generate quests and adventures through a multi-step modal interface. It supports both manual form input and AI-powered generation via Gemini Pro, including batch quest creation and auto-sequencing for adventures.
Why does it matter? Creators face high friction when starting new educational content from scratch. The wizard reduces cognitive load by offering AI suggestions, auto-generated autofill data, and structured step-by-step guidance, accelerating time-to-first-quest.
What's the MVP scope? Fully functional AI-assisted creation wizard with form validation (Zod), quest generation, adventure generation with quest sequencing, batch quest creation, and generation history sidebars for both quests and adventures.

1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

Creators must manually configure every field when creating quests or adventures, requiring deep knowledge of educational content design and the platform's data model.

Pain Point

Type

Impact

Emotional

Overwhelm from blank canvas; fear of producing low-quality content

Functional

Time-consuming manual entry for every field; repeated context-switching

Business

Low content creation throughput; poor creator retention during onboarding

Future State

Creators enter a high-level idea, and the AI generates structured quests/adventures with learning objectives, skills, and metadata. Creators can review, edit, and batch-approve generated content before publishing.

Marketing Hook

"From idea to structured quest in under 60 seconds — AI-powered creation that handles the heavy lifting."

2. 4D FRAMEWORK MAPPING

Phase

Mapping

Diagnose

AI validates the creator's initial idea before content generation

Design

Dual-mode: Form-based manual entry + AI-powered auto-generation

Develop

Rich content creation with AI-assisted autofill for skills, objectives, assets

Deliver

Generated content is immediately available for editing and export workflows

3. USER FLOWSEntry Point

  • Creator Dashboard → "Create New" button → Project Creation Modal

Success Criteria

  • Quest or Adventure is created in the database with all metadata fields populated

  • Adventure includes properly sequenced quests via adventure_sequences

Main Flow

  1. Creator opens ProjectCreationModal.tsx

  2. Selects content type (Quest / Adventure)

  3. Enters high-level idea description

  4. AI generates suggested content (quests or adventure structure)

  5. Creator reviews generated suggestions in AIAssistedWizard.tsx

  6. Creator accepts/rejects/modifies suggestions

  7. Creator provides final metadata (skills, objectives, profile image)

  8. Submits → FormData with "json" field + optional "profile_image" file

  9. System validates with Zod, strips profile_image before DB insert

  10. Content created; adventure sequences auto-generated for adventures

Edge Cases

  • Large profile images: Handled via multipart FormData upload

  • AI generation failure: Error surfaced to UI; creator can proceed manually

  • Duplicate quest titles in adventure: Auto-sequencing handles ordering

  • Empty learning objectives: Zod allows empty string (no min length enforced)

Decision Points

  • AI-assisted vs. fully manual creation (toggle in wizard)

  • Accept/reject individual generated quests in batch view

  • Select profile image or skip

4. INFORMATION ARCHITECTURE

Primary

  • Content title, learning_objectives (string), skills (string array), quest_mode (ENUM)

  • Adventure: title, introduction, description, duration, tags, skills

Secondary

  • Profile image, background image/audio (adventures), enrollment settings

  • AI generation history sidebars

Actions

  • Generate with AI, Regenerate, Accept, Reject, Batch Create, Edit manually

5. WIREFRAMES

Excluded — existing UI implemented.

6. WIREFLOWS

Excluded — existing UI implemented.

7. PROTOTYPE

Excluded — feature is fully implemented.

8. BACKEND SCHEMA

quests table (verified columns)

Column

Type

Notes

id

UUID

PK

creator_id

UUID

Internal app_users.id

title

TEXT

learning_objectives

TEXT

Single string, NOT array

skills

TEXT[]

Array of strings, GIN indexed

quest_mode

quest_mode_type

PostgreSQL ENUM

publishing_status

TEXT

profile_img_url

TEXT

NOT thumbnail_url

canvas_metadata

JSONB

Nodes/Edges per CanvasMetadata interface

adventures table (verified columns)

Column

Type

Notes

id

UUID

PK

creator_id

UUID

Internal app_users.id

title

TEXT

introduction

TEXT

description

TEXT

duration

TEXT

tags

TEXT[]

skills

TEXT[]

GIN indexed

publishing_status

TEXT

is_count_visible

BOOLEAN

accessibility_status

TEXT

enrollment_count

INTEGER

enrollment_limit

INTEGER

enrollment_fee

NUMERIC

profile_img_url

TEXT

background_img_url

TEXT

background_audio_url

TEXT

adventureFolderId

UUID

DB only, NOT in Zod schema

projectFolderId

UUID

DB only, NOT in Zod schema

adventure_sequences table

Column

Type

Notes

adventure_id

UUID

FK → adventures ON DELETE CASCADE

quest_id

UUID

FK → quests

order_index

INTEGER

asset_metadata table

Column

Type

Notes

creator_id

TEXT NOT NULL

CHECK (creator_id != ''), Clerk string, NOT UUID FK

file_name

TEXT

file_path

TEXT

file_url

TEXT

source

TEXT

external_url

TEXT

thumbnail_url

TEXT

deleted_at

TIMESTAMPTZ

Soft delete

expires_at

TIMESTAMPTZ

9. API ENDPOINTS

Method

Path

Auth

Purpose

File

POST

/api/creator/create-quest

Clerk

Create single quest

app/api/creator/(content)/create-quest/route.ts (166 lines)

POST

/api/creator/(content)/create-adventure/route.ts

Clerk

Create adventure with quest sequencing

296 lines

POST

/api/creator/(content)/batch-create-quests/route.ts

Clerk

Batch create multiple quests

180 lines

POST

/api/ai/generate-quest

Clerk

AI quest generation

Verified existing

POST

/api/ai/generate-adventure

Clerk

AI adventure generation

Verified existing

POST

/api/ai/generate-autofill-data

Clerk

AI autofill suggestions

Verified existing

Request Format (create-quest): FormData with "json" field (JSON string) + optional "profile_image" file.
Validation: createQuestSchema.safeParse() — profile_image is stripped from the JSON before DB insert.

Adventure special handling (create-adventure/route.ts:34): suggestedQuests array is extracted from the request body BEFORE Zod parsing. If present, quests are auto-created and linked via adventure_sequences with computed order_index.

Ordering: computeQuestOrder() at adventure-sequence/route.ts:160 uses sparse ordering with 10,000 gaps.

10. DATA REQUIREMENTS

Frontend Needs

  • Quest/adventure metadata for form pre-fill

  • AI generation suggestions (streaming or batch response)

  • Profile image upload with preview

  • Generation history for undo/redo

API Calls

  • POST multipart for quest creation (FormData)

  • POST JSON for adventure creation

  • POST JSON for AI generation endpoints

  • POST JSON for batch quest creation

Caching

  • Generation history persisted client-side via history sidebars

  • AI suggestions displayed inline, no server-side caching required

11. PERFORMANCE CONSIDERATIONS

DB Optimization

  • GIN indexes on quests.skills and adventures.skills for filtering

  • adventure_sequences uses order_index INTEGER for efficient ordering

  • asset_metadata has soft-delete via deleted_at for cleanup efficiency

Response Time

  • AI generation: asynchronous, streaming recommended

  • Batch creation: single transaction with multiple inserts

  • Profile image upload: handled via Supabase Storage, inline with form submission

12. SECURITY & AUTHORIZATION

Access Control

  • All endpoints require Clerk authentication

  • creator_id set from authenticated Clerk user session

  • RLS enabled on all tables (per project standards)

Auth Logic

  • quests.creator_id and adventures.creator_id are UUID REFERENCES app_users(id)

  • asset_metadata.creator_id and idea_validations.creator_id are TEXT (Clerk string ID, NOT UUID FK)

  • asset_metadata.creator_id has CHECK constraint (creator_id != '')

  • Quest/adventure ownership uses internal UUID; asset/validation tracking uses Clerk string

Validation

  • All inputs validated via Zod schemas before processing

  • Profile image stripped from JSON before DB insert (separate storage upload)

  • adventureSchema excludes folder FK columns (adventureFolderId, projectFolderId) — these are DB-only

13. ERROR HANDLING

Error

Response

Zod validation failure

400 with field-level error details

Missing authentication

401 Unauthorized

Storage upload failure

500 with storage error message

AI generation timeout

Graceful fallback; manual creation still available

Duplicate adventure sequence

Handled by computeQuestOrder() sparse ordering

14. TESTING CHECKLIST

Happy Path

  • Create quest with all required fields via wizard

  • Create adventure with AI-generated suggested quests

  • Batch create quests and verify all persisted

  • Upload profile image during quest creation

  • Generate AI autofill data for existing quest

  • View generation history for quests and adventures

Edge Cases

  • Create quest with empty learning_objectives

  • Create adventure with no suggestedQuests (manual mode)

  • Verify adventure sequences maintain correct order

  • Profile image upload failure does not block quest creation

  • Concurrent batch creation with large quest count

15. OPEN QUESTIONS

None — feature is fully implemented.

16. OUT OF SCOPE

  • Multi-SCORM export (handled in Adventure Builder feature)

  • SCORM/xAPI compliance validation

17. SUCCESS METRICS

  • Time from idea to created quest: < 60 seconds (with AI)

  • AI suggestion acceptance rate

  • Number of quests created per creator session

18. DEPENDENCIES

  • Google Gemini Pro API (AI generation)

  • Supabase Storage (profile image uploads)

  • Clerk Auth (user identity)

  • adventure_sequences table (adventure creation)

19. TIMELINE

Completed — Feature is fully implemented in Sprint #12.

Document Version

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

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

Written by Sean Patrick Last updated June 29, 2026
Was this article helpful?