Project started 🍾

README.md

@@ -0,0 +1,68 @@
+# 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.