Daniil
60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
# 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.
|