Install this CLAUDE.md template.
Name: Python API Template
Save to: ./CLAUDE.md in the current project

---
# CLAUDE.md — Python FastAPI Service

## Project overview
<!-- One-sentence description of this API -->

## Tech stack
- **Framework**: FastAPI
- **Language**: Python 3.12+
- **ORM**: SQLAlchemy 2.x (async, using `asyncpg`)
- **Migrations**: Alembic
- **Schemas**: Pydantic v2
- **Tests**: pytest + httpx (async)
- **Package manager**: uv

## Development commands
```bash
uv run uvicorn app.main:app --reload   # dev server on :8000
uv run pytest                          # run test suite
uv run alembic upgrade head            # apply migrations
uv run alembic revision --autogenerate -m "<name>"  # new migration
uv run ruff check . && uv run ruff format .         # lint + format
```

## Project structure
```
app/
  main.py            # FastAPI app factory & lifespan
  api/
    v1/              # versioned routers
  models/            # SQLAlchemy ORM models
  schemas/           # Pydantic request/response schemas
  services/          # business logic (no DB access in routers)
  db/
    session.py       # async session factory
    base.py          # Base model class
alembic/             # migration files
tests/               # pytest tests
```

## Coding conventions
- All route handlers are **async**
- Routers only call service functions — no DB queries in routers
- Services receive a `db: AsyncSession` dependency, not a global
- Pydantic schemas are in `schemas/`, SQLAlchemy models in `models/`
- Use `from __future__ import annotations` in all model files
- HTTP errors: raise `HTTPException(status_code=..., detail=...)`
- Never commit secrets; use `python-dotenv` + `.env` locally

## Environment variables
```
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/dbname
SECRET_KEY=
DEBUG=true
```

## Testing approach
- Each test gets a fresh in-memory SQLite DB (via `pytest-anyio` fixtures)
- Use `httpx.AsyncClient` with `app` as transport — no live server needed
- Factory helpers live in `tests/factories.py`
- Aim for 80%+ coverage; CI will fail below that threshold