Project started 🍾

2026-06-01 18:47:59 +03:00
commit 4bca90a50e
39 changed files with 2340 additions and 0 deletions
@@ -0,0 +1,13 @@
 .git
 .gitignore
 .venv
 __pycache__/
 *.py[oc]
 .mypy_cache/
 .ruff_cache/
 .pytest_cache/
 .env
 *.md
 tests/
 media/
 data/
@@ -0,0 +1,29 @@
 # Copy to .env and adjust. Never commit real secrets.
 # runtime
 ENVIRONMENT=dev          # dev | test | prod
 LOG_LEVEL=INFO
 LOG_JSON=false           # true in prod
 # database (async driver required)
 DATABASE_URL=postgresql+asyncpg://mcma:mcma@localhost:5432/mcma
 DB_ECHO=false
 # redis (cache + arq broker)
 REDIS_URL=redis://localhost:6379/0
 # auth — GENERATE a strong secret for prod: `openssl rand -hex 32`
 JWT_SECRET=change-me-in-prod
 ACCESS_TOKEN_TTL_SECONDS=900
 REFRESH_TOKEN_TTL_SECONDS=2592000
 # media / storage
 MEDIA_PATH=/data/media
 TRANSCODE_CACHE_PATH=/data/transcode-cache
 MAX_PARALLEL_DOWNLOADS=2
 # external services (all optional — backend degrades gracefully if unset)
 # ML_SERVICE_URL=http://ml:9000
 # ACOUSTID_API_KEY=
 MUSICBRAINZ_USER_AGENT=mcma-backend/0.1.0 ( https://github.com/your/repo )
 # YOUTUBE_COOKIES_PATH=/data/cookies.txt
@@ -0,0 +1,22 @@
 # Python-generated files
 __pycache__/
 *.py[oc]
 build/
 dist/
 wheels/
 *.egg-info
 # Virtual environments
 .venv
 # Tooling caches
 .mypy_cache/
 .ruff_cache/
 .pytest_cache/
 # Secrets & local config
 .env
 # Local data (media, transcode cache, db dumps)
 /data/
 media/
@@ -0,0 +1 @@
 3.14
@@ -0,0 +1,70 @@
 # CLAUDE.md
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 ## What this is
 `mcma-backend` — a self-hosted, **offline-first** music service (FOSS, homelab scale: units–tens of users). Downloads music from external sources (yt-dlp etc.), stores files + metadata, streams to clients, serves a native REST API plus a Subsonic-compatible API. The server is a **sync layer**, not the sole source of truth — clients are expected to work offline, which shapes the data model (timestamps, event-logs) even before sync is built.
 Status: **Phase 1 (MVP)**. Step 1 (skeleton) is done; the data model, auth, sources, enrichment, streaming, and Subsonic layer follow. There is no in-repo plan document — the build order and deferred work live in Claude's project memory.
 ## Commands
 Uses **uv** (managed Python 3.14) for everything.
 ```bash
 uv sync                              # install deps (runtime + dev group)
 uv run uvicorn app.main:app --reload # run API (needs Postgres + Redis up)
 uv run arq app.workers.arq_worker.WorkerSettings  # run background worker
 uv run ruff check .                  # lint
 uv run ruff format .                 # format
 uv run mypy app                      # type-check (strict)
 uv run pytest                        # all tests
 uv run pytest tests/test_health.py::test_liveness_ok   # single test
 uv run alembic revision --autogenerate -m "msg"  # new migration (after model changes)
 uv run alembic upgrade head                       # apply migrations
 docker compose up --build            # full stack: api, worker, db, redis
 ```
 Tests run in-process against the ASGI app (httpx + asgi-lifespan) — no server, no network. They do **not** require a running DB/Redis: dependency-backed checks degrade rather than fail.
 ## Architecture — hexagonal (ports & adapters)
 Dependencies point **inward**. The domain knows nothing about frameworks; outer layers are wired together only at the composition root.
 - `app/domain/` — pure business core: entities, value objects, errors, and **ports** (Protocols). No framework imports (no FastAPI/SQLAlchemy/redis here, ever).
 - `app/application/` — use cases / services. Depend on domain ports, never on concrete adapters.
 - `app/infrastructure/` — driven adapters: ORM models + repositories (`db/`), Redis client (`cache/`), source backends, ML/HTTP clients. All vendor-specific code is confined here.
 - `app/api/` — driving adapter (FastAPI): routers, schemas, `deps.py` (request-scoped wiring / composition root), middleware, error mapping.
 - `app/core/` — cross-cutting: config, logging, security.
 - `app/workers/` — arq background tasks (heavy I/O and CPU work).
 **Composition roots** are `app/main.py` (`create_app`, lifespan) and `app/api/deps.py` (binds concrete adapters to ports per request). When adding a feature: define the port in `domain`, the service in `application`, the adapter in `infrastructure`, and wire it in `deps.py`.
 ### Cross-cutting conventions
 - **Errors:** services raise framework-agnostic exceptions from `app/domain/errors.py`. `app/api/errors.py` is the *only* place that maps domain errors → HTTP status codes. Don't reference HTTP status from domain/application code.
 - **Config:** `app/core/config.py` — `get_settings()` is a cached singleton over pydantic-settings. Everything comes from env (or `.env` in dev); nothing is hardcoded. `database_url` must use the `+asyncpg` driver (validated).
 - **Logging:** `app/core/logging.py` — structlog, console in dev / JSON in prod. A `correlation_id` contextvar is bound per HTTP request (middleware) and should be bound per worker task; it auto-attaches to every log line.
 - **DB sessions:** API uses `SessionDep` (request-scoped, commit-on-success/rollback-on-error). Workers/scripts use `session_scope()` from `app.infrastructure.db`.
 - **Migrations:** Alembic is async and settings-driven — the URL is injected in `alembic/env.py`, never written to `alembic.ini`. Uncomment the models import in `env.py` once ORM models exist so autogenerate sees them.
 - **Health:** `/health` is liveness; `/health/ready` checks db + redis (required) + ml (optional). Every dependency check is wrapped in `asyncio.timeout` — a readiness probe must never hang.
 ## Non-negotiable domain invariants
 These exist for future sync + ML and are easy to violate by accident:
 - **Likes are an append-only event-log, not a boolean.** Current state = the latest event per `(user, track)`. Never update a like row in place.
 - **`track.id` is the stable `content_id`** — a uuid that never changes; it's the basis of client-side caching. Don't regenerate it.
 - **Dedup on both** `(source, source_id)` **and** `acoustid_fingerprint`. Downloads/imports must be idempotent.
 - **Graceful degradation is mandatory.** ML, music sources, MusicBrainz/AcoustID are all optional. One being down must degrade a feature, never crash the system. The ML service is *not* a required dependency — radio must still work (worse) without it.
 - **Never overwrite `metadata_status = manual`** with automatic enrichment.
 - **No heavy work in the request cycle.** ffmpeg, fingerprinting, downloads — all go to arq workers.
 - **Subsonic compatibility is a strategic goal:** the Subsonic API is an adapter over services, not a reimplementation of logic.
 ## Python 3.14 note
 The project targets Python 3.14, which makes annotations lazy by default (PEP 649). `from __future__ import annotations` is therefore intentionally **absent** — do not add it back. All pins (pyproject `requires-python`, ruff `target-version`, mypy `python_version`, Dockerfile, `.python-version`) are on 3.14.
@@ -0,0 +1,34 @@
 # syntax=docker/dockerfile:1
 # Single image serves both `api` and `worker` (different commands in compose).
 FROM python:3.14-slim AS base
 ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy \
    VIRTUAL_ENV=/app/.venv \
    PATH="/app/.venv/bin:$PATH"
 # Runtime tools: ffmpeg (transcode/HLS), fpcalc (Chromaprint fingerprinting).
 RUN apt-get update \
    && apt-get install -y --no-install-recommends ffmpeg libchromaprint-tools \
    && rm -rf /var/lib/apt/lists/*
 COPY --from=ghcr.io/astral-sh/uv:0.4 /uv /uvx /bin/
 WORKDIR /app
 # Dependency layer — cached unless lockfile changes.
 COPY pyproject.toml uv.lock* ./
 RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-install-project --no-dev
 # Project layer.
 COPY . .
 RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev
 EXPOSE 8000
 # Default: API server. Worker overrides command in docker-compose.
 CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
@@ -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.
@@ -0,0 +1,42 @@
 # Alembic configuration. The database URL is injected at runtime from
 # app settings (see alembic/env.py) — do NOT hardcode it here.
 [alembic]
 script_location = alembic
 prepend_sys_path = .
 path_separator = os
 # Use a timestamp + slug for migration filenames.
 file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
 [loggers]
 keys = root,sqlalchemy,alembic
 [handlers]
 keys = console
 [formatters]
 keys = generic
 [logger_root]
 level = WARNING
 handlers = console
 qualname =
 [logger_sqlalchemy]
 level = WARNING
 handlers =
 qualname = sqlalchemy.engine
 [logger_alembic]
 level = INFO
 handlers =
 qualname = alembic
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
 level = NOTSET
 formatter = generic
 [formatter_generic]
 format = %(levelname)-5.5s [%(name)s] %(message)s
 datefmt = %H:%M:%S
@@ -0,0 +1,67 @@
 """Alembic environment — async, settings-driven, model-aware.
 The DB URL comes from app settings (env), never alembic.ini. ``target_metadata``
 points at the ORM ``Base.metadata``; importing ``app.infrastructure.db.models``
 registers every model so autogenerate sees the full schema.
 """
 import asyncio
 from logging.config import fileConfig
 from alembic import context
 from app.core.config import get_settings
 from app.infrastructure.db import Base
 from sqlalchemy.engine import Connection
 from sqlalchemy.ext.asyncio import async_engine_from_config
 # Import side-effect: registers all ORM models on Base.metadata.
 # Uncomment once models exist (plan §11 step 2):
 # import app.infrastructure.db.models
 config = context.config
 if config.config_file_name is not None:
    fileConfig(config.config_file_name)
 config.set_main_option("sqlalchemy.url", get_settings().database_url)
 target_metadata = Base.metadata
 def _run_migrations(connection: Connection) -> None:
    context.configure(
        connection=connection,
        target_metadata=target_metadata,
        compare_type=True,
        compare_server_default=True,
        render_as_batch=False,
    )
    with context.begin_transaction():
        context.run_migrations()
 def run_migrations_offline() -> None:
    context.configure(
        url=config.get_main_option("sqlalchemy.url"),
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
        compare_type=True,
    )
    with context.begin_transaction():
        context.run_migrations()
 async def run_migrations_online() -> None:
    connectable = async_engine_from_config(
        config.get_section(config.config_ini_section, {}),
        prefix="sqlalchemy.",
    )
    async with connectable.connect() as connection:
        await connection.run_sync(_run_migrations)
    await connectable.dispose()
 if context.is_offline_mode():
    run_migrations_offline()
 else:
    asyncio.run(run_migrations_online())
@@ -0,0 +1,28 @@
 """${message}
 Revision ID: ${up_revision}
 Revises: ${down_revision | comma,n}
 Create Date: ${create_date}
 """
 from __future__ import annotations
 from collections.abc import Sequence
 from alembic import op
 import sqlalchemy as sa
 ${imports if imports else ""}
 # revision identifiers, used by Alembic.
 revision: str = ${repr(up_revision)}
 down_revision: str | None = ${repr(down_revision)}
 branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
 depends_on: str | Sequence[str] | None = ${repr(depends_on)}
 def upgrade() -> None:
    ${upgrades if upgrades else "pass"}
 def downgrade() -> None:
    ${downgrades if downgrades else "pass"}
@@ -0,0 +1,14 @@
 """mcma-backend — self-hosted, offline-first music service.
 Hexagonal (ports & adapters) architecture:
 * ``app.domain``         — pure business core: entities, value objects, errors,
                           and *ports* (Protocols). No framework imports.
 * ``app.application``    — use cases / services. Orchestrate domain via ports.
 * ``app.infrastructure`` — driven adapters: ORM models, repositories, db, redis,
                           source backends, ML/HTTP clients.
 * ``app.api``            — driving adapter: FastAPI routers & schemas.
 * ``app.core``           — cross-cutting concerns: config, logging, security.
 """
 __version__ = "0.1.0"
@@ -0,0 +1 @@
 """Driving adapter — FastAPI routers, schemas, dependency wiring."""
@@ -0,0 +1,30 @@
 """Shared FastAPI dependencies — the composition root for request-scoped wiring.
 Concrete adapters are bound to ports here so routers and services stay
 decoupled from infrastructure. Repository/service providers are added in
 later steps as the domain grows.
 """
 from collections.abc import AsyncIterator
 from typing import Annotated
 from fastapi import Depends
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.infrastructure.db import get_sessionmaker
 async def get_session() -> AsyncIterator[AsyncSession]:
    """Request-scoped DB session. Commits on success, rolls back on exception."""
    session = get_sessionmaker()()
    try:
        yield session
        await session.commit()
    except Exception:
        await session.rollback()
        raise
    finally:
        await session.close()
 SessionDep = Annotated[AsyncSession, Depends(get_session)]
@@ -0,0 +1,50 @@
 """Maps domain exceptions to HTTP responses. The only place that knows both."""
 from fastapi import FastAPI, Request, status
 from fastapi.responses import JSONResponse
 from app.core.logging import get_logger
 from app.domain.errors import (
    AlreadyExistsError,
    AuthenticationError,
    ConflictError,
    DependencyUnavailableError,
    DomainError,
    NotFoundError,
    PermissionDeniedError,
    ValidationError,
 )
 log = get_logger(__name__)
 _STATUS_BY_ERROR: dict[type[DomainError], int] = {
    NotFoundError: status.HTTP_404_NOT_FOUND,
    AlreadyExistsError: status.HTTP_409_CONFLICT,
    ConflictError: status.HTTP_409_CONFLICT,
    ValidationError: status.HTTP_422_UNPROCESSABLE_CONTENT,
    AuthenticationError: status.HTTP_401_UNAUTHORIZED,
    PermissionDeniedError: status.HTTP_403_FORBIDDEN,
    DependencyUnavailableError: status.HTTP_503_SERVICE_UNAVAILABLE,
 }
 def _error_body(code: str, message: str) -> dict[str, dict[str, str]]:
    return {"error": {"code": code, "message": message}}
 def register_exception_handlers(app: FastAPI) -> None:
    @app.exception_handler(DomainError)
    async def _handle_domain_error(_request: Request, exc: DomainError) -> JSONResponse:
        http_status = _STATUS_BY_ERROR.get(type(exc), status.HTTP_400_BAD_REQUEST)
        return JSONResponse(
            status_code=http_status,
            content=_error_body(exc.code, exc.message),
        )
    @app.exception_handler(Exception)
    async def _handle_unexpected(_request: Request, exc: Exception) -> JSONResponse:
        log.error("unhandled_exception", exc_info=exc)
        return JSONResponse(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            content=_error_body("internal_error", "An unexpected error occurred."),
        )
@@ -0,0 +1,83 @@
 """Health & readiness endpoints — used by compose healthchecks and the admin UI.
 * ``/health``  — liveness: the process is up. Always 200 if serving.
 * ``/health/ready`` — readiness: checks DB, Redis, and (optionally) ML.
  Returns 503 if a *required* dependency is down. ML is optional — its absence
  degrades, never fails, readiness (graceful degradation, see plan §6.5).
 """
 import asyncio
 from typing import Literal
 from fastapi import APIRouter, Response, status
 from pydantic import BaseModel
 from sqlalchemy import text
 from app.core.config import get_settings
 from app.core.logging import get_logger
 from app.infrastructure.cache import get_redis
 from app.infrastructure.db import get_sessionmaker
 log = get_logger(__name__)
 router = APIRouter(tags=["health"])
 CheckStatus = Literal["ok", "down", "skipped"]
 # A readiness probe must answer fast and never hang — bound every dependency
 # check. A check that exceeds this is reported "down".
 CHECK_TIMEOUT_SECONDS = 2.0
 class HealthResponse(BaseModel):
    status: Literal["ok"] = "ok"
 class ReadinessResponse(BaseModel):
    status: Literal["ready", "degraded"]
    checks: dict[str, CheckStatus]
@router.get("/health", response_model=HealthResponse)
 async def health() -> HealthResponse:
    return HealthResponse()
 async def _check_db() -> CheckStatus:
    try:
        async with asyncio.timeout(CHECK_TIMEOUT_SECONDS):
            async with get_sessionmaker()() as session:
                await session.execute(text("SELECT 1"))
        return "ok"
    except Exception as exc:
        log.warning("healthcheck_db_down", error=str(exc))
        return "down"
 async def _check_redis() -> CheckStatus:
    try:
        async with asyncio.timeout(CHECK_TIMEOUT_SECONDS):
            await get_redis().ping()
        return "ok"
    except Exception as exc:
        log.warning("healthcheck_redis_down", error=str(exc))
        return "down"
 async def _check_ml() -> CheckStatus:
    # Optional dependency. A real client lands in step 12; absence is fine.
    return "skipped" if get_settings().ml_service_url is None else "ok"
@router.get("/health/ready", response_model=ReadinessResponse)
 async def readiness(response: Response) -> ReadinessResponse:
    db, redis, ml = await asyncio.gather(_check_db(), _check_redis(), _check_ml())
    checks: dict[str, CheckStatus] = {"database": db, "redis": redis, "ml": ml}
    required_down = db == "down" or redis == "down"
    if required_down:
        response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
    return ReadinessResponse(
        status="degraded" if required_down else "ready",
        checks=checks,
    )
@@ -0,0 +1,52 @@
 """HTTP middleware: bind a correlation id and log each request."""
 import time
 import uuid
 from starlette.types import ASGIApp, Message, Receive, Scope, Send
 from app.core.logging import correlation_id, get_logger
 log = get_logger("http")
 _HEADER = "x-correlation-id"
 class CorrelationIdMiddleware:
    """Pure-ASGI middleware: reuse inbound ``X-Correlation-Id`` or mint one,
    bind it for downstream logs, echo it back, and log request completion."""
    def __init__(self, app: ASGIApp) -> None:
        self.app = app
    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return
        headers = dict(scope["headers"])
        inbound = headers.get(_HEADER.encode())
        cid = inbound.decode() if inbound else uuid.uuid4().hex
        token = correlation_id.set(cid)
        started = time.perf_counter()
        status_code = 0
        async def send_wrapper(message: Message) -> None:
            nonlocal status_code
            if message["type"] == "http.response.start":
                status_code = message["status"]
                message.setdefault("headers", [])
                message["headers"].append((_HEADER.encode(), cid.encode()))
            await send(message)
        try:
            await self.app(scope, receive, send_wrapper)
        finally:
            log.info(
                "request",
                method=scope["method"],
                path=scope["path"],
                status=status_code,
                duration_ms=round((time.perf_counter() - started) * 1000, 1),
            )
            correlation_id.reset(token)
@@ -0,0 +1,6 @@
 """Application layer — use cases / services.
 Services orchestrate the domain through *ports* (Protocols defined in
 ``app.domain``). They never import concrete adapters directly; adapters are
 injected at the composition root (``app.main`` / ``app.api.deps``).
 """
@@ -0,0 +1,25 @@
 """Management CLI (``mcma``). Admin/seed commands land here in later steps.
 For now it exposes ``mcma version``. ``mcma create-admin`` arrives with auth
 (plan §11 step 3).
 """
 import argparse
 from app import __version__
 def main() -> None:
    parser = argparse.ArgumentParser(prog="mcma", description="mcma-backend management CLI")
    sub = parser.add_subparsers(dest="command")
    sub.add_parser("version", help="Print the backend version")
    args = parser.parse_args()
    if args.command == "version":
        print(__version__)
    else:
        parser.print_help()
 if __name__ == "__main__":
    main()
@@ -0,0 +1 @@
 """Cross-cutting concerns: configuration, logging, security."""
@@ -0,0 +1,74 @@
 """Application settings — single source of truth, sourced from environment.
 Nothing is hardcoded. All knobs come from env vars (or a local ``.env`` during
 development). Access the cached singleton via :func:`get_settings`.
 """
 from functools import lru_cache
 from pathlib import Path
 from typing import Literal
 from pydantic import Field, SecretStr, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
        case_sensitive=False,
    )
    # -- runtime ----------------------------------------------------------
    environment: Literal["dev", "test", "prod"] = "dev"
    log_level: str = "INFO"
    log_json: bool = Field(
        default=False,
        description="Structured JSON logs (enable in prod).",
    )
    # -- database ---------------------------------------------------------
    # Async driver required (asyncpg). Example:
    # postgresql+asyncpg://mcma:mcma@db:5432/mcma
    database_url: str = "postgresql+asyncpg://mcma:mcma@localhost:5432/mcma"
    db_echo: bool = False
    db_pool_size: int = 5
    db_max_overflow: int = 10
    # -- redis (cache + arq broker) --------------------------------------
    redis_url: str = "redis://localhost:6379/0"
    # -- auth -------------------------------------------------------------
    jwt_secret: SecretStr = SecretStr("change-me-in-prod")
    jwt_algorithm: str = "HS256"
    access_token_ttl_seconds: int = 60 * 15  # 15 min
    refresh_token_ttl_seconds: int = 60 * 60 * 24 * 30  # 30 days (offline-first)
    # -- media / storage --------------------------------------------------
    media_path: Path = Path("/data/media")
    transcode_cache_path: Path = Path("/data/transcode-cache")
    max_parallel_downloads: int = 2
    # -- external services (all optional; graceful degradation) ----------
    ml_service_url: str | None = None
    acoustid_api_key: SecretStr | None = None
    musicbrainz_user_agent: str = "mcma-backend/0.1.0 ( https://github.com/your/repo )"
    youtube_cookies_path: Path | None = None
    @field_validator("database_url")
    @classmethod
    def _require_async_driver(cls, v: str) -> str:
        if "+asyncpg" not in v:
            raise ValueError("database_url must use the asyncpg driver: postgresql+asyncpg://")
        return v
    @property
    def is_prod(self) -> bool:
        return self.environment == "prod"
@lru_cache
 def get_settings() -> Settings:
    """Cached settings singleton. Patch the cache in tests via ``get_settings.cache_clear()``."""
    return Settings()
@@ -0,0 +1,52 @@
 """Structured logging via structlog.
 Emits key=value (dev) or JSON (prod) with a per-request/task ``correlation_id``
 bound through a contextvar. Call :func:`configure_logging` once at startup.
 """
 import logging
 from contextvars import ContextVar
 from typing import cast
 import structlog
 from structlog.typing import EventDict, FilteringBoundLogger, Processor, WrappedLogger
 # Bound by middleware (HTTP) and worker entrypoints (tasks) so every log line
 # downstream carries the same id without explicit passing.
 correlation_id: ContextVar[str | None] = ContextVar("correlation_id", default=None)
 def _add_correlation_id(
    _logger: WrappedLogger, _method: str, event_dict: EventDict
 ) -> EventDict:
    cid = correlation_id.get()
    if cid is not None:
        event_dict["correlation_id"] = cid
    return event_dict
 def configure_logging(*, level: str = "INFO", json: bool = False) -> None:
    shared: list[Processor] = [
        structlog.contextvars.merge_contextvars,
        _add_correlation_id,
        structlog.processors.add_log_level,
        structlog.processors.TimeStamper(fmt="iso", utc=True),
        structlog.processors.StackInfoRenderer(),
        structlog.processors.format_exc_info,
    ]
    renderer = (
        structlog.processors.JSONRenderer() if json else structlog.dev.ConsoleRenderer(colors=True)
    )
    structlog.configure(
        processors=[*shared, renderer],
        wrapper_class=structlog.make_filtering_bound_logger(logging.getLevelName(level.upper())),
        logger_factory=structlog.PrintLoggerFactory(),
        cache_logger_on_first_use=True,
    )
    # Route stdlib logging (uvicorn, sqlalchemy) through structlog formatting.
    logging.basicConfig(level=level.upper(), format="%(message)s")
 def get_logger(name: str | None = None) -> FilteringBoundLogger:
    return cast(FilteringBoundLogger, structlog.get_logger(name))
@@ -0,0 +1,5 @@
 """Pure business core — entities, value objects, errors, and ports (Protocols).
 This package MUST NOT import frameworks (FastAPI, SQLAlchemy, redis, …).
 Adapters depend on the domain; the domain depends on nothing but stdlib.
 """
@@ -0,0 +1,63 @@
 """Domain exception hierarchy — framework-agnostic.
 Services raise these; the API layer maps them to HTTP responses
 (see ``app.api.errors``). The domain never references HTTP status codes.
 """
 class DomainError(Exception):
    """Base for all expected, business-meaningful failures.
    ``code`` is a stable, machine-readable identifier returned to clients.
    """
    code: str = "domain_error"
    def __init__(self, message: str | None = None) -> None:
        super().__init__(message or self.__class__.__doc__ or self.code)
        self.message = str(self)
 class NotFoundError(DomainError):
    """Requested resource does not exist."""
    code = "not_found"
 class AlreadyExistsError(DomainError):
    """Resource conflicts with an existing one (e.g. duplicate)."""
    code = "already_exists"
 class ConflictError(DomainError):
    """Operation conflicts with current state (e.g. stale version on write)."""
    code = "conflict"
 class ValidationError(DomainError):
    """Input is well-formed but violates a business rule."""
    code = "validation_error"
 class AuthenticationError(DomainError):
    """Caller could not be authenticated."""
    code = "authentication_error"
 class PermissionDeniedError(DomainError):
    """Caller authenticated but not authorized for this action."""
    code = "permission_denied"
 class DependencyUnavailableError(DomainError):
    """An external dependency (source, ML, MusicBrainz) is unavailable.
    Callers should degrade gracefully rather than propagate as a hard 500.
    """
    code = "dependency_unavailable"
@@ -0,0 +1,6 @@
 """Driven adapters — concrete implementations of domain ports.
 ORM models, repositories, the async DB engine, the Redis client, source
 backends, and external HTTP clients live here. Everything framework- and
 vendor-specific is confined to this package.
 """
@@ -0,0 +1,5 @@
 """Redis adapter: shared connection pool for cache and arq broker."""
 from app.infrastructure.cache.redis import close_redis, get_redis
 __all__ = ["close_redis", "get_redis"]
@@ -0,0 +1,26 @@
 """Redis client provider — a single shared async connection pool."""
 from redis.asyncio import Redis
 from app.core.config import get_settings
 _client: Redis | None = None
 def get_redis() -> Redis:
    """Return the process-wide Redis client (created on first use)."""
    global _client
    if _client is None:
        _client = Redis.from_url(
            str(get_settings().redis_url),
            encoding="utf-8",
            decode_responses=True,
        )
    return _client
 async def close_redis() -> None:
    global _client
    if _client is not None:
        await _client.aclose()
        _client = None
@@ -0,0 +1,17 @@
 """Database adapter: declarative base, async engine, session factory."""
 from app.infrastructure.db.base import Base
 from app.infrastructure.db.engine import (
    dispose_engine,
    get_engine,
    get_sessionmaker,
    session_scope,
 )
 __all__ = [
    "Base",
    "dispose_engine",
    "get_engine",
    "get_sessionmaker",
    "session_scope",
 ]
@@ -0,0 +1,22 @@
 """Declarative base with a fixed naming convention.
 The naming convention makes Alembic autogenerate deterministic, named
 constraints — essential for clean, reversible migrations.
 """
 from sqlalchemy import MetaData
 from sqlalchemy.orm import DeclarativeBase
 NAMING_CONVENTION = {
    "ix": "ix_%(column_0_label)s",
    "uq": "uq_%(table_name)s_%(column_0_name)s",
    "ck": "ck_%(table_name)s_%(constraint_name)s",
    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
    "pk": "pk_%(table_name)s",
 }
 class Base(DeclarativeBase):
    """Base for all ORM models. Import models so Alembic sees their metadata."""
    metadata = MetaData(naming_convention=NAMING_CONVENTION)
@@ -0,0 +1,61 @@
 """Async engine + session factory, created lazily from settings.
 The engine is process-global and cached. The API binds a session per request
 (see ``app.api.deps``); workers and scripts use :func:`session_scope`.
 """
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from functools import lru_cache
 from sqlalchemy.ext.asyncio import (
    AsyncEngine,
    AsyncSession,
    async_sessionmaker,
    create_async_engine,
 )
 from app.core.config import get_settings
@lru_cache
 def get_engine() -> AsyncEngine:
    settings = get_settings()
    return create_async_engine(
        settings.database_url,
        echo=settings.db_echo,
        pool_size=settings.db_pool_size,
        max_overflow=settings.db_max_overflow,
        pool_pre_ping=True,  # survive Postgres restarts / idle drops
    )
@lru_cache
 def get_sessionmaker() -> async_sessionmaker[AsyncSession]:
    return async_sessionmaker(
        bind=get_engine(),
        expire_on_commit=False,
        autoflush=False,
    )
@asynccontextmanager
 async def session_scope() -> AsyncIterator[AsyncSession]:
    """Transactional session for workers/scripts: commit on success, rollback on error."""
    session = get_sessionmaker()()
    try:
        yield session
        await session.commit()
    except Exception:
        await session.rollback()
        raise
    finally:
        await session.close()
 async def dispose_engine() -> None:
    """Dispose the pooled engine on shutdown. Safe to call if never initialized."""
    if get_engine.cache_info().currsize:
        await get_engine().dispose()
        get_engine.cache_clear()
        get_sessionmaker.cache_clear()
@@ -0,0 +1,51 @@
 """FastAPI composition root: wiring, lifespan, middleware, routers."""
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from app.api.errors import register_exception_handlers
 from app.api.health import router as health_router
 from app.api.middleware import CorrelationIdMiddleware
 from app.core.config import get_settings
 from app.core.logging import configure_logging, get_logger
 from app.infrastructure.cache import close_redis
 from app.infrastructure.db import dispose_engine
 log = get_logger(__name__)
@asynccontextmanager
 async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
    settings = get_settings()
    log.info("startup", environment=settings.environment)
    yield
    log.info("shutdown")
    await dispose_engine()
    await close_redis()
 def create_app() -> FastAPI:
    settings = get_settings()
    configure_logging(level=settings.log_level, json=settings.log_json)
    app = FastAPI(
        title="mcma-backend",
        version="0.1.0",
        summary="Self-hosted, offline-first music service.",
        lifespan=lifespan,
    )
    app.add_middleware(CorrelationIdMiddleware)
    register_exception_handlers(app)
    app.include_router(health_router)
    # Versioned API routers (auth, library, …) are mounted in later steps:
    #   app.include_router(api_v1_router, prefix="/api/v1")
    #   app.include_router(subsonic_router, prefix="/rest")
    return app
 app = create_app()
@@ -0,0 +1,4 @@
 """arq worker — background tasks (downloads, enrichment, transcoding).
 CPU/IO-heavy work runs here, never in the request cycle (plan §2.6).
 """
@@ -0,0 +1,32 @@
 """arq worker settings — the queue runtime. Task functions register here.
 Run with: ``arq app.workers.arq_worker.WorkerSettings``.
 Tasks (download, enrich, transcode) are appended to ``functions`` in later steps.
 """
 from typing import Any, ClassVar
 from arq.connections import RedisSettings
 from app.core.config import get_settings
 from app.core.logging import configure_logging, get_logger
 log = get_logger("worker")
 async def startup(_ctx: dict[str, Any]) -> None:
    settings = get_settings()
    configure_logging(level=settings.log_level, json=settings.log_json)
    log.info("worker_startup", environment=settings.environment)
 async def shutdown(_ctx: dict[str, Any]) -> None:
    log.info("worker_shutdown")
 class WorkerSettings:
    functions: ClassVar[list[Any]] = []  # populated as tasks are implemented
    on_startup = startup
    on_shutdown = shutdown
    max_jobs = get_settings().max_parallel_downloads
    redis_settings = RedisSettings.from_dsn(str(get_settings().redis_url))
@@ -0,0 +1,97 @@
 # Dev/prod stack. Worker reuses the api image with a different command.
 # The ML service is intentionally a commented placeholder — it is optional
 # (graceful degradation) and lands in a later phase.
 services:
  api:
    build: .
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000
    env_file: .env
    environment:
      DATABASE_URL: postgresql+asyncpg://mcma:mcma@db:5432/mcma
      REDIS_URL: redis://redis:6379/0
    ports:
      - "8000:8000"
    volumes:
      - media:/data/media
      - transcode_cache:/data/transcode-cache
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/health').status==200 else 1)"]
      interval: 30s
      timeout: 5s
      retries: 3
    restart: unless-stopped
  worker:
    build: .
    command: arq app.workers.arq_worker.WorkerSettings
    env_file: .env
    environment:
      DATABASE_URL: postgresql+asyncpg://mcma:mcma@db:5432/mcma
      REDIS_URL: redis://redis:6379/0
    volumes:
      - media:/data/media
      - transcode_cache:/data/transcode-cache
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: mcma
      POSTGRES_PASSWORD: mcma
      POSTGRES_DB: mcma
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mcma"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
  redis:
    image: redis:7-alpine
    command: redis-server --save 60 1 --loglevel warning
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
  # Reverse proxy + auto-HTTPS (enable on prod with a real domain).
  # caddy:
  #   image: caddy:2-alpine
  #   ports: ["80:80", "443:443"]
  #   volumes:
  #     - ./Caddyfile:/etc/caddy/Caddyfile
  #     - caddy_data:/data
  #   depends_on: [api]
  #   restart: unless-stopped
  # ML recommendation service — OPTIONAL, added in a later phase.
  # The backend must run fully without it (set ML_SERVICE_URL to enable).
  # ml:
  #   image: mcma-ml:latest
  #   environment:
  #     MODEL_PATH: /models
  #   restart: unless-stopped
 volumes:
  pgdata:
  redisdata:
  media:
  transcode_cache:
  # caddy_data:
@@ -0,0 +1,87 @@
 [project]
 name = "mcma-backend"
 version = "0.1.0"
 description = "Self-hosted, offline-first music service — backend (hexagonal architecture)"
 readme = "README.md"
 requires-python = ">=3.14"
 dependencies = [
    # web
    "fastapi>=0.115",
    "uvicorn[standard]>=0.32",
    "python-multipart>=0.0.12",
    # data
    "sqlalchemy[asyncio]>=2.0.36",
    "asyncpg>=0.30",
    "alembic>=1.14",
    # config / validation
    "pydantic>=2.10",
    "pydantic-settings>=2.6",
    # cache / queue
    "redis>=5.2",
    "arq>=0.26",
    # auth
    "pyjwt>=2.10",
    "pwdlib[argon2]>=0.2.1",
    # outbound http (ML client, MusicBrainz, AcoustID)
    "httpx>=0.28",
    # logging
    "structlog>=24.4",
 ]
 [project.scripts]
 mcma = "app.cli:main"
 [dependency-groups]
 dev = [
    "pytest>=8.3",
    "pytest-asyncio>=0.24",
    "ruff>=0.8",
    "mypy>=1.13",
    "asgi-lifespan>=2.1",
 ]
 [tool.uv]
 package = true
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["app"]
 # ---------------------------------------------------------------------------
 # Tooling
 # ---------------------------------------------------------------------------
 [tool.ruff]
 target-version = "py314"
 line-length = 100
 src = ["app", "tests"]
 [tool.ruff.lint]
 select = [
    "E", "F", "W",   # pycodestyle / pyflakes
    "I",             # isort
    "N",             # pep8-naming
    "UP",            # pyupgrade
    "B",             # bugbear
    "ASYNC",         # async pitfalls
    "RUF",
 ]
 ignore = ["B008"]  # FastAPI Depends() in defaults is idiomatic
 [tool.mypy]
 python_version = "3.14"
 strict = true
 plugins = ["pydantic.mypy"]
 warn_unused_ignores = true
 disallow_untyped_defs = true
 [[tool.mypy.overrides]]
 module = ["arq.*"]
 ignore_missing_imports = true
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
 addopts = "-ra"
@@ -0,0 +1,28 @@
 """Shared test fixtures.
 The ASGI app is driven in-process via httpx + asgi-lifespan (no network, no
 running server). DB/Redis-backed integration fixtures arrive with the data
 layer (plan §11 step 2).
 """
 import os
 from collections.abc import AsyncIterator
 import pytest
 from asgi_lifespan import LifespanManager
 from httpx import ASGITransport, AsyncClient
 # Force a test-safe environment before settings load.
 os.environ.setdefault("ENVIRONMENT", "test")
 os.environ.setdefault("JWT_SECRET", "test-secret")
@pytest.fixture
 async def client() -> AsyncIterator[AsyncClient]:
    from app.main import create_app
    app = create_app()
    async with LifespanManager(app):
        transport = ASGITransport(app=app)
        async with AsyncClient(transport=transport, base_url="http://test") as ac:
            yield ac
@@ -0,0 +1,22 @@
 """Smoke tests for the health endpoints."""
 from httpx import AsyncClient
 async def test_liveness_ok(client: AsyncClient) -> None:
    resp = await client.get("/health")
    assert resp.status_code == 200
    assert resp.json() == {"status": "ok"}
 async def test_correlation_id_echoed(client: AsyncClient) -> None:
    resp = await client.get("/health", headers={"X-Correlation-Id": "abc123"})
    assert resp.headers.get("x-correlation-id") == "abc123"
 async def test_readiness_reports_checks(client: AsyncClient) -> None:
    # No DB/Redis running in unit env → degraded, but the contract holds.
    resp = await client.get("/health/ready")
    body = resp.json()
    assert set(body["checks"]) == {"database", "redis", "ml"}
    assert body["status"] in {"ready", "degraded"}
		`@@ -0,0 +1 @@`
							`"""Driving adapter — FastAPI routers, schemas, dependency wiring."""`
		`@@ -0,0 +1 @@`
							`"""Cross-cutting concerns: configuration, logging, security."""`