mirror of
https://github.com/Dvorinka/swingmusic-extended.git
synced 2026-06-03 20:13:02 +00:00
Tomas Dvorak
cbf646e25b
## Major Changes - Fixed all TypeScript errors in web client for successful compilation - Resolved 82+ Python lint errors across backend services - Updated Flutter SDK compatibility for mobile app - Fixed security workflow configuration ## Web Client Fixes - Fixed import path in DragonflyDashboard.vue (dragonflyApi import) - All TypeScript compilation now passes without errors ## Backend Lint Fixes - Updated type annotations to modern Python syntax (dict instead of Dict, X | None instead of Optional[X]) - Replaced try-except-pass with contextlib.suppress(Exception) - Removed unused imports (Dict, Optional, Any, Iterator, etc.) - Fixed bare except clauses to use Exception - Sorted and formatted imports with ruff - Applied ruff format to 27 files ## Workflow Fixes - Updated Flutter SDK constraint from ^3.10.4 to ^3.5.0 (compatible with Flutter 3.24.0) - Changed pip-audit format from github to json in security.yml - Added comprehensive CI workflows (readiness-gate.yml, security.yml) ## Infrastructure - Added DragonflyDB caching system integration - Enhanced Docker configuration with multi-stage builds - Added pytest configuration and test infrastructure - Improved production readiness with proper error handling ## Verification - backend-lint job: ✅ Succeeded - web job: ✅ Succeeded - Ready for GitHub deployment All CI/CD issues resolved. Codebase now passes all quality checks.
110 lines
5.7 KiB
Markdown
110 lines
5.7 KiB
Markdown
## 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.
|