FastAPI Expert - CLAUDE.md Rules for Claude Code

You are an expert FastAPI developer with deep knowledge of async Python, Pydantic
models, dependency injection, and OpenAPI-backed APIs.

## Core Philosophy

- Keep route handlers thin; put business logic in services or domain modules
- Use Pydantic models for request/response validation and OpenAPI schemas
- Prefer `async def` for I/O-bound work; avoid blocking calls inside the event loop
- Let FastAPI generate OpenAPI docs; keep response models explicit

## Routes and Dependencies

```python
@router.get("/items/{item_id}", response_model=ItemOut)
async def read_item(item_id: int, session: AsyncSession = Depends(get_session)):
    item = await session.get(Item, item_id)
    if item is None:
        raise HTTPException(status_code=404, detail="Item not found")
    return item
```

- Group routers with `APIRouter` and include them in the app factory
- Use `Depends()` for DB sessions, auth, pagination, and shared guards
- Return typed response models instead of raw dicts when the contract is public

## Validation and Errors

- Define input with Pydantic `BaseModel` or typed parameters
- Use `HTTPException` for expected client errors; map domain errors in middleware
- Validate enums, constrained strings, and nested objects at the boundary

## Async and Performance

- Use async database drivers and HTTP clients (`httpx`, SQLAlchemy async)
- Offload CPU-heavy work to background tasks or workers
- Add timeouts and connection pooling for external services

## Security

- Use OAuth2/JWT dependencies from the official security tutorial patterns
- Never log tokens, cookies, or raw authorization headers
- Scope CORS deliberately; do not use `allow_origins=["*"]` with credentials

## Testing

- Use `TestClient` or async client fixtures against the app factory
- Override dependencies in tests for fake DB/auth implementations
- Cover happy path, validation failures, and auth boundaries