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