Reviewer Queue & Status Workflow

Feature Owner: Jethro Magdaleno Lagmay
Module: Review Workflow
Priority: High
Sprint: #12
Date: July 1, 2026

EXECUTIVE SUMMARY

What is this feature? A centralized Next.js frontend dashboard and Supabase backend workflow that allows authorized platform reviewers to evaluate, approve, or reject quests submitted by authors on the WyzQuests platform.

Why does it matter? It standardizes the content moderation lifecycle, providing a secure, auditable trail of state changes (from pending to published) while giving reviewers a dedicated interface to inspect the visual canvas logic and content.

What’s the MVP scope?

• A queue interface displaying quests with pending_review status.

• A detailed view for reviewers to inspect the quest's canvas logic.

• A backend state machine (Status Workflow) to transition quest statuses (Approve/Reject).

• A commenting system to capture reviewer feedback upon rejection.

1. USER PAIN POINT & SOLUTION

Current State (Without Feature) Quests lack a structured review pipeline, meaning there is no unified interface for content moderators to find, evaluate, and officially approve content for the WyzQuests platform.

Pain Point

• Emotional: Frustration and cognitive overload for reviewers trying to manually track which quests need evaluation.

• Functional: No secure database mechanism to prevent unauthorized users from changing a quest's publication status. No centralized way to leave required feedback for rejected quests.

• Business Impact: Bottlenecks in the content publishing pipeline, leading to slower platform growth and missing quality control audit trails.

Future State (With Feature) A streamlined, secure dashboard where reviewers can see exactly what needs attention, make decisions quickly, and automatically notify authors of required changes via integrated comments.

Marketing Hook "Streamlined quality control: Empowering WyzQuests reviewers to evaluate, give feedback, and publish top-tier quests with a single click."

2. 4D FRAMEWORK MAPPING

• Diagnose: Identified a bottleneck in the quest publication pipeline and a lack of role-based security around content approvals.

• Design: Architected a dedicated dashboard with clear status indicators and a read-only viewer for quest canvas logic.

• Develop: Implemented a Next.js frontend integrated with Supabase (custom reviews table, ENUM status updates, and Row Level Security).

• Deliver: Feature completed, tested, and merged into the develop branch for staging deployment.

3. USER FLOWS

Entry Point Reviewer logs into the WyzQuests platform -> Navigates to the 'Reviewer Dashboard' from the main navigation.

Success Criteria A quest successfully transitions out of the pending_review queue into either an approved or rejected state, logging the reviewer's ID and comments.

Main Flow (Happy Path)

1. Reviewer opens the Queue.

2. Clicks on a pending quest to view details.

3. Reviews the visual canvas logic and content.

4. Clicks "Approve".

5. Dashboard optimistically updates, removing the quest from the queue.

6. Supabase backend commits the status change and creates a review log.

Edge Cases

• Reviewer attempts to reject a quest but leaves the comment field blank (blocked by frontend validation).

• Two reviewers attempt to evaluate the same quest simultaneously.

• Non-reviewer attempts to hit the API endpoint to approve their own quest (blocked by Supabase RLS).

Decision Points

• Approve: Changes status to approved, quest becomes eligible for public visibility.

• Reject: Changes status to rejected, prompts mandatory feedback text area for the author.

4. INFORMATION ARCHITECTURE

Primary Information (Always visible)

• Quest Title

• Author Name

• Submission Date

• Current Status

Secondary Information

• Visual Canvas Logic structure (when viewing quest details)

• Reviewer Comment Textbox (when rejecting)

Tertiary Information (Hidden until needed)

• Historical review logs/previous rejection reasons for the same quest.

Actions

• Primary CTA: Approve, Reject

• Secondary Actions: View Canvas Details, Cancel/Go Back to Queue

5. WIREFRAMES

N/A

6. WIREFLOWS

• Screen 1 (Queue List): Data table showing all pending_review quests.

• Screen 2 (Detail View): Read-only rendering of the quest's canvas logic. Bottom action bar with [Approve] and [Reject] buttons.

• Modal (Rejection): Triggered if [Reject] is clicked. Contains a mandatory text area for comments and a [Confirm Rejection] submit button.

7. PROTOTYPE

Already synced in the development server.

8. BACKEND SCHEMA

Database Tables

• quests (Existing table, updated):

  • status: Added ENUM values ['draft', 'pending_review', 'approved', 'rejected'].

  • reviewer_id: UUID (Foreign Key to users table).

• reviews (New table):

  • id: UUID (Primary Key)

  • quest_id: UUID (Foreign Key to quests)

  • reviewer_id: UUID (Foreign Key to users)

  • status_given: ENUM ('approved', 'rejected')

  • comments: Text

  • created_at: Timestampz

Indexes

• B-Tree index on quests.status to optimize fetching the pending_review queue.

Constraints & RLS Policies

• RLS (Row Level Security):

  • Only users with role = 'reviewer' or role = 'admin' can run UPDATE on the quests.status column.

  • Only users with role = 'reviewer' can INSERT into the reviews table.

9. API ENDPOINTS

Endpoint 1: Fetch Reviewer Queue

• Method/Path: Supabase Client select() or GET /api/reviews/queue

• Purpose: Retrieves all quests awaiting review.

• Payload: None.

• Response: Array of quest objects where status == 'pending_review'.

Endpoint 2: Mutate Quest Status

• Method/Path: Next.js Server Action / POST /api/reviews/status

• Purpose: Submits the reviewer's verdict.

• Payload: { quest_id: string, action: 'approve' | 'reject', comments: string }

• Response: { success: true, message: 'Status updated' }

10. DATA REQUIREMENTS

Frontend Needs

• Active user session and role verification.

• Paginated list of pending quests.

• Full quest object data (including canvas nodes/edges) for the detail view.

API Calls Frontend Will Make

• Fetch pending quests on dashboard load.

• Post status mutations (Approve/Reject).

Caching Strategy

• Optimistic UI updates for immediate user feedback on status mutation.

• Short-lived cache/stale-while-revalidate strategy for the queue to prevent reviewers from seeing heavily outdated lists.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

• Index added to the status column on the quests table to ensure rapid loading of the queue even as the platform scales to thousands of quests.

Caching Strategy

• Next.js Router Cache utilized for navigating back and forth between the queue list and individual quest detail views without redundant data fetching.

API Response Time

• Status mutation runs as a single Supabase RPC (Remote Procedure Call) transaction to update both quests and reviews tables simultaneously, keeping response times under 200ms.

12. SECURITY & AUTHORIZATION

Who can access this feature?

• Authenticated users with the explicit 'reviewer' or 'admin' role assigned in the Supabase Auth metadata.

Authorization Logic

• Frontend: Route protection redirects non-reviewers away from /reviewer-dashboard.

• Backend: Supabase RLS acts as the final gatekeeper, blocking database mutations from unauthorized tokens.

Data Validation

• Payload validation ensures comments are strictly required if action === 'reject'.

• Ensure quest_id exists before attempting mutation.

13. ERROR HANDLING

• Database Transaction Failure: If inserting into reviews succeeds but updating quests fails, the transaction rolls back. Frontend displays a generic "Update failed, please try again" toast.

• Unauthorized Attempt: Returns a 403 Forbidden error. Frontend displays "You do not have permission to perform this action."

• Missing Comments: Frontend form validation blocks submission and highlights the comment box in red if a rejection is attempted without feedback.

14. TESTING CHECKLIST

Happy Path

• [x] Reviewer can load the dashboard and see pending quests.

• [x] Reviewer can approve a quest, and the UI immediately removes it from the queue.

• [x] Reviewer can reject a quest with comments, and the database reflects both the status change and the new review log.

Edge Cases

• [x] Rejecting a quest without comments triggers an error state.

• [x] Attempting to approve a quest that has already been approved by someone else (throws a handled "Quest no longer pending" error).

• [x] User without reviewer role cannot navigate to the dashboard.

15. OPEN QUESTIONS

• Concurrent Reviews: Do we need to implement a "Claim" feature to lock a quest to a specific reviewer, preventing two people from working on the same quest at once?

• Real-Time Updates: Should we upgrade the dashboard to use Supabase Realtime subscriptions so new pending quests appear instantly without a page refresh?

16. OUT OF SCOPE

• The actual quest authoring tools or canvas builder (handled in separate modules).

• Automated AI moderation or auto-approvals.

• Complex multi-stage review pipelines (e.g., requires 2 separate reviewers to approve).

17. SUCCESS METRICS

• Average Review Time: Reduction in the time it takes for a quest to go from pending_review to a final state.

• Queue Zero: Ability for the reviewer team to clear the backlog efficiently using the new UI.

• Security: Zero instances of unauthorized status changes.

18. DEPENDENCIES

This feature depends on:

• Next.js App Router.

• Supabase Authentication and Role management.

• Visual Canvas and Quest Editor (which generates the quests that need reviewing).

These features depend on this:

• Notification System (needs to trigger emails to authors when status changes).

19. TIMELINE & OWNERSHIP

Implemented: Currently merged into the develop branch.
Owner: Jethro Magdaleno Lagmay

Document Version
v1.0 - Initial document