# mcma-backend

Self-hosted, **offline-first** music service — backend. Searches/downloads music
from external sources, stores files + metadata, streams to clients, and serves a
native REST API plus a Subsonic-compatible API.

> Status: **Phase 1 (core/MVP)** — project skeleton in place. See the
> implementation plan for the full roadmap.

## Architecture — hexagonal (ports & adapters)

```
app/
├── domain/          pure core: entities, value objects, errors, ports (Protocols)
├── application/     use cases / services — orchestrate domain via ports
├── infrastructure/  driven adapters: ORM, repositories, db, redis, sources, ML client
│   ├── db/          declarative base, async engine, session factory
│   └── cache/       redis client
├── api/             driving adapter: FastAPI routers, schemas, deps, middleware
├── workers/         arq background tasks (download, enrich, transcode)
└── core/            cross-cutting: config, logging, security
```

**Rule:** dependencies point inward. `domain` imports nothing framework-specific;
`application` depends on domain ports; `infrastructure`/`api` are the outer ring
and are wired together at the composition root (`app/main.py`, `app/api/deps.py`).

## Build (Docker)

This repo ships only its own `Dockerfile` — the image runs anywhere and gets
every peer (Postgres, Redis, media path) from env. It carries **no**
orchestration. Full-stack wiring lives in the workspace compose one level up
(`../docker-compose.yml`, alongside `mcma-webui`):

```bash
docker build -t mcma-backend .                  # build just this service
# or, from the workspace root, the whole stack:
docker compose --profile app up --build         # db, redis, api, worker, webui
```

## Local dev (without Docker)

```bash
uv sync                       # install deps (uses managed Python 3.14)
# start backing services from the workspace root: `docker compose up -d` (db + redis)
cp .env.example .env          # then set a real JWT_SECRET
uv run uvicorn app.main:app --reload
```

## Tooling

```bash
uv run ruff check .           # lint
uv run ruff format .          # format
uv run mypy app               # type-check (strict)
uv run pytest                 # tests
```

## Database migrations (Alembic)

```bash
uv run alembic revision --autogenerate -m "message"   # after model changes
uv run alembic upgrade head                            # apply
```

The DB URL is injected from app settings — never hardcoded in `alembic.ini`.

## Configuration

All settings come from environment variables (or `.env` in dev). See
[`.env.example`](.env.example). External services (ML, AcoustID, MusicBrainz)
are **optional** — the backend degrades gracefully when they are absent.

## Sources & importing music

Music enters the library through **source backends** (`app/infrastructure/sources`),
selected via a registry. The first backend is **`local`** — it indexes a mounted
folder, copying each audio file into managed storage and creating a track
(`metadata_status=pending`; real metadata is filled later by enrichment).

```bash
# point the instance at an existing library (mount read-only in compose)
LOCAL_MEDIA_IMPORT_PATH=/import

GET  /api/v1/sources                 # list configured sources + availability
POST /api/v1/sources/local/scan      # admin: enqueue an import (runs in the worker)
GET  /api/v1/sources/local/health    # availability check
```

Scanning is a background job (arq worker) — the endpoint only enqueues it; the
walk + file copies never run in the request cycle. Re-scans are idempotent
(dedup on `(source, source_id)`, where `source_id` is the path within the root).

## Subsonic API (`/rest`)

A Subsonic-compatible API is mounted at `/rest`, so standard clients (Symfonium,
DSub, play:Sub, …) can browse the library and stream. It is a thin adapter over
the native services — it adds no business logic of its own.

**HTTPS is mandatory.** Subsonic authentication puts the credential in the URL
(`t=md5(password+salt)&s=…`, or the legacy `p=`), so `/rest` must only ever be
exposed behind TLS (terminate at the reverse proxy). Never serve it over plain
HTTP.

### App-passwords

Subsonic auth needs a recoverable secret, but login passwords are stored as a
one-way argon2 hash. So Subsonic clients authenticate against a separate,
per-user **app-password** — high-entropy, random, and encrypted at rest with a
key derived from `SUBSONIC_SECRET_KEY` (set this to a strong random string in
prod; rotating it invalidates all stored app-passwords).

Self-service lifecycle (native API, needs a normal JWT login):

```bash
GET  /api/v1/users/me/subsonic-password   # reveal (generated lazily on first read)
POST /api/v1/users/me/subsonic-password   # rotate
# admin, for any user:
POST /api/v1/admin/users/{user_id}/subsonic-password
```

Point the client at the instance URL, use your **username** + the revealed
**app-password** (not your login password).

> **Cover art** (`getCoverArt`) currently returns a placeholder — the cover
> pipeline (`/api/v1/.../cover` endpoints) is not implemented yet.
