User-facing references and per-feature deep dives. The top-level README keeps the install / quick-start path short — anything substantive about how a feature actually works lives here.
| Doc | Scope |
|---|---|
| Playback engine | Decoder pipeline, crossfade DSP, ReplayGain, output device selection, OS media controls, persistent queue, A-B repeat |
| Library | Folder scanning + management (add / watch / remove), filesystem watcher, drag-and-drop import, duplicate detection, on-demand audio analysis, multi-artist split, ratings, A-Z navigator |
| Playlists | User playlists CRUD, M3U import/export, likes, recently-played |
| Smart playlists | Daily Mix auto-generation + user-defined rule editor: algorithm, cover compositor, regen flow |
| Integrations | Deezer / Last.fm / LRCLIB clients, metadata cache, scrobble worker, similar-artists discovery, in-app lyrics editor |
| DLNA / UPnP server | Built-in MediaServer: SSDP discovery, ContentDirectory Browse, Range streaming to LAN amplifiers |
| UI & UX | Layout, panels, mini-player widget, tray, statistics, dark mode, i18n, profiles, onboarding, auto-updater |
| Doc | Scope |
|---|---|
| Audio architecture | 3-thread lock-free pipeline, ring buffer sizing, callback constraints |
| Database & paths | app.db vs per-profile data.db, on-disk layout, migration policy |
Long-form design documents that lock in cross-cutting architectural decisions before implementation. New RFCs live under rfcs/ and are numbered sequentially.
| RFC | Status | Scope |
|---|---|---|
| RFC-001 — WaveFlow Server | Accepted | Server stack, web app stack, auth boundary, sync protocol, streaming, Phase 1 delivery plan |
| RFC-002 — Plugin SDK | Draft | WASM Component Model plugins for sources / metadata / UI, sideload distribution, desktop ↔ server parity |
CONTRIBUTING.md and RELEASING.md cover the contribution and release flows respectively. upstream-blockers.md tracks Tauri-ecosystem issues that affect WaveFlow and the policy for handling them. Anything project-wide that should always be loaded into Claude Code's context lives in CLAUDE.md at the repo root.