Feature Owner : Joylynne Esportuno
Module : Review Workflow
Priority : P1
Sprint #6: Fully Implemented
Date : July 2, 2026
EXECUTIVE SUMMARY
What is this feature ?
Validation Error standardizes how quest/content validation failures are detected and shown to creators.
Why does it matter ?
Creators need clear, actionable messages before publishing or submitting broken content.
What's the MVP scope ?
Return structured validation messages for publish/review blockers. Full field-level UI coverage across every form is follow-up.
1. USER PAIN POINT & SOLUTION
Without Validation Error
Validation failures can be generic or hard to locate.
Pain Point
Emotional : Creators feel stuck
Functional : Debugging content issues takes too long
Business Impact : Review submissions and publishing slow down
Current State (Already Implemented)
Creators see specific validation errors tied to missing or invalid content.
Marketing Hook
"Fix publish blockers before they become review blockers."
2. 4D FRAMEWORK MAPPING
Diagnose
Identifies incomplete nodes, missing links, and invalid content.
Design
Guides creators toward publish-ready structure.
Develop
Uses shared validators and structured API responses.
Deliver
Prevents broken quests from reaching learners/reviewers.
3. USER FLOWS
Entry Point
Publish, submit for review, or content save validation.
Success Criteria
Invalid content is blocked with a clear message; valid content proceeds.
Main Flow
Creator triggers publish/submit/save.
API validates quest content.
Validation errors are returned if any.
UI shows actionable error.
Creator fixes and retries.
Edge Cases
No data : Show missing content error
API error : Show retry-safe failure
Permission denied : Block validation action
Decision Points
IF validation passes, continue
ELSE stop action and show error list
4. INFORMATION ARCHITECTURE
Primary Information
Error title
Affected node/card
Required fix
Secondary Information
Field name
Validation category
Tertiary Information
Raw debug details in logs only
Actions
Primary CTA : Fix content / Retry
Secondary Actions : Open affected node/card
5. WIREFRAMES
Excluded — Feature already implemented.
6. WIREFLOWS
Excluded — Feature already implemented.
7. PROTOTYPE
Excluded — Feature already implemented.
8. BACKEND SCHEMA
Database Tables
questsquests.canvas_metadataContent/card/node data structures
Indexes
quests.idand ownership fields should support validation lookups
Constraints
Validation must run against the latest saved quest data
Validation errors must be returned as user-safe messages
Publish/review transitions must be blocked when validation fails
9. API ENDPOINTS
Endpoint 1: /api/creator/validate-quest-content
Purpose: Validates quest content and structure before publish/review actions.
Auth: Creator/editor access required.
Response Data: Pass/fail result and validation details.
10. DATA REQUIREMENTS
Frontend Needs
Quest ID and current publishing/review status
Validation result summary
Field/node/card-level validation messages
Affected node/card display labels where possible
Retry state after creator fixes content
Backend Needs
Quest ownership/role context
quests.canvas_metadataForm-editor card data where applicable
Required node/card fields by type
Publishing/review status rules
API Calls Frontend Will Make
Validate before publish/submit
Retry validation after fixes
Potentially call publish/submit only after validation passes
Caching Strategy
Validation results should not be cached long-term. They are only accurate for the current saved content state.
11. PERFORMANCE CONSIDERATIONS
Database Optimization
Load quest content/canvas data in as few queries as possible. Avoid querying per node/card when validation can operate on already-loaded metadata.
Validation Runtime
Validation should collect actionable errors in one pass where practical, rather than failing after the first issue and forcing repeated publish attempts.
Caching Strategy
Do not cache validation success across edits. Any content save should invalidate prior validation results.
API Response Time
Validation should return quickly enough to feel like part of publish/submit flow. Long-running validation should show progress/loading state.
12. SECURITY & AUTHORIZATION
Who Can Access This Feature?
Creator: Can validate owned/editable quests
Reviewer: Can receive validation results when approving/reviewing quests
Learner: No access to draft validation details
Authorization Logic
Validation endpoints must verify quest ownership or review authorization before returning detailed errors.
13. ERROR HANDLING
401 Unauthorized: Prompt sign-in and do not run validation for anonymous users on protected creator routes.
403 Forbidden: Return access denied when the user does not own or cannot edit/review the quest.
404 Quest Not Found: Show a missing quest message and provide a safe route back to the editor or content library.
500 Server Error: Show a generic retry message. Log full error details server-side.
14. TESTING CHECKLIST
Happy Path
Valid quest passes validation
Publish/submit proceeds after validation passes
Reviewer approval succeeds only for valid quest
Edge Cases
Missing title/content returns clear error
Broken canvas structure returns clear error
Unauthorized validation blocked
Reviewer approval blocked by invalid content
15. OPEN QUESTIONS
For Frontend:
Should validation errors deep link to the exact node/card?
For Backend:
Should validation errors be persisted as review notes?
Should validation rules be versioned for older quests?
16. OUT OF SCOPE
Full validation dashboard and automated content repair.
17. SUCCESS METRICS
Reduced failed submissions, lower review rejection rate, fewer support tickets about publish blockers.
18. DEPENDENCIES
This feature depends on:
Quest editor save state
Canvas metadata schema
Publish and review status routes
Shared API response helpers
These features depend on this:
Review Alert approval flow
Visual Canvas publish readiness
19. TIMELINE & OWNERSHIP
Backend: Joylynne Esportuno
Frontend: Joylynne Esportuno
QA: Christian Denzon
Estimated Completion: Fully implemented.
