[7.1] Reviewers' Commenting System

1. Front Matter

• Title: Reviewers' Commenting System

• Author: scorevi/dyorgie (Backend/Frontend)

• Reviewers: scorevi/dyorgie (Backend/Frontend)

• Created: February 2026

• Status: Approved

• References:

  • Issue: [7.1] Commenting System #51

  • Milestone: [7] Review Workflow

2. Introduction & Goals

• Problem Summary: Reviewers need a structured way to leave actionable feedback on specific canvas nodes during quest review, with support for guest SME reviewers, notifications, and analytics.

• Goals:

  • Threaded comments on canvas nodes

  • Guest SME review via secure invite links

  • Real-time notifications with badge counts

  • Bulk operations and CSV export

  • Comment analytics and heatmaps

• Non-Goals:

  • In-line text editing suggestions

  • Video/audio comments

  • External integration (Slack, Teams)

• Glossary:

  • Thread: Parent comment with nested replies

  • SME: Subject Matter Expert (guest reviewer)

  • Heatmap: Visual indicator of comment density per node

3. High-Level Architecture

• System Diagram:

• Technologies Used:

  • React Context - CommentingContext state

  • Supabase - Comments, invites, notifications

  • Zod - API validation schemas

  • crypto.randomBytes - Secure invite tokens

4. Detailed Design & Implementation

• Data Model / Schema:

  quest_comments Table:

  Column	Type	Description
  id	UUID PK	Auto-generated
  quest_id	UUID FK	References quests.id
  node_id	TEXT	Canvas node ID
  parent_comment_id	UUID FK	Self-reference for threading
  app_user_id	UUID FK	Authenticated author
  guest_invite_id	UUID FK	Guest author (alt to app_user_id)
  content	TEXT	Comment text (max 5000 chars)
  is_resolved	BOOLEAN	Resolution status
  created_at	TIMESTAMPTZ	Auto-set

  Constraint: chk_author_exists - Either app_user_id OR guest_invite_id required

  quest_invites Table:

  Column	Type	Description
  id	UUID PK	Auto-generated
  quest_id	UUID FK	References quests.id
  access_token	TEXT UNIQUE	128-bit secure token
  email	TEXT	Invitee's email
  display_name	TEXT	Guest's display name
  status	TEXT	ACTIVE, REVOKED, EXPIRED
  expires_at	TIMESTAMPTZ	7-day expiry default

  notifications Table:

  Column	Type	Description
  id	UUID PK	Auto-generated
  recipient_clerk_id	TEXT	User receiving notification
  type	TEXT	NEW_COMMENT, REPLY_RECEIVED, etc.
  quest_id	UUID FK	Related quest
  is_read	BOOLEAN	Read status

• API Specification:

  Comments:

  • GET /api/reviewer/comments - List threaded comments

  • POST /api/reviewer/comments/create - Create comment/reply

  • PATCH /api/reviewer/comments/[id] - Toggle resolved

  • DELETE /api/reviewer/comments/[id] - Delete comment

  • PATCH /api/reviewer/comments/bulk-resolve - Batch resolve

  • GET /api/reviewer/comments/export - CSV export

  Invites:

  • GET /api/reviewer/invites - List invites

  • POST /api/reviewer/invites - Generate invite

  • DELETE /api/reviewer/invites/[id] - Revoke invite

  Notifications:

  • GET /api/notifications/get-notifications - List notifications

  • PATCH /api/notifications/mark-all-read - Mark all read

• Logic & Workflows:

  Guest SME Access: /review/guest?token=<access_token>

  Guest Permissions:

  • View canvas - ✅

  • Post comments - ✅

  • Resolve comments - ❌

  • Delete comments - ❌

  Rate Limit: 20 comments per token per hour

• Key Files:

  • components/context/CommentingContext.tsx - State management

  • components/reviewer/CommentPanel.tsx - Main sidebar

  • components/reviewer/CommentThread.tsx - Thread rendering

  • components/reviewer/CommentBadge.tsx - Node indicator

  • shared/schemas/commentsSchema.ts - Zod schemas

5. Infrastructure & Operations

• Dependencies:

  • Supabase - Comments, invites, notifications

  • Clerk - User identification

• Monitoring & Alerting:

  • Notification Types: NEW_COMMENT, COMMENT_RESOLVED, REPLY_RECEIVED

  • Analytics: Per-node heatmaps, resolution metrics

• Deployment Plan:

  1. Run migrations for all 3 tables

  2. Deploy API routes

  3. Deploy frontend components

  4. Configure RLS policies

6. Testing & Quality Assurance

• Test Strategy:

  • Manual: Comment CRUD, threading, notifications

  • Integration: Guest access, invite flow, bulk ops

  • Security: RLS policy validation

• Known Limitations:

  • Max 5000 chars per comment

  • Guest rate limit: 20/hour

  • No rich text formatting

7. Maintenance & Support

• Troubleshooting:

  • Guest token invalid → Check expiry, status in quest_invites

  • Comments not loading → Verify quest_id, check RLS

  • Notifications missing → Check recipient_clerk_id match

• Changelog:

  • 1.0 (Feb 2026): Initial implementation

  • 1.1 (Feb 2026): Added bulk operations

  • 1.2 (Feb 2026): Added analytics

Document Version

1.2 - Approved, Feature deployed to production, 02/28/2026