CLAUDE.md for FastAPI

A CLAUDE.md encoding the async-everywhere rule, layering direction, and the Alembic autogenerate review habit.

# CLAUDE.md - Atlas API (FastAPI)

## Commands
```bash
uv run uvicorn app.main:app --reload             # dev on :8000
uv run pytest -x                                 # stop at first failure
uv run pytest tests/test_orders.py::test_create  # single test
uv run ruff check . && uv run mypy app           # lint + types, both gate CI
uv run alembic revision --autogenerate -m "msg"  # new migration - review the diff
```

## Architecture
- Layering: `app/api` (routers) → `app/services` (logic + DB) → `app/models`.
  Routers stay thin; services own transactions; models never import upward.
- Pydantic schemas in `app/schemas/` are the API contract - ORM models never
  cross the HTTP boundary.
- Auth: `CurrentUser` dependency from `app/core/security.py`; use it, don't
  parse Authorization headers in routers.

## Conventions
- Everything async: `async def`, `AsyncSession`, `httpx` for outbound calls.
  Blocking IO in a handler will pass locally and stall under load.
- New endpoints follow `app/api/orders.py` as the reference implementation.
- Service functions take the session as their first argument; they never create it.

## Workflow
- Schema change: edit the model, autogenerate a revision, then hand-check the
  migration for missed server defaults before applying.
- Failing CI on mypy usually means a missing return type on a service function.

## Do not
- Do not return ORM objects from routes; map to a schema.
- Do not add module-level singletons; use dependencies so tests can override them.
- Do not write raw SQL in services when the ORM expresses it; if raw SQL is
  unavoidable, put it in the model layer with a comment naming the reason.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.