Files
karaoke-gen/frontend
Andrew Beveridge ☄️andClaude Opus 4.5 42c304dcdf feat(multitenancy): Implement white-label B2B portal infrastructure (#241)
## Summary

Adds multi-tenant white-label portal infrastructure for B2B customers.
Vocal Star is the first tenant at `vocalstar.nomadkaraoke.com`.

## Changes

### Backend
- **Tenant Models** (`backend/models/tenant.py`): Pydantic models for
TenantConfig with branding, features, defaults, and auth settings
- **Tenant Service** (`backend/services/tenant_service.py`): GCS-backed
config loading with 5-min cache, signed URL generation for logos
- **Tenant API** (`backend/api/routes/tenant.py`): `GET
/api/tenant/config` and `GET /api/tenant/config/{tenant_id}` endpoints
- **Tenant Middleware** (`backend/middleware/tenant.py`): Extracts
tenant from X-Tenant-ID header, query param (dev only), or Host
subdomain
- **Auth Updates**: Email domain validation for tenant-restricted auth,
sender email override
- **Feature Enforcement**: Audio search endpoint checks
`features.audio_search`, returns 403 if disabled
- **Job Scoping**: Added `tenant_id` field to JobCreate

### Frontend
- **Tenant Store** (`frontend/lib/tenant.ts`): Zustand store with tenant
state, `useTenant()` hook, CSS variable application
- **TenantProvider** (`frontend/components/tenant-provider.tsx`):
Hydration-safe initialization via useEffect
- **TenantLogo** (`frontend/components/tenant-logo.tsx`): Dynamic logo
with fallback to Nomad Karaoke
- **Feature-Flagged UI**: Tabs conditionally rendered based on tenant
features, active tab sync
- **Locked Themes**: `defaults.locked_theme` hides theme selector and
enforces specific theme
- **Output Links**: Filtered based on distribution features

### Security
- Query param tenant detection disabled in production (prevents
spoofing)
- Strict subdomain patterns: only `{tenant}.nomadkaraoke.com` or
`{tenant}.gen.nomadkaraoke.com`
- PII masking in logs (`an***@vo***.com`)
- `is_active` check prevents inactive tenants from being used

### Documentation
- ARCHITECTURE.md: New Multitenancy section
- API.md: Tenant Config endpoints
- LESSONS-LEARNED.md: 3 new lessons on multitenancy patterns
- Archive: Comprehensive implementation document

### Setup
- `scripts/setup-vocalstar-tenant.py`: Uploads theme assets, creates
tenant/theme configs in GCS

## Vocal Star Configuration

- **Subdomain**: `vocalstar.nomadkaraoke.com`
- **Features**: File upload only (no audio search, no YouTube URL)
- **Distribution**: Download only (no YouTube/Dropbox/GDrive)
- **Theme**: Locked to "vocalstar" (yellow/blue)
- **Auth**: Restricted to `@vocal-star.com` and `@vocalstarmusic.com`
emails

## Testing

- [x] Frontend TypeScript build passes
- [x] CodeRabbit CLI review completed (3 cycles, all issues fixed)
- [x] Manual testing with `?tenant=vocalstar` query param

## Next Steps (post-merge)

1. Configure DNS: CNAME for `vocalstar.nomadkaraoke.com`
2. Update Cloudflare Pages for subdomain
3. Run setup script to upload Vocal Star assets to GCS
4. Test at `https://vocalstar.nomadkaraoke.com`

@coderabbitai ignore

---
🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-08 16:39:56 -05:00
..

Karaoke Generator Frontend

Next.js frontend for the Karaoke Generator application.

Quick Start

# Install dependencies
npm install

# Run development server
npm run dev

The app will be available at http://localhost:3000

Development Setup

Connecting to the Cloud Backend

In development, the frontend proxies API requests to the cloud backend (api.nomadkaraoke.com) via Next.js rewrites. This avoids CORS issues and allows local development without running a local backend.

The proxy is configured in next.config.mjs:

  • All /api/* requests are forwarded to the cloud backend
  • You can override the backend URL with BACKEND_URL environment variable

Authentication

The backend requires authentication. To authenticate:

  1. Create a .env.local file in the frontend directory:

    KARAOKE_ACCESS_TOKEN=your-token-here
    
  2. The token is automatically loaded by Playwright tests

  3. In the browser, the token is stored in localStorage as karaoke_access_token

Testing

Unit Tests (Jest)

# Run tests in watch mode
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in CI mode
npm run test:ci

E2E Tests (Playwright)

E2E tests run against the local dev server connected to the real cloud backend.

# Run all E2E tests
npm run test:e2e

# Run with UI (interactive mode)
npm run test:e2e:ui

# Run in headed mode (see the browser)
npm run test:e2e:headed

# Run in debug mode
npm run test:e2e:debug

Authentication for E2E Tests

E2E tests require a valid access token. Set it in .env.local:

KARAOKE_ACCESS_TOKEN=your-token-here

The Playwright config (playwright.config.ts) automatically loads this file.

Test Structure

Tests are located in e2e/:

  • karaoke-generation.spec.ts - Main test suite covering:
    • Homepage loading and form display
    • Search tab functionality
    • Audio search submission
    • Audio selection dialog flow
    • API health checks

Test Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│   Playwright    │────▶│  Next.js Dev     │────▶│  Cloud Backend      │
│   Browser       │     │  Server (:3000)  │     │  api.nomadkaraoke   │
└─────────────────┘     └──────────────────┘     └─────────────────────┘
                              │
                              ▼
                        API Proxy
                        /api/* → backend

Debugging Test Failures

  1. Screenshots: Failed tests save screenshots to test-results/
  2. Videos: First retry captures video (when retries enabled)
  3. Traces: View detailed traces with npx playwright show-trace <trace.zip>
  4. HTML Report: After running tests, view npx playwright show-report

Common Issues

  • 401 Unauthorized: Token missing or invalid - check .env.local
  • Socket hang up: Backend operation taking too long - some operations (like audio download) can take minutes
  • Element outside viewport: Dialog scrolling issues - tests use JavaScript click to handle this

Project Structure

frontend/
├── app/                    # Next.js app router pages
├── components/             # React components
│   ├── ui/                 # shadcn/ui components
│   └── audio-search/       # Audio search feature components
├── lib/                    # Utilities and API client
│   └── api.ts              # Backend API client
├── e2e/                    # Playwright E2E tests
├── playwright.config.ts    # Playwright configuration
└── next.config.mjs         # Next.js configuration

Scripts

Script Description
npm run dev Start development server
npm run build Build for production
npm run start Start production server
npm run lint Run ESLint
npm test Run unit tests (watch mode)
npm run test:ci Run unit tests (CI mode with coverage)
npm run test:e2e Run E2E tests
npm run test:e2e:ui Run E2E tests with interactive UI