# CLAUDE.md

## Project Context
Python FastAPI application with SQLAlchemy ORM, Pydantic v2, and PostgreSQL.

## Code Style
- Use type hints everywhere
- Pydantic v2 models for all request/response schemas
- SQLAlchemy 2.0 style with async sessions
- Use dependency injection for database sessions

## API Conventions
- RESTful routes under /api/v1/
- Return proper HTTP status codes (201 for create, 204 for delete)
- Use FastAPI's HTTPException for errors
- Paginate list endpoints with limit/offset

## Testing
- pytest with pytest-asyncio
- Use httpx.AsyncClient for API tests
- Factory Boy for test fixtures
- Run: pytest --cov=app tests/

## Database
- Alembic for migrations: alembic upgrade head
- Never raw SQL — always use SQLAlchemy ORM
- All queries must be async

## Git
- Conventional commits: feat:, fix:, chore:
- Run ruff check before committing