Senko-san
7c920f38f6
1B — domain layer:
- New entities: Album, Playlist, Like, PlayHistoryEntry
- Track entity extended with album_id, genre, year fields
- New protocols: AlbumRepository, PlaylistRepository, LikeRepository, HistoryRepository
- ArtistRepository / TrackRepository protocols extended (list, count, update, get_many, etc.)
- New repos: SqlAlchemyAlbum/Playlist/Like/HistoryRepository
- Artist and track repos updated to match extended protocols
1H — library API:
- Pagination: PagedResponse[T] generic, offset-based, limit default 50 max 200
- Schemas: TrackOut, AlbumOut, ArtistOut, PlaylistOut/Create/Update,
LikeEvent/State, HistoryIn/Out, LibrarySearchResponse
- GET/PATCH/DELETE /tracks with filters, sort, pagination
- GET /albums, /albums/{id}, /albums/{id}/tracks
- GET /artists, /artists/{id}, /artists/{id}/albums, /artists/{id}/tracks
- GET /search/library (ILIKE across tracks/albums/artists)
- Full /playlists CRUD + track add/remove (append-only version bump)
- POST /likes (append-only event log), GET /likes, GET /likes/state
- POST /history (scrobble), GET /history
- deps.py: TrackRepoDep, ArtistRepoDep, AlbumRepoDep, PlaylistRepoDep,
LikeRepoDep, HistoryRepoDep
ruff ✅ mypy ✅ pytest 45/45 ✅
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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):
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)
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
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.