Feature Owner : Joylynne Esportuno
Module : Review Workflow
Priority : P3
Sprint #5: Fully Implemented
Date : July 2, 2026
EXECUTIVE SUMMARY
What is this feature ?
Review Alert notifies creators when a reviewer approves a quest or requests changes.
Why does it matter ?
Creators need immediate visibility into review outcomes.
What's the MVP scope ?
Create in-app notification and companion email after reviewer status update.
1. USER PAIN POINT & SOLUTION
Without Review Alert
Creators may not know that a review decision has been made.
Pain Point
Emotional : Waiting for review feels uncertain.
Functional : Creators manually check statuses.
Business Impact : Approval/revision cycles slow down.
Current State (Already Implemented)
Creators get notification bell alerts after review decisions.
Marketing Hook
"Know the moment a quest review is complete."
2. 4D FRAMEWORK MAPPING
Diagnose
Surfaces review status and requested changes.
Design
Connects review decisions to creator notifications.
Develop
Creates notification records in status update workflow.
Deliver
Speeds approval and revision delivery.
3. USER FLOWS
Entry Point
Reviewer submit review modal/status update.
Success Criteria
Creator receives review notification and can open linked quest.
Main Flow
Reviewer approves or requests changes.
API updates
quests.publishing_status.Notification is inserted for creator.
Email send is attempted.
Creator sees bell unread count.
Edge Cases
On notification failure, status update still succeeds
Log email failure and continue
Only reviewer can update status
Decision Points
IF approved, send approved notification
ELSE IF changes requested, send revision notification
4. INFORMATION ARCHITECTURE
Primary Information
Quest title
Review status
Notification link
Secondary Information
Reviewer identity
Timestamp
Tertiary Information
Email delivery metadata
Actions
Primary CTA : Open quest / View feedback
Secondary Actions : Mark as read
5. WIREFRAMES
Excluded — Feature fully implemented.
6. WIREFLOWS
Excluded — Feature fully implemented.
7. PROTOTYPE
Excluded — Feature fully implemented.
8. BACKEND SCHEMA
Database Tables
questsnotificationsapp_users
Constraints
Only reviewer roles can update review status
Approval should be blocked if quest validation fails
Notification recipient must be the quest creator
9. API ENDPOINTS
Endpoint 1: POST /api/reviewer/update-quest-status
Purpose: Updates quest review status and triggers creator alert side effects.
Auth: Reviewer/admin role required.
Request Body: Quest ID and review decision/status.
Response Data: Updated quest status or validation errors.
Endpoint 2: GET /api/notifications/get-notifications
Purpose: Lets creator see the generated review alert.
Auth: Authenticated creator/recipient.
Frontend Use: Notification bell unread state and alert list.
10. DATA REQUIREMENTS
Frontend Needs
Quest ID, quest title, current publishing/review status
Reviewer decision: approved or changes requested
Submit modal loading/error state
Creator notification title, body, link, and unread state
Backend Needs
Quest creator ID for notification recipient
Reviewer/admin authenticated user ID
Quest status transition target
Validation result for approval attempts
Email template data: quest title, status, destination link
API Calls Frontend Will Make
Reviewer submits status update
Creator notification bell polls/loads notifications
Creator may mark/open alert through notification UI
Caching Strategy
Quest status should be refetched after review update. Notification list should refresh after status update or next polling interval.
11. PERFORMANCE CONSIDERATIONS
Database Optimization
Status update should perform targeted quest update by ID and authorized scope. Notification insert should be a simple recipient-scoped insert.
Caching Strategy
Reviewer queue/status views should invalidate or refetch after update. Creator notification bell can rely on polling unless realtime delivery is later added.
API Response Time
Status update should return promptly. Email delivery delays should not make the reviewer wait unnecessarily.
12. SECURITY & AUTHORIZATION
Who Can Access This Feature?
Reviewer: Can submit review status changes.
Creator: Receives alert for owned quest.
Learner: No access.
Authorization Logic
The status update endpoint must require reviewer role and verify the quest is eligible for review. Notification fetch must return only recipient-owned notifications.
13. ERROR HANDLING
401 Unauthorized: Prompt reviewer/admin to sign in again. Do not update quest status.
403 Forbidden: Return access denied when the user is not a reviewer/admin or does not have review access to the quest.
404 Quest Not Found: Show a reviewer-facing error that the quest can no longer be reviewed.
14. TESTING CHECKLIST
Happy Path
Approved status sends alert
Changes requested sends alert
Creator unread count increases
Notification link opens expected quest route
Edge Cases
Unauthorized status update blocked
Notification failure does not break status update
Email failure is logged without rollback
Invalid quest approval is blocked by validation
15. OPEN QUESTIONS
For Frontend:
Should final reviewer notes be shown directly in the notification body?
Should notifications be realtime or continue polling?
For Backend:
Should final reviewer notes be persisted and shown in the notification?
Should notification/email delivery attempts be retried or audited?
16. OUT OF SCOPE
Push notifications
17. SUCCESS METRICS
Review alert delivery rate
Creator click-through rate
Review cycle time
18. DEPENDENCIES
This feature depends on:
Reviewer queue/status API
Notifications table and helper functions
Email service and quest status email template
Quest validation before approval
These features depend on this:
View Feedback entry point from notifications
Creator review response workflow
Dismiss Alert unread-count behavior
19. TIMELINE & OWNERSHIP
Backend: Joylynne Esportuno
Frontend: Joylynne Esportuno
QA: Christian Denzon
Estimated Completion: Fully implemented
