# FablePool Music Server — Design Specification Package (Milestone 1)

**Project codename:** `fablepool-music` (working title; final name TBD)
**Milestone:** #1 — Architecture & Design Specification
**Status of this package:** Normative. This document set is the contract for all later milestones. Any deviation in implementation milestones requires an explicit, recorded design-change note.

## What this project is

An open-source, self-hostable music streaming server in the spirit of
[Navidrome](https://www.navidrome.org/), with three differentiators:

1. **Remote-first storage.** Music libraries live directly on **S3-compatible
   object storage** or **WebDAV** servers. No requirement to mount or sync the
   library to local disk. The server streams (and range-requests) directly from
   the remote backend, with a local cache layer.
2. **First-class Chromecast support** — a custom Cast receiver application plus
   sender integration in both the web UI and the Android app.
3. **A built-in recommendation engine** that auto-queues the next track based
   on the current track and the user's last *N* played tracks, where *N* is
   user-configurable.

The server exposes both a **native REST API** and a **Subsonic-compatible API**
so the large ecosystem of existing Subsonic clients (DSub, Symfonium, Sublime
Music, play:Sub, …) works out of the box.

## Contents of this design package

| File | Contents |
|---|---|
| `docs/00-overview.md` | Goals, non-goals, glossary, technology selections and rationale |
| `docs/01-architecture.md` | System architecture, component responsibilities, deployment topologies, Mermaid diagrams |
| `docs/02-data-model.md` | Full relational data model: entities, DDL (PostgreSQL + SQLite), indexes, integrity rules, ER diagrams |
| `docs/03-storage-abstraction.md` | The `StorageDriver` abstraction; S3 driver (range requests, presigned URLs, listing pagination); WebDAV driver (PROPFIND traversal, partial GET); scanner integration |
| `docs/04-caching-and-transcoding.md` | Cache tiers (metadata, artwork, segment, transcode), eviction, cache keys, transcoding pipeline (ffmpeg), on-the-fly vs. ahead-of-time policy |
| `docs/05-auth-and-security.md` | Auth model: sessions, API keys, Subsonic token auth, Cast device auth, password storage, threat model |
| `docs/06-chromecast.md` | Receiver application design, sender flow (web + Android), media channel message schema, queueing, auth handoff |
| `docs/07-recommendation-engine.md` | Configurable last-N window, feature extraction pipeline, scoring function, candidate generation, cold start, API surface |
| `docs/08-android-app.md` | Android app architecture (sender + standalone player), offline behaviour, module layout |
| `api/openapi.yaml` | OpenAPI 3.0 specification for the native REST API **and** the Subsonic-compatible endpoints |
| `docs/09-milestone-map.md` | Mapping from this design to future implementation milestones, with acceptance criteria |

## How to read this package

- Start with `docs/00-overview.md` and `docs/01-architecture.md`.
- `api/openapi.yaml` is machine-readable; render it with any OpenAPI viewer
  (e.g. `npx @redocly/cli preview-docs api/openapi.yaml` or Swagger UI). It
  validates against OpenAPI 3.0.3.
- All diagrams are Mermaid and render natively on GitHub/GitLab, or with
  `npx @mermaid-js/mermaid-cli`.

## Normative language

The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY**
in these documents are to be interpreted as described in RFC 2119. Anything
marked *non-normative* is rationale or example only.

## License

This design package, and the project it specifies, are licensed under the
**GNU AGPLv3** (matching Navidrome's license family and keeping hosted forks
open). A `LICENSE` file will be added when the code repository is initialised
in the first implementation milestone.