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).

Quick start (Docker)

cp .env.example .env          # then set a real JWT_SECRET
docker compose up --build     # api on :8000, worker, postgres, redis
curl localhost:8000/health    # {"status":"ok"}
curl localhost:8000/health/ready

Local dev (without Docker)

uv sync                       # install deps (uses managed Python 3.14)
# start Postgres + Redis (e.g. `docker compose up db redis`)
cp .env.example .env
uv run uvicorn app.main:app --reload

Tooling

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

Database migrations (Alembic)

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. External services (ML, AcoustID, MusicBrainz) are optional — the backend degrades gracefully when they are absent.

2.4 KiB Raw Blame History