# Repository Guidelines

## Project Structure & Module Organization

This FastAPI backend lives in `cpv3/`. The app entry point is `cpv3/main.py`;
versioned routes are collected in `cpv3/api/v1/router.py`. Feature code lives in
`cpv3/modules/<feature>/` and should stay flat: `models.py`, `schemas.py`,
`repository.py`, `service.py`, and `router.py`. Shared infrastructure is in
`cpv3/infrastructure/`, database setup in `cpv3/db/`, migrations in `alembic/`,
docs in `docs/`, and tests in `tests/unit/` and `tests/integration/`.

## Build, Test, and Development Commands

- `uv sync` installs locked dependencies.
- `uv run uvicorn cpv3.main:app --reload` runs the API on `localhost:8000`.
- `docker compose -f docker-compose.local.yml up --build` starts Postgres, Redis,
  MinIO, the API, and the Dramatiq worker.
- `uv run dramatiq cpv3.modules.tasks.service` starts the worker without Docker.
- `uv run alembic upgrade head` applies database migrations.
- `uv run alembic revision --autogenerate -m "add table"` creates a migration.

## Coding Style & Naming Conventions

Use Python 3.11+ with absolute imports such as
`from cpv3.modules.media.schemas import MediaRead`. Keep Ruff formatting with a
100-character line length: `uv run ruff format cpv3 tests` and
`uv run ruff check cpv3 tests`. Put HTTP concerns in `router.py`, DTOs in
`schemas.py`, business orchestration in `service.py`, and SQLAlchemy queries in
`repository.py`. Pydantic schemas should inherit from `cpv3.common.schemas.Schema`.
Define reusable error strings as module-level `ERROR_...` constants.

## Testing Guidelines

Pytest is configured in `pyproject.toml` with `pytest-asyncio` auto mode. Name test
files `test_*.py`, classes `Test*`, and functions `test_*`. Run all tests with
`uv run pytest`; run a slice with `uv run pytest tests/unit/test_task_service.py`.
Prefer unit tests for service/repository logic and integration tests for endpoint
contracts. Shared async clients, users, storage mocks, and SQLite fixtures live in
`tests/conftest.py`.

## Commit & Pull Request Guidelines

Recent history uses short imperative subjects, often with Conventional Commit
prefixes: `fix: add cors endpoints`, `feat: add swagger auth`, `chore: add pipeline`.
Keep commits focused and mention migrations or config changes in the body. Pull
requests should include a summary, linked issue or task, test results, and notes for
API, migration, Docker, or environment-variable changes.

## Security & Configuration Tips

Runtime settings come from `.env` through `cpv3/infrastructure/settings.py`. Do not
commit real secrets, service keys, or certificates. Local defaults expose Postgres on
`5332`, Redis on `6379`, MinIO on `9000/9001`, and the API on `8000`.

## Agent-Specific Instructions

Use Context7 for current library, SDK, CLI, framework, or cloud-service documentation.
Treat committed project files as source of truth when available, and do not rely on
`.claude/` directory contents.