## SwingMusic Production-Ready Workflow Plan

### Summary
We will deliver your requested end-to-end workflow in phased, production-safe order:
1) stabilize backend boot/runtime,  
2) enforce first-run onboarding (account + music directory),  
3) implement catalog/artist/download UX behavior (top 15, full discography, availability states),  
4) integrate real server-side downloads via SpotiFLAC,  
5) make lyrics always-on (embed + `.lrc`),  
6) complete true multi-user isolation with optional cross-user import prompts.

Chosen defaults (from your answers): shared files + isolated profiles, SpotiFLAC-first downloader, onboarding wizard on first boot, Spotify/Last.fm-first cold start recommendations, embed+`.lrc` lyrics, boot-stable gate then rebuild.

### Implementation Changes
- **Phase 0: Backend stabilization gate**
- Fix startup blockers so app boots reliably (`upload` metadata import, downloader startup contract, logger contract, missing DB helper calls, migration registration).
- Replace fragile eager API import behavior with safe/lazy registration so one broken module cannot crash boot.
- Keep currently scaffold/broken modules gated behind feature flags until rebuilt on tested contracts.
- Add boot smoke checks and API registration checks as release gate.

- **Phase 1: First-run onboarding**
- Add setup state and hard onboarding flow:
- `create admin account` -> `select primary music directory` -> `trigger initial index` -> `enter dashboard`.
- Block non-auth product APIs until setup completes.
- Preserve existing multi-user auth model, but remove “implicit ready state” for uninitialized installs.

- **Phase 2: Home + artist product workflow**
- Home on empty/new profile: return API-driven recommended artists (Spotify/Last.fm-first, local fallback).
- New artist overview response contract:
- top 15 popular tracks,
- full discography,
- artist radio (similar artists),
- “This Is <Artist>” (artist-only tracks),
- per-track/album availability (`available` vs `missing`) + quality badge metadata.
- Navigation payloads normalized so clicking artist/song/playlist/radio resolves to proper page targets.

- **Phase 3: Real downloader via SpotiFLAC**
- Integrate SpotiFLAC as managed worker service for track/album/artist/playlist downloads to server-selected library folder.
- Unify queue/status/history API with deterministic job states, retries, and per-user ownership.
- Add dedupe/import-aware media registry so existing downloaded files are reused instead of duplicated when possible.

- **Phase 4: Lyrics always-on**
- Remove experimental lyrics toggle behavior.
- Default pipeline for every downloaded/ingested track:
- if embedded lyrics exist: keep/use,
- else fetch synced lyrics and write `.lrc`,
- also embed lyrics tags when format safely supports writing.
- Add background backfill job for existing library and failure reporting.

- **Phase 5: Multi-user isolation + shared import prompt**
- Keep physical media shared, but isolate each user’s logical app state:
- own library projection,
- own stats/listens/recommendations/mixes/radios/playlists/favorites/history.
- When user opens artist/playlist/radio and matching media already exists from another user, API returns `import_available` suggestion.
- User may accept/decline import every time; no forced sharing.

- **Phase 6: Personalization and radio evolution**
- Cold-start radio/recommendations from Spotify/Last.fm seeds.
- Progressively re-rank by per-user scrobbles/listen duration/skip/favorites and recency.
- Keep “This Is” playlist strictly artist-only and refreshable from updated local availability + downloads.

### Public API / Data Model Additions
- **New setup endpoints**: setup status/bootstrap/index-progress.
- **Catalog/artist contract expansion**: unified artist overview payload with availability and quality badges.
- **Downloader API normalization**: queue/job/status/history endpoints with per-user scope.
- **Import suggestion contract**: item-level `import_available` and `import_action`.
- **Lyrics pipeline state**: per-track lyrics source/status fields.
- **Data model additions**:
- setup/system-state table,
- media registry (canonical file identity),
- user-to-media projection/link table,
- downloader jobs table,
- lyrics status table.
- Migration runner will explicitly register/apply new migrations (not silent/no-op).

### Test Plan (Acceptance Scenarios)
- Fresh install:
- server boots,
- onboarding required,
- admin created,
- directory saved,
- initial index completes.
- Empty profile home shows recommended artists from external APIs (fallback behavior verified).
- Artist page returns exactly top 15 popular tracks + full discography + radio + “This Is”.
- Availability rendering contract:
- local items marked available with quality,
- missing items marked inactive/downloadable.
- Download flow:
- queue job created,
- media lands in configured server folder,
- artist page updates availability after completion.
- Lyrics:
- no experimental toggle required,
- missing lyrics auto-fetched,
- `.lrc` created,
- embedding written when supported.
- Multi-user:
- profiles remain isolated for stats/library/recommendations,
- cross-user import prompt appears only when relevant,
- decline preserves isolation, accept links media to user profile.
- Regression:
- core legacy endpoints (stream, artist, album, playlist, favorites, scrobble) remain functional.

### Assumptions and Defaults
- SpotiFLAC is available as a local dependency/service and is the primary download engine.
- Shared physical files are allowed; logical profile isolation is mandatory.
- Recommendation APIs may fail; deterministic local fallback is required.
- Existing scrobble pipeline remains the source of per-user listening counts and personalization signals.
- Stabilization phase is a hard prerequisite before feature rollout.