swingmusic-extended/PLAN2.md

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-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.