69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```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.
|