Form Editor

Feature Owner: Krizha Onise Cortez
Module: Design (Dual Editor)
Priority: P0
Sprint: Fully Implemented
Date: February 2026

EXECUTIVE SUMMARY

What is this feature?

The Form Editor is the primary linear content authoring interface used by creators to build quests through modular content cards. It supports creating, editing, deleting, duplicating, reordering, and organizing content while automatically synchronizing with the Visual Canvas.

Why does it matter?

Creators need a simple and structured editing experience without manually managing quest data or canvas metadata. The Form Editor provides a familiar outline-based workflow while maintaining consistency with the Visual Canvas.

What's the MVP scope?

• Create content cards

• Edit existing cards

• Delete and reorder cards

• Upload media

• Support Scenario child cards

• Integrate Question Hub activities

• Automatically synchronize with Visual Canvas

• Validate content before publishing

1. USER PAIN POINT & SOLUTION

Without Form Editor

Creators would need to edit quest content directly through canvas nodes or raw data, making content management slower and more difficult.

Pain Point

Emotional: Editing large quests becomes overwhelming.
Functional: Managing multiple content types without a structured interface is inefficient.
Business Impact: Content production takes longer and increases authoring errors.

Current State (Already Implemented)

Creators can manage all quest content through a centralized card-based editor with automatic synchronization and publishing validation.

2. 4D FRAMEWORK MAPPING

Diagnose
Provides a structured overview of all quest content.

Design
Allows creators to organize, edit, and manage every content card.

Develop
Supports media uploads, Question Hub integration, Scenario child cards, and publishing.

Deliver
Provides validated quest content used by the Quest Player and Visual Canvas.

3. USER FLOWS

Entry Point

/quest-editor/[questID]/content/form-editor

Success Criteria

Content cards load successfully, edits persist after saving, media uploads complete successfully, and published quests pass validation.

Main Flow

1. Open Form Editor.

2. Load existing quest content.

3. Create or edit content cards.

4. Upload media if necessary.

5. Save changes.

6. Synchronize with Visual Canvas.

7. Validate quest.

8. Save draft or publish.

Edge Cases

• Empty quest initializes with no cards.

• Upload failure displays an error message.

• Validation failure prevents publishing.

• Unauthorized users cannot edit content.

• Deleted Question Hub activities cannot be selected.

Decision Points

IF quest mode is Linear
Continue using Form Editor.

ELSE
Redirect creators to Visual Canvas.

4. INFORMATION ARCHITECTURE

Primary Information

• Content Cards

• Scenario Cards

• Activity Cards

• Media Attachments

Secondary Information

• Motivation Content

• Card Order

• Validation Status

• Publishing Status

Tertiary Information

• Canvas Synchronization

• Upload Progress

• Save State

Actions

Primary CTA

• Save Draft

• Publish

Secondary Actions

• Add Card

• Edit Card

• Delete Card

• Duplicate Card

• Reorder Card

• Upload Media

5. WIREFRAMES

Excluded — Feature fully implemented.

6. WIREFLOWS

Excluded — Feature fully implemented.

7. PROTOTYPE

Excluded — Feature fully implemented.

8. BACKEND SCHEMA

Database Tables

quest_content_cards

Stores all content cards belonging to a quest.

Example:

{
  "id": "...",
  "quest_id": "...",
  "type": "text",
  "content": {},
  "motivation": {},
  "order_index": 1
}

quests

Relevant fields:

• canvas_metadata

• publishing_status

• quest_mode

9. API ENDPOINTS

GET /api/creator/quest-content-cards/list

Loads all content cards for a quest.

• POST /api/creator/quest-content-cards/create

  • Creates a new content card.

• PUT /api/creator/quest-content-cards/update

  • Updates an existing content card.

• DELETE /api/creator/quest-content-cards/delete

  • Deletes a content card.

• PUT /api/creator/quest-content-cards/reorder

  • Updates card ordering.

• POST /api/creator/quest-content-cards/upload-media

  • Uploads media files.

• POST /api/creator/validate-quest-content

  • Validates quest content before publishing.

• PATCH /api/creator/update-quest

  • Updates publishing status.

10. DATA REQUIREMENTS

Frontend Needs

• Quest ID

• Quest Mode

• Content Cards

• Scenario Child Cards

• Question Hub Activities

• Upload Status

• Publishing Status

• Validation State

• Canvas Synchronization State
  

API Calls Frontend Will Make

• Load content cards

• Create card

• Update card

• Delete card

• Reorder cards

• Upload media

• Validate quest

• Publish quest

11. PERFORMANCE CONSIDERATIONS

Database Optimization

Cards are stored individually while canvas metadata is synchronized only when necessary. This minimizes unnecessary updates while preserving consistency between the Form Editor and Visual Canvas.

12. SECURITY & AUTHORIZATION

Who Can Access This Feature?

Creator
Full editing permissions for owned quests.

Reviewer
Read-only access during review workflows.

Learner
No access.

13. ERROR HANDLING

Current Existing Error Handling

• Validation failures prevent saving invalid content.

• Upload failures display error notifications.

• Unauthorized users are blocked from editing.

• Database failures return API error responses.

• Publishing validation prevents incomplete quests from being published.

• Canvas synchronization failures are logged before returning an error.

14. TESTING CHECKLIST

Happy Path

• Load content cards

• Create card

• Edit card

• Delete card

• Duplicate card

• Reorder cards

• Upload media

• Save draft

• Publish quest

• Synchronize with Visual Canvas

Edge Cases

• Upload unsupported file type.

• Upload oversized file.

• Validation failure.

• Empty quest.

• Deleted Question Hub activity.

• Unauthorized editing.

• Synchronization failure.

15. OPEN QUESTIONS

• Should collaborative editing be supported in the future?

• Should version history be implemented?

• Should bulk editing be supported for large quests?

16. OUT OF SCOPE

• Real-time collaborative editing.

• Version history.

• Bulk card editing.

• Offline editing support.

17. SUCCESS METRICS

• Successful content save rate.

• Media upload success rate.

• Publishing success rate.

• Canvas synchronization success rate.

• Average quest authoring time.

18. DEPENDENCIES

This feature depends on:

• Quest Editor

• Visual Canvas

• Question Hub

• Supabase Storage

• Clerk Authentication

• Publishing Workflow

These features depend on this:

• Quest Player

• Visual Canvas Synchronization

• Review Workflow

• Publishing Workflow

• AI Curriculum Import

19. TIMELINE & OWNERSHIP

Sprint: Feature already implemented and deployed.
Backend: Multiple Contributors
Frontend: Krizha Onise Cortez
Estimated Completion: Feature completed.