CLAUDE.md for FastAPI

# CLAUDE.md

Project memory for Claude Code in this FastAPI repository. Read it before editing. Other agents can follow the same rules.

## Stack

This repository is a FastAPI service. Request and response bodies are Pydantic v2 models. Routes stay async and must not block the event loop.

## Layout

- The app package exposes `app`. Routers live beside it and are included explicitly.
- Pydantic models live next to the route that owns them, or in a schemas module if they are shared.
- Settings are read once. Do not call `os.environ` inside a path operation.

## Commands

- Dev server: `uvicorn app.main:app --reload`
- Tests: `pytest`
- Lint: `ruff check .`
- Format: `ruff format .`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Define request and response bodies as Pydantic v2 models, not bare dicts.
- Use `APIRouter` and `Depends` the way the project already does.
- Path operations that talk to the network or a database are `async def`. Do not run blocking I/O directly inside them.
- Return the response model you declared. Do not leak ORM objects that were not configured for it.
- Status codes match the action. Create is 201, a missing row is 404, a bad transition is 409.
- Type hints are mandatory on new functions.

## Testing

Add or update tests when behavior changes.

Test the route with the project's HTTP client (httpx or TestClient). Cover the success path and one rejection.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Raise `HTTPException` with a stable detail for expected failures. Unexpected errors should propagate to the server log.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not call `time.sleep` or synchronous database drivers inside an async route.
- Do not use Pydantic v1 `validator` decorators in new models.
- Do not catch `Exception` and return a 200.
- Do not disable response-model filtering to hide a serialization bug.

## Done when

- The requested behavior works.
- `pytest` passes and `ruff check .` is clean, or you say which tool the repo does not have.
- The diff stays inside the task.
- You list anything you could not run.