# queue design

## overview

The queue is a cross-device, server-authoritative data model with optimistic local updates. Every device performs queue mutations locally, pushes a full snapshot to the API, and receives hydrated track metadata back. Servers keep an in-memory cache (per process) in sync via Postgres LISTEN/NOTIFY so horizontally scaled instances observe the latest queue state without adding Redis or similar infra.

## server implementation

- `queue_state` table (`did`, `state`, `revision`, `updated_at`). `state` is JSONB containing `track_ids`, `current_index`, `current_track_id`, `shuffle`, `repeat_mode`, `original_order_ids`.
- `QueueService` keeps a TTL LRU cache (`maxsize 100`, `ttl 5m`). Cache entries include both the raw state and the hydrated track list.
- On startup the service opens an asyncpg connection, registers a `queue_changes` listener, and reconnects on failure. Notifications simply invalidate the cache entry; consumers fetch on demand.
- `GET /queue/` returns `{ state, revision, tracks }`. `tracks` is hydrated server-side by joining against `tracks`+`artists`. Duplicate queue entries are preserved—hydration walks the `track_ids` array by index so the same `file_id` can appear multiple times. Response includes an ETag (`"revision"`).
- `PUT /queue/` expects an optional `If-Match: "revision"`. Mismatched revisions return 409. Successful writes increment the revision, emit LISTEN/NOTIFY, and rehydrate so the response mirrors GET semantics.
- Hydration preserves order even when duplicates exist by pairing each `track_id` position with the track returned by the DB. We never de-duplicate on the server.

## client implementation (Svelte 5)

- Global queue store (`frontend/src/lib/queue.svelte.ts`) uses runes-backed `$state` fields for `tracks`, `currentIndex`, `shuffle`, etc. Methods mutate these states synchronously so the UI remains responsive.
- A 250 ms debounce batches PUTs. We skip background GETs while a PUT is pending/in-flight to avoid stomping optimistic state.
- Conflict handling: on 409 the client performs a forced `fetchQueue(true)` which ignores local ETag and applies the server snapshot if the revision is newer. Older revisions received out-of-order are ignored.
- Before unload / visibility change flushes pending work to reduce data loss when navigating away.
- Helper getters (`getCurrentTrack`, `getUpNextEntries`) supplement state but UI components bind directly to `$state` so Svelte reactivity tracks mutations correctly.
- Duplicates: adding the same track repeatedly simply appends another copy. Removal is disabled for the currently playing entry (conceptually index 0); the queue sidebar only allows removing future items.

## UI behavior

- sidebar shows "now playing" card with prev/next buttons
- shuffle control in player footer (always visible)
- "up next" lists tracks beyond `currentIndex`
- drag-and-drop reordering supported for upcoming tracks
- removing a track updates local state and syncs to server
- `queue.playNow(track)` inserts track at position 0, preserves existing up-next order
- duplicate tracks allowed - same track can appear multiple times in queue
- auto-play preference controls automatic advancement to next track
- persisted via `/preferences/` API and localStorage
- queue toggle button opens/closes sidebar
- responsive positioning for mobile viewports
- cannot remove currently playing track (index 0)

## shuffle

- shuffle is an action, not a toggle mode
- each shuffle operation randomly reorders upcoming tracks (after current track)
- preserves everything before and including the current track
- uses fisher-yates algorithm with retry logic to ensure different permutation
- original order preserved in `original_order_ids` for server persistence

## cross-tab synchronization

- uses BroadcastChannel API for same-browser tab sync
- each tab has unique `tabId` stored in sessionStorage
- queue updates broadcast to other tabs via `queue-updated` message
- tabs ignore their own broadcasts and duplicate revisions
- receiving tabs fetch latest state from server
- `lastUpdateWasLocal` flag tracks update origin

## future work

- realtime push via SSE/WebSocket for instant cross-device updates
- UI affordances for "queue updated on another device" notifications
- repeat modes (currently not implemented)
- clear up-next functionality exposed in UI