Content Review Portal — Build Spec

1. Why We're Building This

Our current content review workflow uses Google Docs in a shared Drive folder. It has too much friction:

• Charlotte can't reliably create or read Google Docs through the browser automation tools. Clipboard restrictions, navigation timeouts, and inability to read Suggesting-mode edits make the workflow fragile.
• Kristi has to navigate a folder structure, open docs, switch to Suggesting mode, and manage which folder things are in — all on her phone. She's reviewing content, not managing files.
• Jason has no dashboard view of what's pending, what's approved, and what needs attention. He has to check Google Drive manually.
• Format conversion pain: Charlotte creates .docx files → they get converted to Google Docs → Kristi reviews → Charlotte can't read the suggestions back programmatically. Every step loses fidelity.

The review portal solves all of this by putting the review workflow inside our own infrastructure where all three participants have clean, purpose-built interfaces.

2. User Roles & Access

Three users interact with this system. Each has a different access pattern.

2a. Kristi's Magic Link Auth

Kristi is not a Stylify user — she doesn't have an account and shouldn't need one. Instead:

1. A reviewers table stores her email and a unique access token (UUID v4).
2. Her bookmark URL looks like: stylify-ai.com/review?token=abc123...
3. The token is long-lived (no expiry unless manually rotated) and grants access to the review interface only.
4. If the token is compromised, Jason regenerates it from the admin panel. The old URL stops working.
5. The token only grants read/comment/approve access to content_reviews. No other API access.

3. Database Schema

Two new tables. Follows the existing pattern: BIGINT auto-incrementing IDs, timestamps, foreign keys to users table where applicable.

3a. content_reviews — The Review Items

-- Migration: 022_content_review_portal.sql
-- Run one statement at a time in Supabase SQL Editor

CREATE TABLE content_reviews (
  id            BIGSERIAL PRIMARY KEY,
  title         TEXT NOT NULL,           -- e.g. "Email 1: Welcome + Playbook"
  content_type  TEXT NOT NULL,           -- 'email' | 'landing_page' | 'scorecard' | 'lead_magnet' | 'instagram' | 'dm_template' | 'legal' | 'other'
  content_body  TEXT NOT NULL,           -- The full content (plain text or markdown)
  context_brief TEXT,                    -- "What is this? Why does it matter?" for the reviewer
  status        TEXT NOT NULL DEFAULT 'pending',  -- 'pending' | 'approved' | 'needs_changes' | 'revised' | 'archived'
  version       INTEGER NOT NULL DEFAULT 1,     -- Increments on each revision
  parent_id     BIGINT REFERENCES content_reviews(id),  -- Links revised versions to original
  submitted_by  TEXT NOT NULL DEFAULT 'charlotte',   -- Which agent submitted this
  expert_score  NUMERIC(3,1),            -- Expert Panel average score (e.g. 7.8)
  brand_rules   TEXT,                    -- Relevant brand rules shown to reviewer
  live_url      TEXT,                    -- Link to see it live (if applicable)
  reviewed_by   TEXT,                    -- Reviewer name (filled on approval/rejection)
  reviewed_at   TIMESTAMPTZ,             -- When the decision was made
  created_at    TIMESTAMPTZ DEFAULT NOW(),
  updated_at    TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_content_reviews_status ON content_reviews(status);
CREATE INDEX idx_content_reviews_type ON content_reviews(content_type);

3b. review_comments — Inline Feedback

CREATE TABLE review_comments (
  id          BIGSERIAL PRIMARY KEY,
  review_id   BIGINT NOT NULL REFERENCES content_reviews(id) ON DELETE CASCADE,
  author      TEXT NOT NULL,             -- 'kristi' | 'jason' | 'charlotte'
  comment     TEXT NOT NULL,             -- The feedback text
  section_ref TEXT,                      -- Which section this comment is about (e.g. "Q3" or "CTA headline")
  original_text TEXT,                   -- The specific text being commented on (for inline edits)
  suggested_text TEXT,                  -- The replacement text (if suggesting a rewrite)
  resolved    BOOLEAN DEFAULT FALSE,     -- Charlotte marks resolved after incorporating
  created_at  TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_review_comments_review ON review_comments(review_id);

3c. reviewers — Reviewer Access Tokens

CREATE TABLE reviewers (
  id        BIGSERIAL PRIMARY KEY,
  name      TEXT NOT NULL,           -- 'Kristi'
  email     TEXT UNIQUE NOT NULL,     -- 'kristiwait@hotmail.com'
  token     TEXT UNIQUE NOT NULL,     -- UUID v4, used in URL
  is_active BOOLEAN DEFAULT TRUE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Seed Kristi's reviewer record
INSERT INTO reviewers (name, email, token)
VALUES ('Kristi', 'kristiwait@hotmail.com', gen_random_uuid()::text);

4. API Endpoints

New route file: backend/src/routes/reviewRoutes.js

4a. Reviewer-Facing (Token Auth)

These endpoints use the reviewer token from the URL query parameter. Middleware: authenticateReviewer — looks up token in reviewers table, attaches reviewer info to req.reviewer.

4b. Admin-Facing (JWT Auth — existing adminAuth middleware)

5. Frontend — Kristi's Review Interface

Route: /review (public route, token-authenticated via query param)

5a. Review List View

Visual design notes:

• Pending items have a colored left border (amber) and are listed first.
• Approved items collapse into an "Already reviewed" section with green checkmarks.
• "Needs changes" items show a red flag icon and stay visible until Charlotte revises.
• Each card shows: title, content_type badge, time since submission, Expert Panel score.
• Tapping a card opens the detail view.

5b. Review Detail View

Detail view features:

• Context brief at the top in a highlighted card — tells Kristi what this is and why it matters.
• "View Live" link if a live_url is set — opens the actual page in a new tab so she can see it in context.
• Content body rendered as formatted text with clear section headers. Markdown rendering (headers, bold, lists) via a lightweight renderer.
• Inline comment anchors: Between each section, a subtle "tap to comment" affordance. Tapping opens a text input anchored to that section. The section_ref is auto-filled based on the nearest section header.
• Text selection commenting: If Kristi selects/highlights text and taps, a comment box appears with the selected text pre-filled as original_text. She can type a suggested replacement (suggested_text) or just a note. This replaces Google Docs' Suggesting mode.
• Sticky action bar at the bottom: Approve (green) and Needs Changes (red) buttons. Always visible. General notes text area above the buttons.
• Brand rules sidebar: If brand_rules is set, show a collapsible "Brand Rules" panel so Kristi can reference them while reviewing.

5c. Comment UI

Comment features:

• Section reference: Auto-detected from nearest section header. Shown as a label ("Comment on: CTA Headline").
• Selected text: If text was highlighted, it shows as a quote block. This becomes original_text.
• Suggested replacement: Optional text field. If filled, this becomes a "suggested edit" (like Google Docs Suggesting mode, but simpler). Charlotte reads this as suggested_text and knows exactly what to change.
• Note: Free-text comment explaining the reasoning. This is always available.
• Comments appear inline in the content, anchored to their section, with a subtle highlight on the relevant text.

6. Frontend — Jason's Admin View

Route: /admin/reviews (uses existing admin auth — adminAuth middleware)

This is a simple dashboard panel. Could be a new tab on the existing Six Engine Command Center, or a standalone page. Minimal build — just shows the status at a glance.

Dashboard Contents

• Status counters: Pending (amber), Needs Changes (red), Approved (green), Total.
• Item list: All reviews sorted by status (pending → needs_changes → approved). Each row: title, type badge, status badge, submitted date, reviewer, Expert Panel score.
• Click-through: Clicking an item shows the full content + all comments (same layout as Kristi's detail view, but with admin controls).
• Admin actions: Override approval/rejection, rotate reviewer token, submit new content for review (form with all fields from the API).

7. Workflow: How It All Connects

7a. Submitting Content for Review

1. Charlotte finishes content (email copy, scorecard text, landing page copy, etc.).
2. Charlotte runs Expert Panel scoring → gets a score (e.g. 7.8/10).
3. Charlotte submits to the review portal via:
   • Option A (API): POST /api/admin/reviews with all fields. Cleanest — Charlotte can do this from a Task subagent.
   • Option B (Browser): Charlotte navigates to /admin/reviews, fills the submission form, clicks Submit.
4. The review appears in Kristi's queue immediately.

7b. Kristi Reviewing

1. Kristi opens her bookmarked URL on her phone.
2. She sees pending items at the top. Taps one.
3. Reads the context brief, then the content.
4. If something needs tweaking: she highlights text, types a suggestion or note.
5. At the bottom: taps "Approve" or "Needs Changes" with an optional general note.
6. Done. Back to the list. Next item.

7c. Charlotte Incorporating Feedback

1. Charlotte reads all comments via GET /api/reviews/:id?token=admin (or API with admin JWT).
2. For each comment with suggested_text: Charlotte makes the exact change, then marks the comment resolved.
3. For general notes: Charlotte addresses them and marks resolved.
4. Charlotte submits a new version (PUT /api/admin/reviews/:id → creates v2 with parent_id linking to v1).
5. Kristi sees the new version in her queue for re-review.

7d. The Re-Approval Rule (Automated)

1. Content is approved (v1, status='approved').
2. Someone changes the content (Charlotte rewrites a line, Stitch changes a UI string, Pixel updates a caption).
3. Charlotte creates a new review with parent_id = original's ID and version = 2.
4. The original's status is automatically changed to 'revised' (indicating a newer version exists).
5. Kristi sees the new version in her pending queue — it shows "v2 — changed by Charlotte" and includes a diff summary in the context brief.
6. For typo fixes: the context brief can be as short as "Changed 'recieve' to 'receive' in paragraph 3."

8. Implementation Notes for Stitch

8a. File Structure

// New files
backend/src/migrations/022_content_review_portal.sql
backend/src/routes/reviewRoutes.js
backend/src/middleware/reviewerAuth.js

// Frontend (new components)
frontend/src/components/ReviewPortal.jsx      // Kristi's view
frontend/src/components/ReviewPortal.css
frontend/src/components/AdminReviews.jsx      // Jason's admin view (optional: add to CommandCenter)

8b. Reviewer Auth Middleware

// backend/src/middleware/reviewerAuth.js
const authenticateReviewer = async (req, res, next) => {
  const token = req.query.token;
  if (!token) return res.status(401).json({ error: 'Review token required' });

  const reviewer = await supabase
    .from('reviewers')
    .select('*')
    .eq('token', token)
    .eq('is_active', true)
    .single();

  if (!reviewer.data) return res.status(401).json({ error: 'Invalid review token' });

  req.reviewer = reviewer.data;
  next();
};

8c. Content Rendering

The content_body is stored as plain text with simple section markers. On the frontend, render with:

• Lines starting with SECTION N: or all-caps text → rendered as section headers.
• Lines starting with - → rendered as list items.
• Text in quotes → rendered with slight emphasis.
• Lines starting with Headline:, Button:, Subtext: etc. → rendered with bold labels.
• No need for a full Markdown parser — a simple custom renderer handles the content patterns Charlotte uses.

8d. Text Selection for Comments

On mobile, text selection is native (long-press). After selection, show a floating "Comment" button near the selection. Use the Selection API:

const handleTextSelection = () => {
  const selection = window.getSelection();
  if (selection.toString().trim()) {
    setSelectedText(selection.toString());
    // Find nearest section header for section_ref
    const range = selection.getRangeAt(0);
    const section = range.startContainer.parentElement
      .closest('[data-section]');
    setSectionRef(section?.dataset.section || 'General');
    setShowCommentBox(true);
  }
};

8e. Production Freeze Compatibility

8f. What NOT to Build (Scope Control)

• No email notifications. Kristi checks the page when she's ready. If we want notifications later, that's a v2 feature.
• No diff view. v1 just shows the new version with a note about what changed. Side-by-side diff is v2.
• No rich text editor. Content is plain text/simple formatting. No WYSIWYG.
• No file attachments. Just text content. If an image is needed, link to it.
• No multi-reviewer workflow. Kristi is the only reviewer for now. The schema supports multiple reviewers, but the UI doesn't need to.

9. Migration from Google Docs

Once the review portal is live:

1. Charlotte migrates existing pending items — re-submits each Google Doc review package as a content_review via the API. Includes any comments Kristi already left (manually transferred).
2. Kristi gets her new bookmark URL — Jason sends it to her. One-time setup.
3. Google Drive folder stays as archive — don't delete it. The Review Tracker spreadsheet can be retired since the portal has a built-in dashboard.
4. CLAUDE.md updated — Charlotte's Content Approval System section points to the portal instead of Google Docs.

10. Future Enhancements (v2+)

Not for initial build. Documenting so we don't forget:

• Email notification: Send Kristi an email when new content is submitted (via Kit or direct SMTP). Include a deep link to the specific item.
• Side-by-side diff: When a v2 is submitted, show what changed from v1 with highlighted additions/removals.
• Preview rendering: For emails, show a visual preview of how the email will look. For Instagram posts, show a mock Instagram card.
• Batch approve: "Approve all remaining" button for when Kristi has reviewed everything and it all looks good.
• Comment threading: Allow Charlotte to reply to Kristi's comments before resolving (for discussion).
• Approval analytics: Average time to review, common feedback themes, revision rate by content type.

11. Open Decisions for Jason

12. Artifact Self-Check

Assumption: Kristi's phone browser supports the Selection API for text highlighting. All modern mobile browsers (Safari iOS, Chrome Android) support this, but the floating "Comment" button behavior after selection may need testing on her specific device. Fallback: section-level comments (tap between sections) work on any device.

Uncertainty: Whether Charlotte should submit content via the API directly (requires making HTTP requests from Claude CoWork, which isn't currently straightforward) or via the browser UI (which we know works but is slower). The spec supports both paths — Stitch should build both the API and the form UI so we can use whichever works better in practice.