# CLAUDE.md - this project

Project instructions for Claude Code.

## Project

A Python + FastAPI + SQLAlchemy 2 + Alembic + pytest + Docker project.

Stack: Python + FastAPI, SQLAlchemy 2 + Alembic, pytest, Docker.

## Commands

- Install deps: `uv sync`
- Dev server: `uv run fastapi dev`
- Lint and format: `uv run ruff check . && uv run ruff format .`
- Tests: `uv run pytest`
- New migration: `uv run alembic revision --autogenerate -m "<change>"`
- Apply migrations: `uv run alembic upgrade head`
- Tests: `uv run pytest -q`
- Local services: `docker compose up -d`

## Project structure

- `app/main.py` creates the app; one `APIRouter` per domain in `app/routers/`.
- Pydantic schemas in `app/schemas/`, business logic in `app/services/`.

## How to work in this repo

- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.

## Python + FastAPI

- Type-hint every function. Use `Annotated[..., Depends(...)]` for dependencies.
- Request and response bodies are Pydantic v2 models; set `response_model` so output is filtered.
- Use `async def` only when the endpoint awaits async I/O. Blocking libraries go in plain `def` endpoints.
- Inject DB sessions, settings and the current user with dependencies, not globals.
- Load settings with `pydantic-settings` from env vars.
- Raise `HTTPException` with a clear `detail` for expected errors.
- Manage dependencies with `uv add <pkg>`; do not hand-edit lock files.

## SQLAlchemy 2 + Alembic

- Use SQLAlchemy 2.0 style: `DeclarativeBase`, `Mapped[...]`, `mapped_column()`, and `select()` statements. No legacy `session.query()`.
- Every schema change gets an Alembic migration; review autogenerated migrations before applying.
- Scope one session per request (via a dependency) and never share sessions across threads.
- Load relationships deliberately with `selectinload` / `joinedload` to avoid N+1 queries.

## pytest

- Tests live in `tests/` named `test_*.py`. Use plain `assert`.
- Share setup with fixtures in `conftest.py`; use `@pytest.mark.parametrize` for input tables.
- Mock external services (HTTP, LLM APIs, payment providers); tests must not hit the network.
- Every bug fix adds a regression test.

## Docker

- Use multi-stage builds and slim, pinned base images.
- Run the app as a non-root user in the final image.
- Keep a `.dockerignore` that excludes `.git`, `node_modules`, `.env` and build output.
- Never bake secrets into images; pass them at runtime.

## Reference docs

- [FastAPI docs](https://fastapi.tiangolo.com)
- [SQLAlchemy docs](https://docs.sqlalchemy.org/en/20/)
- [pytest docs](https://docs.pytest.org)
- [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/)