AGENTS.md for FastAPI + async SQLAlchemy

An AGENTS.md for a typed, fully-async FastAPI service: uv commands, router/service/model layering, and migration review rules.

# Atlas API (FastAPI)

## Project Overview
FastAPI service on Python 3.12: Pydantic v2, async SQLAlchemy 2.0 + Postgres,
Alembic migrations, uv for dependency management. OpenAPI docs served at /docs.

## Setup & Commands
```bash
uv sync                                          # install from uv.lock
uv run uvicorn app.main:app --reload             # dev server on :8000
uv run pytest                                    # test suite
uv run pytest tests/test_orders.py::test_create  # single test
uv run ruff check . && uv run ruff format --check .
uv run mypy app                                  # strict mode, gates CI
uv run alembic upgrade head                      # apply migrations
```

## Structure
- `app/api/` - routers, one module per resource; thin, no business logic
- `app/services/` - business logic; the only layer that opens a DB session
- `app/models/` - SQLAlchemy models; `app/schemas/` - Pydantic request/response
- `tests/` - mirrors `app/`; shared fixtures in `tests/conftest.py`

## Code Style
- Type hints everywhere; mypy strict is a CI gate.
- Request/response bodies are Pydantic schemas - never return ORM models directly.
- Wire dependencies with `Depends()` (db session, auth, pagination); no
  module-level state.
- Async end to end: `async def` routes, `AsyncSession`, no blocking IO in handlers.

## Testing
- Tests drive the app through `httpx.AsyncClient` against a transactional test DB.
- Every new endpoint covers: happy path, validation failure (422), auth failure (401).
- Review autogenerated Alembic revisions by hand - autogenerate misses server
  defaults and enum renames.

## Security
- Auth is JWT bearer via `app/core/security.py`; routers opt in with the
  `CurrentUser` dependency, never by parsing headers inline.
- Settings come from the environment through `app/core/config.py`; no secrets in git.

## Boundaries
- Dependency direction is one-way: `app.models` never imports `app.services`.
- Routers don't touch the DB; go through a service function.
- Never downgrade migrations in shared environments; roll forward.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.