@coderabbitai ignore
## Summary
- Add "Edit Reviews" section to admin dashboard for reviewing user
lyrics corrections
- New backend endpoints: `GET /api/admin/edit-reviews` (list) and `GET
/api/admin/edit-reviews/{job_id}` (detail snapshot)
- Three frontend views: read-only lyrics review, edit log replay with
step-through, raw data JSON viewer
- All endpoints are strictly read-only (no state mutations, no
Firestore/GCS writes)
- 7 backend unit tests covering filtering, search, pagination, test
exclusion, error handling
## Motivation
Users are now making lyrics corrections during the review phase, and
we're collecting edit logs. This dashboard lets admins:
1. See what users experienced (original vs corrected lyrics in read-only
LyricsAnalyzer)
2. Replay user edits step-by-step to evaluate quality
3. Review raw human edits data for potential AudioShake data sharing
## Test plan
- [x] 7 backend unit tests pass (list filtering, search, pagination,
test exclusion, 404, full snapshot, missing files)
- [ ] Manual: navigate to /admin/edit-reviews, verify list loads
- [ ] Manual: click View Review, verify read-only LyricsAnalyzer renders
- [ ] Manual: click View Edit Log, verify step-through works
- [ ] Manual: click View Raw Data, verify JSON tabs render
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
6.2 KiB
Plan: Admin Lyrics Review Dashboard
Created: 2026-03-05 Branch: feat/sess-20260305-0002-admin-lyrics-review Status: Draft
Overview
Add an "Edit Reviews" section to the admin dashboard for reviewing completed lyrics reviews. Three goals:
- View what users saw - Jump into a read-only lyrics review UI showing original vs corrected lyrics
- Replay user edits - Step through edit log entries to see exactly what each user changed
- Review raw data - View human edits data to evaluate quality for AudioShake data sharing
Requirements
- New admin sidebar item "Edit Reviews" linking to
/admin/edit-reviews - Backend endpoint to list recent jobs that have completed lyrics review (with edit logs)
- Backend endpoint to serve immutable correction data for a job (read-only, cannot modify job)
- Admin page showing list of recently reviewed jobs with key metrics
- Ability to open the existing LyricsAnalyzer in read-only mode with snapshot data
- Edit log replay/stepper UI to walk through user changes one by one
- Raw data viewer for edit logs, annotations, and correction diffs
Technical Approach
Backend: 2 new admin endpoints
-
GET /api/admin/edit-reviews- List jobs with completed reviews- Query Firestore for jobs with
state_data.last_edit_log_pathset (indicating review was performed) - Filter by status (completed jobs, or optionally all post-review statuses)
- Return summary: job_id, artist, title, user_email, review_completed_at, edit_count, feedback_count
- Support pagination, search, exclude_test filtering
- Query Firestore for jobs with
-
GET /api/admin/edit-reviews/{job_id}- Get full review snapshot- Returns immutable copy of:
- Original corrections (
corrections.jsonfrom GCS) - Updated corrections (
corrections_updated.jsonfrom GCS) - Edit log (
edit_log_{session_id}.jsonfrom GCS) - Annotations (
annotations.jsonfrom GCS) - Job metadata (artist, title, user_email, timestamps)
- Audio URL (signed, for playback in review UI)
- Original corrections (
- This is a read-only endpoint - no job state mutations
- Uses
require_admindependency (notrequire_review_auth) - Does NOT transition job status or modify any state
- Returns immutable copy of:
Frontend: New admin page + Read-only review mode
-
/admin/edit-reviews/page.tsx- List page- Table of recently reviewed jobs
- Columns: Artist/Title, User, Review Date, Edits Made, Feedback Given, Actions
- "View Review" button → opens read-only lyrics review
- "View Edit Log" button → opens edit replay view
- "View Raw Data" button → shows raw JSON
-
Read-only review viewer - Reuse LyricsAnalyzer
- Load data from the new admin endpoint (not the regular review endpoint)
- Pass
isReadOnly={true}andapiClient={null}to LyricsAnalyzer - Header shows "Admin Review - Read Only" indicator
- No submit/save buttons, no state transitions
- Audio playback still works (via signed URL)
-
Edit log replay - New component
- Timeline/stepper showing each edit entry
- For each entry: operation type, text before → text after, timestamp
- Step forward/backward through edits
- Show feedback reason if user provided one
- Summary stats: total edits, edits with feedback, correction types breakdown
-
Raw data viewer - JSON viewer tabs
- Tab 1: Edit Log (formatted JSON with syntax highlighting)
- Tab 2: Annotations
- Tab 3: Corrections diff (original vs updated)
Key safety guarantee
The admin review endpoint serves a snapshot of the data. It reads from GCS files that were already written. The LyricsAnalyzer receives apiClient={null} so it physically cannot call any mutation endpoints. Even if code changes in the future, the admin endpoint itself never writes to Firestore or GCS.
Implementation Steps
- Backend: Add
GET /api/admin/edit-reviewsendpoint - List reviewed jobs with edit log metadata - Backend: Add
GET /api/admin/edit-reviews/{job_id}endpoint - Serve full immutable review snapshot - Frontend: Add admin API client methods -
adminApi.listEditReviews(),adminApi.getEditReview(jobId) - Frontend: Create
/admin/edit-reviews/page.tsx- List page with table - Frontend: Add sidebar nav item - "Edit Reviews" with BookOpen icon
- Frontend: Create read-only review viewer - Load snapshot data into LyricsAnalyzer with isReadOnly
- Frontend: Create edit log replay component - Step-through UI for edit entries
- Frontend: Create raw data viewer - JSON viewer with tabs
- Tests: Backend unit tests for new admin endpoints
- Tests: Frontend component tests for new page
Files to Create/Modify
| File | Action | Description |
|---|---|---|
backend/api/routes/admin.py |
Modify | Add edit-reviews endpoints |
frontend/lib/api.ts |
Modify | Add adminApi methods for edit reviews |
frontend/app/admin/edit-reviews/page.tsx |
Create | Main edit reviews list page |
frontend/components/admin/edit-review-viewer.tsx |
Create | Read-only review wrapper using LyricsAnalyzer |
frontend/components/admin/edit-log-replay.tsx |
Create | Edit log stepper/replay component |
frontend/components/admin/raw-data-viewer.tsx |
Create | JSON viewer with tabs |
frontend/components/admin/admin-sidebar.tsx |
Modify | Add Edit Reviews nav item |
backend/tests/test_admin_edit_reviews.py |
Create | Backend tests |
Testing Strategy
- Unit tests for backend endpoints (mock Firestore + GCS)
- Verify admin auth is required on all new endpoints
- Verify no write operations occur on read-only endpoints
- Frontend component tests for key interactions
Open Questions
- Should we show ALL jobs that went through review, or only ones with edit logs? (Recommendation: only those with edit logs, since those are the interesting ones)
- Do we need audio playback in the admin review viewer? (Recommendation: yes, it helps understand what the user heard)
- Should the raw data be downloadable? (Nice-to-have, can add later)
Rollback Plan
All changes are additive (new endpoints, new pages). Removing the sidebar link effectively hides the feature. No existing behavior is modified.