Phase 12: Library CRUD & Data Integrity - Context

Gathered: 2026-03-12 Status: Ready for planning

## Phase Boundary

Users can add, rename, and remove libraries through the UI with correct data lifecycle management. Tracks are created/deleted, shared entities (artists, albums, genres) are cleaned up only when orphaned, FTS5 search index stays consistent, queue tracks cascade-delete, and playlist tracks convert to phantoms. The library manager UI lives in settings alongside scan controls.

## Implementation Decisions

Library management UI

Integrated library + scan section in the settings page — combine library management and scanning into one unified section
Remove the libraries tab from the sidebar list entirely
Each library row displays: name, directory path, track count in the main row; actions (rename, remove, rescan) hidden behind a ... overflow menu
Replace the old single-directory config UI (directory path field + rescan button) completely — the migrated library appears in the new list

Add-library flow

Click "Add Library" button in the library management section
OS folder picker dialog opens
Library auto-named from the folder name (editable later via rename)
Scan starts automatically after adding
Uses the existing per-library scan pipeline from Phase 11

Removal confirmation & feedback

Warning dialog with impact summary before removal: "Remove 'Jazz Collection'? This will delete 1,234 tracks, affect 2 playlists, and remove 15 queue items."
If a track from the library being removed is currently playing, stop playback first, then proceed with removal; queue advances to next valid track if one exists
Blocking operation with spinner on the dialog while cleanup runs (expected < 1 second for most libraries)
Toast notification on completion: "Removed 'Jazz Collection' (1,234 tracks deleted)"

Orphan cleanup behavior

Immediate cleanup in the same database transaction — delete tracks, identify orphaned entities, delete orphans, convert playlist phantoms, all atomic
Reference-counting bottom-up: only delete artists/albums/genres that have zero remaining track references after the library's tracks are removed
Rebuild the entire FTS5 index from remaining tracks after library removal (handles contentless table limitation cleanly)
Playlist phantom track conversion in the same transaction: copy track metadata to phantom columns on playlist_tracks, then SET NULL the audio_file_id
Queue tracks cascade-delete (queue is ephemeral, not user-curated)
Removal API endpoint returns cleanup summary: {tracks_deleted, artists_removed, albums_removed, genres_removed, playlists_affected, queue_items_removed} — feeds the toast notification

Rename & display behavior

Library names must be unique — validation error if user tries to use an existing name
Inline edit on the list row: click name (or rename action from menu) turns it into an editable text field, Enter to save, Escape to cancel
Name validation: 1-50 characters, non-empty
Rename changes display name only — changing a library's directory path requires remove + add (no path editing)

Claude's Discretion

Exact layout/styling of the library management section within settings
Loading skeleton design while library list loads
Error state handling for failed operations
Exact spinner implementation during removal
Toast notification library/component choice
API endpoint URL structure and HTTP methods
SQL query optimization for orphan detection

## Specific Ideas

Library management section should feel like a natural extension of the existing settings page — not a separate app within settings
The impact summary in the removal dialog should use real counts from the database, not estimates
The ... overflow menu pattern keeps the list clean — same pattern used elsewhere in the app for action menus

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 12-library-crud-data-integrity Context gathered: 2026-03-12

4.1 KiB Raw Blame History