## 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>
13 KiB
Plan: White Label B2B Karaoke Portals
Created: 2026-01-08 Branch: feat/sess-20260108-0358-white-label-portal Status: Draft
Overview
Add multi-tenant white label portal capability to karaoke-gen, enabling B2B customers like Vocal Star to access a customized version of the generator app on their own subdomain with their branding, theme, and restricted feature set.
First customer: Vocal Star
- Subdomain:
vocalstar.nomadkaraoke.com - Workflow: Upload original + instrumental audio (no audio search)
- Theme: Custom Vocal Star karaoke theme (already exists as JSON)
- Distribution: Download only (no Dropbox/GDrive/YouTube)
- Auth: Magic link for
@vocal-star.com/@vocalstarmusic.comdomains, plus fixed API token option
Requirements
Functional Requirements
- Tenant identification via subdomain (e.g.,
vocalstar.nomadkaraoke.com) - Per-tenant frontend branding (logo, colors, metadata)
- Per-tenant feature flags (hide audio search, hide distribution options)
- Per-tenant default theme (always use Vocal Star theme)
- Per-tenant allowed email domains for magic link auth
- Per-tenant fixed API token support (for automation)
- Jobs scoped to tenant (Vocal Star users only see Vocal Star jobs)
- Users scoped to tenant
Non-Functional Requirements
- Minimal code duplication - single codebase serves all tenants
- Easy to add new tenants via config, not code changes
- Graceful fallback - default to Nomad Karaoke if no tenant match
- No performance impact on existing single-tenant flow
Technical Approach
Architecture Decision: Config-Driven Multi-Tenancy
Rather than building a full tenant management system (overkill for ~1 customer/year), we'll use a config-driven approach:
- Tenant configs stored in GCS at
tenants/{tenant_id}/config.json - Frontend detects subdomain and fetches tenant config from API
- Backend middleware extracts tenant from request and applies config
- Firestore collections get
tenant_idfield for isolation
This approach:
- Requires no database migrations for new tenants
- Configs can be managed via simple JSON files
- Easy to test locally with query param override (
?tenant=vocalstar) - Can evolve to admin UI later if needed
Tenant Config Schema
{
"id": "vocalstar",
"name": "Vocal Star",
"subdomain": "vocalstar.nomadkaraoke.com",
"branding": {
"logo_url": "gs://karaoke-gen-storage/tenants/vocalstar/logo.png",
"primary_color": "#ffff00",
"secondary_color": "#006CF9",
"favicon_url": "gs://karaoke-gen-storage/tenants/vocalstar/favicon.ico",
"site_title": "Vocal Star Karaoke Generator"
},
"features": {
"audio_search": false,
"file_upload": true,
"youtube_upload": false,
"dropbox_upload": false,
"gdrive_upload": false,
"theme_selection": false
},
"defaults": {
"theme_id": "vocalstar",
"distribution_mode": "download_only"
},
"auth": {
"allowed_email_domains": ["vocal-star.com", "vocalstarmusic.com"],
"fixed_tokens": ["<will be in Secret Manager>"]
}
}
Key Implementation Details
1. Subdomain Detection (Frontend)
- Next.js middleware checks
request.headers.host - If subdomain matches tenant, store tenant ID in cookie/context
- Fetch
/api/tenant/configto get branding/features - Apply CSS variables dynamically for colors
- Swap logo component based on config
2. Tenant Middleware (Backend)
- FastAPI middleware extracts tenant from:
X-Tenant-IDheader (set by frontend)- Or subdomain from
Hostheader - Or query param
?tenant=(dev only)
- Attaches
tenant_idto request state - Tenant config loaded from GCS (cached 5 min like themes)
3. Auth Enhancement
AuthService.validate_token_full()already returnsuser_email- Add tenant validation: check if user's email domain is in tenant's allowed list
- Support fixed tokens per tenant (stored in
auth_tokenswithtenant_id) - Magic links include tenant context for proper redirect
4. Data Isolation
- Add
tenant_id: Optional[str]to User and Job models - Default to
Nonefor existing Nomad Karaoke users (backwards compatible) - Query filters:
where('tenant_id', '==', tenant_id or None) - No schema migration needed - new field, optional
5. Theme Integration
- Upload Vocal Star theme to
themes/vocalstar/in GCS - Upload assets (backgrounds, fonts) to
themes/vocalstar/assets/ - Tenant config specifies
default_theme_id: "vocalstar" - When
theme_selection: false, UI hides theme picker and uses default
Implementation Steps
Phase 1: Backend Tenant Foundation (Day 1-2)
-
Create tenant model and config loader
- Create
backend/models/tenant.pywithTenantConfig,TenantBranding,TenantFeatures - Create
backend/services/tenant_service.pywith GCS config loading and caching - Add
GET /api/tenant/configendpoint (unauthenticated, returns public config) - Add
GET /api/tenant/config/{tenant_id}for explicit tenant fetch
- Create
-
Add tenant middleware
- Create
backend/api/middleware/tenant.py - Extract tenant from subdomain or header
- Attach to
request.state.tenant_idandrequest.state.tenant_config - Add
get_tenant()dependency for routes
- Create
-
Update data models
- Add
tenant_id: Optional[str] = NonetoUsermodel - Add
tenant_id: Optional[str] = NonetoJobmodel - Update Firestore indexes in Pulumi for tenant-scoped queries
- Add
-
Update auth for tenant awareness
- Modify
AuthServiceto validate email domain against tenant config - Add tenant context to magic link generation
- Support per-tenant fixed tokens in
auth_tokenscollection
- Modify
Phase 2: Upload Vocal Star Theme (Day 2)
-
Prepare Vocal Star theme for GCS
- Convert local paths in
karaoke-prep-styles-vocalstar.jsonto GCS paths - Upload background images to
themes/vocalstar/assets/ - Upload Oswald font to
themes/vocalstar/assets/ - Upload
style_params.jsontothemes/vocalstar/ - Create preview image and upload to
themes/vocalstar/preview.png - Add Vocal Star to
themes/_metadata.json
- Convert local paths in
-
Create Vocal Star tenant config
- Create
tenants/vocalstar/config.jsonin GCS - Upload Vocal Star logo to
tenants/vocalstar/logo.png - Upload favicon to
tenants/vocalstar/favicon.ico
- Create
Phase 3: Frontend Tenant Support (Day 3-4)
-
Add tenant context provider
- Create
frontend/lib/tenant.tswith tenant config types - Create
frontend/hooks/useTenant.tsfor tenant state - Create
TenantProvidercomponent that fetches config on mount - Detect subdomain in
_app.tsxor middleware
- Create
-
Dynamic branding
- Create
TenantLogocomponent that renders tenant or default logo - Update
globals.cssto support CSS variable overrides - Add
applyTenantColors()function to set CSS variables from config - Update page metadata (title, favicon) from tenant config
- Create
-
Feature-flagged UI
- Wrap audio search in
{tenant.features.audio_search && ...} - Wrap theme selector in
{tenant.features.theme_selection && ...} - Wrap distribution options based on tenant features
- Show simplified form for Vocal Star (just file upload fields)
- Wrap audio search in
-
Update magic link flow
- Pass tenant context when requesting magic link
- Magic link redirect goes to tenant subdomain
- Verify endpoint extracts tenant from link context
Phase 4: Backend Feature Enforcement (Day 4-5)
-
Enforce tenant features in API
- Audio search endpoint: return 403 if
audio_search: false - File upload: check
file_upload: true - Distribution settings: ignore/error if disabled features requested
- Theme selection: use default if
theme_selection: false
- Audio search endpoint: return 403 if
-
Job creation with tenant context
JobCreatehandler setstenant_idfrom request state- Distribution config respects tenant defaults
- Theme defaults to tenant's default theme
-
Query scoping
- Update
JobManager.get_jobs()to filter by tenant_id - Update
UserServicequeries to include tenant_id - Admin endpoints bypass tenant filter (see all tenants)
- Update
Phase 5: Infrastructure & Deployment (Day 5-6)
-
DNS setup
- Add
vocalstar.nomadkaraoke.comCNAME to Cloudflare - Configure Cloudflare Pages to accept wildcard subdomain
- Add SSL certificate for subdomain
- Add
-
Backend CORS update
- Add
vocalstar.nomadkaraoke.comto allowed origins - Or use pattern matching for
*.nomadkaraoke.com
- Add
-
Pulumi updates
- Add Firestore indexes for tenant_id queries
- Add any new secrets (tenant fixed tokens)
Phase 6: Testing & Documentation (Day 6-7)
-
Testing
- Unit tests for TenantService config loading
- Unit tests for tenant middleware
- E2E test for Vocal Star flow (upload audio, generate, download)
- Test magic link works for @vocal-star.com email
-
Documentation
- Update CLAUDE.md with tenant info
- Create
docs/WHITE-LABEL.mdwith tenant setup guide - Document how to add new tenants
Files to Create/Modify
| File | Action | Description |
|---|---|---|
backend/models/tenant.py |
Create | Tenant config models |
backend/services/tenant_service.py |
Create | Tenant config loading/caching |
backend/api/routes/tenant.py |
Create | Tenant config API endpoint |
backend/api/middleware/tenant.py |
Create | Tenant extraction middleware |
backend/api/dependencies.py |
Modify | Add get_tenant() dependency |
backend/models/user.py |
Modify | Add tenant_id field |
backend/models/job.py |
Modify | Add tenant_id field |
backend/services/auth_service.py |
Modify | Tenant email domain validation |
backend/services/user_service.py |
Modify | Tenant-aware user queries |
backend/services/job_manager.py |
Modify | Tenant-aware job queries |
backend/api/routes/file_upload.py |
Modify | Tenant feature enforcement |
backend/api/routes/audio_search.py |
Modify | Tenant feature enforcement |
backend/main.py |
Modify | Add tenant middleware |
frontend/lib/tenant.ts |
Create | Tenant types and API |
frontend/hooks/useTenant.ts |
Create | Tenant context hook |
frontend/components/TenantProvider.tsx |
Create | Tenant context provider |
frontend/components/TenantLogo.tsx |
Create | Dynamic logo component |
frontend/app/layout.tsx |
Modify | Add TenantProvider |
frontend/app/globals.css |
Modify | CSS variable support for tenant colors |
frontend/app/app/page.tsx |
Modify | Feature-flag UI sections |
infrastructure/__main__.py |
Modify | Add tenant Firestore indexes |
docs/WHITE-LABEL.md |
Create | Tenant setup documentation |
Testing Strategy
Unit Tests
TenantService: Config loading, caching, validationTenantMiddleware: Subdomain extraction, header extractionAuthService: Tenant email domain validationJobManager: Tenant-scoped queries
Integration Tests (Emulator)
- Create job with tenant context
- Query jobs filtered by tenant
- Auth with tenant-allowed email domain
- Auth rejection for wrong email domain
E2E Tests
- Vocal Star happy path: Upload audio files, review lyrics, download video
- Auth flow: Magic link for @vocal-star.com, verify redirect to subdomain
- Feature hiding: Verify audio search not shown on Vocal Star portal
Open Questions
-
Q: Should tenant configs be in GCS or Firestore? A: GCS - simpler, matches theme pattern, easy to edit JSON directly
-
Q: How to handle localhost development for specific tenant? A: Query param override
?tenant=vocalstarfor local testing -
Q: Should admin portal be tenant-aware? A: No - admins see all tenants. Admin routes bypass tenant filter.
-
Q: Do we need tenant-specific email sender identity? A: Yes - use
{tenant}@nomadkaraoke.com(e.g.,vocalstar@nomadkaraoke.com). Catchall is configured. -
Q: Vocal Star logo and favicon - do you have these assets? A: Logo provided as
vocalstar-logo.jpg- yellow star, white text on black. Will convert to PNG with transparency for web use.
Rollback Plan
Since this is additive (new optional tenant_id field), rollback is straightforward:
- Revert frontend to not check tenant
- Revert backend middleware to not extract tenant
- Existing data unaffected (tenant_id = null = Nomad Karaoke)
- No schema migration to reverse
For DNS: Simply remove CNAME record if needed.
Success Criteria
- Vocal Star user can access
vocalstar.nomadkaraoke.com - Portal shows Vocal Star branding (logo, colors)
- Audio search is hidden; only file upload available
- Theme is locked to Vocal Star style
- Distribution options hidden; download only
- Magic link works for @vocal-star.com emails
- Fixed API token works for automation
- Generated videos use Vocal Star theme
- Nomad Karaoke portal unchanged at gen.nomadkaraoke.com