# Architecture (/docs/architecture)

```
 browser                                   lodesong server (Bun, one executable)              upstream
┌──────────────────────────┐   cookie   ┌──────────────────────────────────────────┐
│ React app (shadcn/ui)     │──────────▶│ /auth/*      sessions (SQLite, encrypted)  │
│  player engine, 2 decks   │           │ /rest/*      Subsonic proxy, adds the      │──────▶ Navidrome
│  TanStack Query + IDB     │◀──────────│              session's token, Range, abort │        (any OpenSubsonic)
│ service worker            │  audio    │ /cover/:id   resized WebP, disk LRU cache  │──────▶
│  app shell, covers,       │           │ /api/search  FTS5 index of the library     │
│  next 3 songs (Range)     │           │ /api/lyrics  Navidrome → LRCLIB, cached    │──────▶ lrclib.net
└──────────────────────────┘           │ /api/health  readiness, per server         │
                                        │ /api/history, offsets, hidden songs…       │
                                        └───────────────┬───────────────────────────┘
                                                        │ $DATA_DIR
                                         sessions.db · library.db · covers/ · session.secret
```

## Server (`apps/api/src`)

- **One origin.** The app, the API and the audio come from the same host: no CORS, cookies just work, and Web
  Audio can process the stream (ReplayGain, gapless handover, fades).
- **Sessions** (`sessions.ts`): login turns the password into a Subsonic token (`md5(password + salt)`), checks it
  against Navidrome and stores it encrypted (AES-GCM with `SESSION_SECRET`). The browser holds an httpOnly cookie;
  tokens never appear in browser storage or URLs, so audio and cover URLs are stable and cacheable.
- **Proxy** (`api.ts`): an allowlist of Subsonic endpoints. Strips any client credentials, adds the session's,
  passes `Range` through for seeking, and aborts the upstream request when the browser drops it.
- **Upstreams** come only from config (`NAVIDROME_URL` / `NAVIDROME_SERVERS`), never from a request, so the proxy
  can't be pointed elsewhere.
- **Search index** (`search-index.ts`, `search.ts`): FTS5 tables (words and trigrams) over songs, albums, artists
  and lyrics, synced after Navidrome scans. Results are filtered to the requester's music folders.
- **Lyrics** (`lyrics.ts`, `backfill.ts`): Navidrome first, LRCLIB fallback, hits and misses cached, a polite
  background backfill. See [lyrics](/docs/lyrics).
- **Covers** (`covers.ts`): fetched once per id and size step, converted to WebP, kept in an LRU on disk, served
  `immutable`.
- **Link previews** (`og.ts`, `share-store.ts`, `share-token.ts`): the player's own item links carry Open Graph tags
  and a 1200x630 JPEG card, drawn on first use by satori and resvg (WebAssembly, loaded lazily) from the bundled
  fonts. Signed-in members see real details; link holders get the snapshot a share link stores. See
  [security](/docs/security#share-links).
- **Config** (`settings.ts`): one table of every variable, checked at boot, rendered into
  [configuration](/docs/configuration).



## Web app (`apps/player/src`)

- **Player engine** (`lib/player.ts`, `lib/decks.ts`): two `<audio>` decks, each through its own gain node.
  The playing deck plays; the idle one holds the next song. A few ms before the end the idle deck starts and they
  swap (gapless). Downloads ahead only start once the playing song is safely buffered, so they never starve it.
  A stall watchdog reloads a stream only when no bytes arrive for 8 s.
- **Queue** (`lib/queue.ts`): history, "your queue" (play next / add), and the context (album, playlist…), with a
  balanced shuffle. Pure functions with unit tests.
- **State:** the player is an external store read through selectors, and the playback position is a separate
  ticker, so lists don't re-render while music plays. Library data goes through TanStack Query, persisted to
  IndexedDB per account, so a reload paints instantly.
- **Lists** are virtualized (`@tanstack/react-virtual`): a 10k-song list keeps ~40 rows in the DOM.
- **Service worker** (`sw.ts`): app shell for offline, covers cache-first, and the next songs downloaded one at a time
  at low priority into an LRU audio cache that serves Range requests (instant seeks, offline playback).
- **Shortcuts** (`lib/shortcuts.ts`, `app-shortcuts.ts`): one registry with scopes and chords; the `?` sheet,
  tooltips, the palette and [shortcuts](/docs/shortcuts) all read it.
- **UI:** shadcn/ui on Base UI plus the audiocn registry, themed by tokens only (monochrome, square). See
  [CONTRIBUTING](https://github.com/FindMalek/lodesong/blob/main/CONTRIBUTING.md).

## Sync with other clients

Only standard (Open)Subsonic data on the server: the play queue (hand-off), stars and ratings, playlists and
scrobbles. Any client sees the same. See [sync](/docs/sync).
