main_backend/AGENTS.md

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.