CLAUDE.md — Python + FastAPI + SQLAlchemy

# CLAUDE.md

## Project Overview
{{project_name}} — {{one-line description}}

## Tech Stack
- Language: Python 3.11+
- Framework: FastAPI
- ORM: SQLAlchemy 2.0 (async)
- Database: PostgreSQL
- Migrations: Alembic
- Testing: pytest + pytest-asyncio
- Linting: ruff

## Commands
```bash
uv run uvicorn app.main:app --reload   # Dev server
uv run pytest                           # Run tests
uv run ruff check .                     # Lint
uv run alembic upgrade head             # Apply migrations
uv run alembic revision --autogenerate -m "description"  # New migration
```

## Directory Structure
```
app/
├── main.py           # FastAPI app + middleware
├── api/
│   └── v1/           # Versioned route handlers
├── models/           # SQLAlchemy models
├── schemas/          # Pydantic request/response schemas
├── services/         # Business logic
├── repositories/     # Database queries
└── core/
    ├── config.py     # Settings via pydantic-settings
    ├── database.py   # Async engine + session
    └── security.py   # Auth utilities
```

## Conventions
- Type hints on all function signatures
- Async by default for all DB operations
- Use dependency injection via FastAPI Depends()
- Pydantic models for all API input/output
- Never use raw SQL strings — use SQLAlchemy query builder
- snake_case for everything (files, functions, variables)