## Summary
Consolidate three separate frontends into a single unified Next.js
application that serves both cloud deployment and local CLI modes.
### Key Changes
- **Unified Frontend**: One Next.js app serves cloud
(gen.nomadkaraoke.com) and local CLI (karaoke-gen)
- **Delete Old Code**: Removed ~70k lines of legacy frontend code
- **UI Fixes**: Edit Modal, Instrumental Review, word timing, and more
- **Simplified URLs**: Direct routes (`/app/jobs/{id}/review`) instead
of complex query strings
## Changes
### Frontend Consolidation
- Add `/app/jobs/{id}/review` route for lyrics review
- Add `/app/jobs/{id}/instrumental` route for instrumental selection
- Migrate lyrics review components from MUI to Radix/Tailwind
- Convert vanilla JS instrumental review to React components
- Add local mode detection (`frontend/lib/local-mode.ts`)
### Local CLI Integration
- Package Next.js static export in `karaoke_gen/nextjs_frontend/out/`
- Update lyrics and instrumental review servers to serve unified
frontend
- Add cloud-compatible API routes (`/api/jobs/local/*`)
- Add SPA routing with Turbopack chunk injection workaround
### Deletions
- Remove `lyrics_transcriber_temp/lyrics_transcriber/frontend/` (~14k
lines)
- Remove `karaoke_gen/instrumental_review/static/index.html`
### Backend Updates
- Simplify email notification URLs to use consolidated routes
- Remove E2E bypass key (no longer needed)
- Update job notification service for new URL format
### UI Fixes
- Edit Modal: width, spacebar handler (Tap To Sync), footer layout
- Word highlight: purple color instead of grey
- Add word timing calculation
- Replace all words functionality
- Instrumental review: smooth 60fps playhead animation
- Success screen with countdown before window close
## Testing
- [x] All 1021 backend tests pass
- [x] All 181 frontend unit tests pass
- [x] Local CLI flow verified end-to-end
- [x] Lyrics review UI functional in browser
- [x] Instrumental review UI functional in browser
## Review
- [x] CodeRabbit CLI review completed locally (manual review due to file
count)
- [x] No security issues found
- [x] Test failures fixed
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
13 KiB
Frontend Consolidation Plan
Date: 2026-01-09
Branch: feat/sess-20260109-1931-consolidate-frontends
Approach: Big bang migration
Goal
Consolidate three separate frontends into a single Next.js application:
| Current | Lines | Location | After |
|---|---|---|---|
| Main karaoke-gen | ~10k | frontend/ |
Keep, extend |
| Lyrics Review | ~14,300 | lyrics_transcriber_temp/.../frontend/ |
Migrate to frontend/ |
| Instrumental Review | ~1,700 | karaoke_gen/instrumental_review/static/ |
Migrate to frontend/ |
Benefits:
- Single deployment (Cloudflare Pages only)
- Seamless UX (no external redirects)
- Unified codebase and build system
- Consistent design system (Radix + Tailwind)
Current Architecture
┌─────────────────────────────────────────────────────────────┐
│ gen.nomadkaraoke.com (Cloudflare Pages) │
│ └── Next.js main frontend │
│ ├── /app → Job dashboard │
│ ├── /admin → Admin panel │
│ └── Opens external URLs for review... │
└─────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ GitHub Pages │ │ Backend (Cloud Run) │
│ Lyrics Review (Vite) │ │ Instrumental (static) │
│ MUI + Emotion │ │ Vanilla HTML/JS │
└───────────────────────┘ └───────────────────────┘
Target Architecture
┌─────────────────────────────────────────────────────────────┐
│ gen.nomadkaraoke.com (Cloudflare Pages) │
│ └── Next.js unified frontend │
│ ├── /app → Job dashboard │
│ ├── /app/jobs/[id]/review → Lyrics review (embedded) │
│ ├── /app/jobs/[id]/instrumental → Instrumental select │
│ └── /admin → Admin panel │
└─────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────┐
│ Backend (Cloud Run) │
│ API only (no static) │
└───────────────────────┘
Migration Phases
Phase 1: Setup & Routing Structure
Tasks:
-
Create new Next.js routes:
frontend/app/app/jobs/[id]/review/page.tsxfrontend/app/app/jobs/[id]/instrumental/page.tsx
-
Update JobCard navigation to use internal routes instead of external URLs
-
Add temporary wrapper components that will host migrated content
Files to create:
frontend/app/app/jobs/[id]/
├── review/
│ └── page.tsx # Lyrics review route
└── instrumental/
└── page.tsx # Instrumental selection route
Phase 2: Migrate Lyrics Review Components
Source: lyrics_transcriber_temp/lyrics_transcriber/frontend/src/
Components to migrate (in dependency order):
Tier 1: Core utilities (keep as-is, move location)
types.ts→frontend/lib/lyrics-review/types.tsvalidation.ts→frontend/lib/lyrics-review/validation.tsapi.ts→ integrate intofrontend/lib/api.ts
Tier 2: Shared utilities
components/shared/utils/*.ts→frontend/lib/lyrics-review/utils/components/shared/types.ts→ merge with types.tscomponents/shared/constants.ts→frontend/lib/lyrics-review/constants.ts
Tier 3: Base components (MUI → Radix/Tailwind)
AudioPlayer.tsx- Audio playback with waveformWord.tsx- Individual word displayHighlightedText.tsx- Text highlightingSourceSelector.tsx- Source selection dropdown
Tier 4: View components
TranscriptionView.tsx- Main transcription displayReferenceView.tsx- Reference lyrics panelDurationTimelineView.tsx- Timeline visualizationEditWordList.tsx- Word list editorTimelineEditor.tsx- Timeline editing
Tier 5: Modal components
FindReplaceModal.tsxReviewChangesModal.tsxSegmentDetailsModal.tsxReplaceAllLyricsModal.tsxTimingOffsetModal.tsxAddLyricsModal.tsxModeSelectionModal.tsxCorrectionAnnotationModal.tsxAIFeedbackModal.tsx
Tier 6: Lyrics Synchronizer
LyricsSynchronizer/index.tsxLyricsSynchronizer/TimelineCanvas.tsxLyricsSynchronizer/SyncControls.tsxLyricsSynchronizer/UpcomingWordsBar.tsx
Tier 7: Main container
LyricsAnalyzer.tsx- Main orchestrator componentAppHeader.tsx- Header (merge with existing)Header.tsx- Review header
Tier 8: Metrics/Dashboard
CorrectionMetrics.tsxAgenticCorrectionMetrics.tsxMetricsDashboard.tsxPreviewVideoSection.tsx
Target structure:
frontend/
├── components/
│ └── lyrics-review/
│ ├── LyricsAnalyzer.tsx # Main container
│ ├── AudioPlayer.tsx
│ ├── TranscriptionView.tsx
│ ├── ReferenceView.tsx
│ ├── TimelineEditor.tsx
│ ├── modals/
│ │ ├── FindReplaceModal.tsx
│ │ ├── ReviewChangesModal.tsx
│ │ └── ...
│ ├── synchronizer/
│ │ ├── index.tsx
│ │ ├── TimelineCanvas.tsx
│ │ └── ...
│ └── shared/
│ ├── Word.tsx
│ └── ...
└── lib/
└── lyrics-review/
├── types.ts
├── validation.ts
├── constants.ts
└── utils/
Phase 3: Migrate Instrumental Review
Source: karaoke_gen/instrumental_review/static/index.html
Conversion approach: Extract from single HTML file to React components
Components to create:
frontend/components/instrumental-review/
├── InstrumentalSelector.tsx # Main container
├── WaveformViewer.tsx # Audio waveform display
├── StemPlayer.tsx # Individual stem playback
├── MuteRegionEditor.tsx # Custom mute region UI
├── InstrumentalOptions.tsx # Selection options
└── AudioUpload.tsx # Custom instrumental upload
Key features to preserve:
- Waveform visualization
- A/B comparison between instrumentals
- Custom mute region editing
- Custom instrumental upload
- Keyboard shortcuts
Phase 4: API Client Consolidation
Current state: 3 separate API clients
frontend/lib/api.ts- Main applyrics_transcriber_temp/.../api.ts- Lyrics review (LiveApiClient)- Vanilla fetch in
index.html- Instrumental
Target: Single unified API client in frontend/lib/api.ts
New endpoints to add:
// Lyrics review
getCorrectionData(jobId: string, token: string): Promise<CorrectionData>
submitCorrections(jobId: string, token: string, corrections: Corrections): Promise<void>
getMetadata(jobId: string): Promise<Metadata>
generatePreview(jobId: string, corrections: Corrections): Promise<PreviewResponse>
// Instrumental review
getInstrumentalAnalysis(jobId: string, token: string): Promise<Analysis>
getWaveformData(jobId: string, numPoints: number): Promise<WaveformData>
selectInstrumental(jobId: string, token: string, selection: Selection): Promise<void>
uploadCustomInstrumental(jobId: string, token: string, file: File): Promise<void>
createCustomInstrumental(jobId: string, token: string, muteRegions: MuteRegion[]): Promise<void>
getAudioStream(jobId: string, stemType: string): string // Returns URL
Phase 5: Design System Migration
MUI → Radix/Tailwind component mapping:
| MUI Component | Radix/Tailwind Equivalent |
|---|---|
Button |
components/ui/button.tsx |
Dialog |
components/ui/dialog.tsx |
TextField |
components/ui/input.tsx |
Select |
components/ui/select.tsx |
Slider |
components/ui/slider.tsx |
Tabs |
components/ui/tabs.tsx |
IconButton |
Button with icon variant |
Tooltip |
components/ui/tooltip.tsx |
CircularProgress |
components/ui/spinner.tsx |
Snackbar |
sonner toast |
Box |
<div> with Tailwind |
Typography |
Tailwind text classes |
Paper |
Card component |
Accordion |
components/ui/accordion.tsx |
Theme mapping (MUI → Tailwind CSS variables):
theme.palette.primary→--primarytheme.palette.secondary→--secondarytheme.palette.background→--backgroundtheme.spacing()→ Tailwind spacing scale
Phase 6: Navigation & State Updates
JobCard.tsx changes:
// Before (external URLs)
const reviewUrl = `${reviewUiUrl}/?baseApiUrl=${encodedApiUrl}&reviewToken=${token}&audioHash=${hash}`
window.open(reviewUrl, '_blank')
// After (internal routes)
router.push(`/app/jobs/${job.job_id}/review`)
Token handling:
- Review tokens currently passed via URL params
- Move to: Server-side session or secure cookie
- Or: Keep in URL but validate on server
Phase 7: Testing Strategy
Update existing E2E tests:
frontend/e2e/lyrics-review-only.spec.ts- Update URLsfrontend/e2e/instrumental-selection-only.spec.ts- Update URLs- Happy path tests should work unchanged (test user flow, not URLs)
New tests to add:
- Route parameter validation
- Token validation
- Component-level tests for migrated components
Phase 8: Cleanup
Delete:
lyrics_transcriber_temp/lyrics_transcriber/frontend/(entire directory)karaoke_gen/instrumental_review/static/index.html- GitHub Pages deployment workflow (if exists)
Update:
- Remove
NEXT_PUBLIC_REVIEW_UI_URLenv var - Update backend to stop serving instrumental static files
- Update documentation
Risk Mitigation
| Risk | Mitigation |
|---|---|
| Large scope | Detailed component inventory; test each phase |
| MUI→Tailwind bugs | Visual regression tests; side-by-side comparison |
| Broken functionality | E2E tests cover critical paths |
| Performance regression | Lighthouse CI; bundle size monitoring |
Estimated Component Count
| Category | Count | Complexity |
|---|---|---|
| Core types/utils | 8 | Low (copy) |
| Base components | 4 | Medium |
| View components | 5 | High |
| Modals | 9 | Medium |
| Synchronizer | 4 | High |
| Metrics | 4 | Medium |
| Instrumental | 5 (new) | Medium |
| Total | 39 |
Success Criteria
- All existing functionality works through new internal routes
- No external frontend deployments required
- E2E tests pass
- Visual parity with current UI (or better)
- No performance regression
- Single
npm run buildproduces complete frontend
Decisions Made
Authentication: Job Ownership Model
Decision: Use job ownership for access control (no URL tokens needed)
Implementation:
- User must be logged in to access
/app/jobs/[id]/reviewor/app/jobs/[id]/instrumental - Backend validates:
job.user_email === current_user.emailORcurrent_user.role === 'admin' - Simplifies URLs:
/app/jobs/abc123/reviewinstead of?reviewToken=xyz&audioHash=... - Email notification links go to
/app/jobs/{id}/review- user logs in if needed
Backend changes needed:
- Update
/api/review/{job_id}/*endpoints to check job ownership instead of token - Update
/api/jobs/{job_id}/instrumental-*endpoints similarly - Keep token-based auth as fallback for backward compatibility (deprecate later)
Audio Streaming
Decision: Keep as-is - stream directly from backend API
- Frontend calls
api.nomadkaraoke.com/api/jobs/{id}/audio-stream/{stem} - No need to proxy through Next.js
Preview Video
Decision: Keep as-is - generated on-demand by backend
- Frontend POSTs corrections, backend returns preview URL
Next Steps
- Resolve authentication question → Job ownership
- Create route structure (Phase 1)
- Migrate core types/utils (Phase 2, Tier 1-2)
- Migrate base components (Tier 3)
- Migrate view components (Tier 4)
- Migrate modals (Tier 5)
- Migrate synchronizer (Tier 6)
- Migrate main container (Tier 7)
- Convert instrumental review (Phase 3)
- Update API client (Phase 4)
- Update navigation (Phase 6)
- Update tests (Phase 7)
- Cleanup old code (Phase 8)