[5.4] Reviewer Queue Backend

1. Front Matter

• Title: Reviewer Queue Backend

• Author: scorevi (Sean Patrick Caintic)

• Reviewers: dyorgie (Jethro Lagmay)

• Created: February 2026

• Status: Approved

• References:

  • Issue: [5.4] Reviewer Queue Backend #179

  • Milestone: [5] Dashboards

2. Introduction & Goals

• Problem Summary: Reviewers need a queue system to see quests awaiting review, claim quests for review, and manage their review assignments with lockout mechanisms to prevent concurrent reviews.

• Goals:

  • Add REVIEWER role to platform

  • Provide queue management APIs

  • Implement lockout mechanism (single reviewer per quest)

  • Auto-release stale claims after 72 hours

• Non-Goals:

  • Automated review assignment

  • Review scoring/rating system

  • Cross-agency review sharing

• Glossary:

  • Claim: Reviewer locks a quest for exclusive review

  • Lockout: Prevents other reviewers from claiming same quest

  • Auto-Release: Automatic claim release after 72h inactivity

3. High-Level Architecture

• System Diagram:
  

• Technologies Used:

  • Supabase - Queue storage, claim columns

  • Clerk - Role management

  • Next.js Middleware - Route protection

4. Detailed Design & Implementation

• Data Model / Schema: quests Table (Review Columns)

Index: (status, submitted_at) for efficient queue queries

• API Specification:

  • GET /api/reviewer/queue - List quests with status IN_REVIEW

  • POST /api/reviewer/claim-quest/[questId] - Claim quest for review

  • PATCH /api/reviewer/update-quest-status - Approve or request changes

  • POST /api/reviewer/release-quest/[questId] - Release claim

• Logic & Workflows:

  Role Hierarchy:

  ADMIN > AGENCY > REVIEWER > CREATOR > LEARNER

  Lockout Mechanism:

  1. Single Claim - Only one reviewer can claim a quest at a time

  2. Visual Indicator - Shows "In Review by [Name]" to other reviewers

  3. Auto-Release - Claims released after 72 hours of inactivity

  4. Manual Release - Reviewer can voluntarily release a claim

  Queue States:

  • IN_REVIEW - Submitted, awaiting review (visible to all reviewers)

  • CHANGES_REQUESTED - Reviewer requested changes (visible to all reviewers)

  • Claimed - In active review (visible to claiming reviewer only)

• Key Files:

  • app/api/reviewer/queue/route.ts - Queue listing API

  • app/api/reviewer/claim-quest/[questId]/route.ts - Claim quest

  • app/api/reviewer/update-quest-status/route.ts - Status updates

  • app/reviewer/layout.tsx - Role guard for reviewer routes

  • lib/auth/role-guard.ts - Role authentication utilities

5. Infrastructure & Operations

• Dependencies:

  • Supabase - Queue persistence

  • Clerk - Role management

• Monitoring & Alerting:

  • Background Job: Auto-release stale claims (72h)

  • Logs: Track claim/release events

• Deployment Plan:

  1. Add claimed_by, claimed_at, submitted_at columns

  2. Deploy API routes

  3. Add role guard to reviewer routes

6. Testing & Quality Assurance

• Test Strategy:

  • Manual: Claim, release, queue listing

  • Integration: Role guard, concurrent claim prevention

• Known Limitations:

  • No automated assignment algorithm

  • Single reviewer per quest (no team reviews)

7. Maintenance & Support

• Troubleshooting:

  • Quest already claimed → Wait for release or admin override

  • Stale claim not releasing → Check background job status

  • Role guard blocking access → Verify Clerk role assignment

• Changelog:

  • 1.0 (Feb 2026): Initial implementation

Document Version

1.0 - Approved, Feature deployed to production, 02/27/2026