Quest Creation

Author: James Derick Billate
Reviewer:
Creation Date: July 1, 2026
Status: Approved and Merged
References: https://github.com/wyzlab/WyzQuests/issues/29

INTRODUCTION AND GOALS

Problem Summary: This feature allows Creators to align the goal of their learning content to their target learners. It offers dynamic customization for various quests, including the ability to create a quest manually or through AI Assistant and set the quest mode for learner navigation.

Goals and Non-goals:

• Allow Creators to create quests inside WyzQuests.

• Allow Creators to choose between Manual creation and AI Assistant creation.

• Allow quest mode selection between Narrative (Linear) and Exploration (Branching).

• Store quest metadata such as title, introduction, description, duration, tags, skills, and learning objectives.

• Quest mode is limited to Narrative (Linear) and Exploration (Branching).

• This feature does not cover full learner gameplay, publishing approval, or advanced analytics.

HIGH-LEVEL ARCHITECTURE

System Diagram:

Technologies Used:

Frontend: Next.js, React, Tailwind CSS, Shadcn Components.

Backend: Next.js API routes, TypeScript, RESTful APIs.

Validation: Zod Validation.

Authentication and Authorization: Clerk Authentication, agency ownership context.

Database and Storage: Supabase Postgres and Supabase Storage for optional quest profile image upload.

DETAILED DESIGN & IMPLEMENTATION

Database:

Primary table: quests

Important fields used by this feature:

• id

• creator_id

• agency_id where applicable through agency-scoped ownership.

• title

• introduction

• description

• duration

• tags

• skills

• learning_objectives

• quest_mode

• profile_img_url

• publishing_status

• created_at

• updated_at

Quest Mode Values:

• linear: Narrative mode.

• exploration: Exploration or branching mode.

Default Behavior:

• New quests are created as draft content.

• If no quest mode is provided, schema defaults should keep the quest in a valid supported mode.

API Specification:

POST /api/creator/(content)/create-quest
Creates a single quest from Creator input. The request is submitted as FormData with a json payload and optional profile image file.

Required or supported data:

• title

• quest_mode

• introduction

• description

• duration

• tags

• skills

• learning_objectives

• Optional profile image file.

POST /api/creator/(content)/batch-create-quests
Creates multiple quests from AI-assisted suggested quest outlines and links them to an adventure sequence where applicable.

Required or supported data:

• adventure_id

• quests

GET /api/creator/(content)/list-quests
Lists quests available to the authenticated Creator or agency-scoped account. This endpoint supports dashboard listing and may filter by quest_mode or editable access.

Supported query behavior:

• Filter by quest_mode.

• Exclude archived quests by default.

• Respect agency resource ownership and editability where applicable.

PATCH /api/creator/(content)/update-quest
Updates quest details after creation, including quest_mode changes from Overview > Settings.

Supported data:

• quest_id

• Quest editable fields such as title, description, introduction, duration, tags, skills, learning objectives, quest_mode, and other supported quest settings.

Core Logic and Workflow:

• Creator signs in.

• Creator opens the dashboard.

• Creator clicks Create Content.

• Creator chooses Quest.

• Creator chooses Manual or AI Assistant.

• Creator chooses Narrative or Exploration mode.

• System validates form data through Zod.

• System checks authenticated Creator or agency ownership context.

• System inserts the quest into Supabase with draft publishing status.

• If a profile image is included, system uploads the image and stores the resulting URL.

• System returns the created quest and allows the Creator to continue editing.

INFRASTRUCTURE & OPERATIONS

Dependencies: No known major dependencies other than Zod validation to ensure data inputs and returns are correct and accurate.

Monitoring & Alerting: No major monitoring is needed because most of this feature is standard quest record creation. Alert notifications or logs should still be checked whenever database insertion, schema validation, or storage upload fails.

Deployment Plan:

• Ensure that the quests table has a migrated quest_mode column.

• Ensure quest_mode accepts the supported values used by the application.

• Ensure UI/UX for choosing Narrative or Exploration is available upon the creation form.

• Ensure quest mode conversion is available through Overview > Settings where supported.

• Ensure all quest creation APIs include quest_mode in validation, insertion, listing, and update logic.

TESTING & QUALITY ASSURANCE

Testing Strategy:

• Sign in as a Creator.

• Create a quest via the dashboard.

• Choose Manual or AI Assistant.

• Choose either Narrative or Exploration.

• Input required quest information.

• Submit the quest creation form.

• Ensure that the quest is created in the database.

• Ensure that the quest's mode is updated in both UI/UX and database record.

• Ensure the created quest appears in list and dashboard views.

Known Limitations:

• There are no known major limitations because this feature only covers the ability to create a quest and choose a quest mode option.

• Quest mode is currently limited to Narrative (Linear) and Exploration (Branching).

• Full learner progression behavior is outside this documentation.

MAINTENANCE & SUPPORT

Troubleshooting:

• Re-migrate the quest_mode column if the database column is missing from the quests table.

• Ensure that all APIs related to quest creation have quest_mode in their Supabase queries for create, list, fetch, and update methods.

• Check Zod schema validation if valid Creator input is rejected.

• Check Clerk authentication and agency ownership context if a Creator cannot create a quest.

• Check Supabase insert logs if a quest does not appear after form submission.

Document Version

1.0 - Documentation draft, feature is merged, 07/01/2026

1.1 - Enhanced documentation using hand-off and technical documentation templates, 07/10/2026