# apps/api

Python 3.12 / FastAPI / SQLAlchemy 2.0 async / Alembic. See `docs/PLAN.md` for the overall
design and `docs/DECISIONS.md` for why things are built this way.

## Layout

```
velodrome/
  app.py              FastAPI app factory
  config.py            Settings (env-driven, see below)
  db.py                Two database engines — read this first, it's the load-bearing module
  ids.py                UUIDv7 generation
  models/               SQLAlchemy models
  auth/                 Password hashing, session service, FastAPI auth dependencies
  api/v1/                Route handlers
  schemas/               Pydantic request/response models
alembic/                 Migrations. 0001_baseline.py creates the identity tables, the two
                          runtime DB roles, and their RLS policies — read its module docstring.
tests/                    pytest, against a real Postgres, never mocked
```

## Why two database connections

The app connects to Postgres as **two different roles**, not one — this is the single most
important thing to understand before touching `auth/` or `db.py`:

- **`velodrome_app`** — `NOBYPASSRLS`. Every request that already knows who's calling uses this,
  via `db.scoped_session(user_id)`, which sets `app.user_id` for the transaction so Postgres RLS
  policies can key off it.
- **`velodrome_auth`** — `BYPASSRLS`. Used *only* by `auth/service.py`, and only for the narrow
  set of lookups that must happen *before* identity is known: login by email, a session by its
  token hash, an invite by its code hash — plus the inserts that create those rows. Every one of
  those queries is an exact match on a unique key, never an unfiltered scan, which is what makes
  bypassing RLS safe there.

A third connection — `VELODROME_DATABASE_URL_MIGRATE` — is used only by Alembic. It needs enough
privilege to `CREATE ROLE` and `GRANT`, so in practice it's the Postgres superuser (or a
schema-owning role); the app itself never connects with it.

If you're adding a new table with per-user data: give it a `user_id` column, enable RLS on it in
a migration, and query it only through `scoped_session`. See CLAUDE.md's invariants.

## Environment variables

| Variable | Used by | Notes |
|---|---|---|
| `VELODROME_DATABASE_URL_MIGRATE` | Alembic only | Superuser/owner DSN. Never used by the app itself. |
| `VELODROME_DB_APP_PASSWORD` | Alembic (creates the role) | No default — the migration fails loudly if unset. |
| `VELODROME_DB_AUTH_PASSWORD` | Alembic (creates the role) | Same. |
| `VELODROME_DATABASE_URL_APP` | The app | Connects as `velodrome_app`. |
| `VELODROME_DATABASE_URL_AUTH` | The app | Connects as `velodrome_auth`. |
| `VELODROME_SECRET_KEY` | The app | Not yet used (arrives with the Bryton credential encryption in a later phase); declared now so the settings shape is stable. |
| `VELODROME_ENVIRONMENT` | The app | `development` / `test` / `production`. Gates the session cookie's `Secure` flag — see the comment in `api/v1/auth.py` before changing this condition. |
| `VELODROME_PUBLIC_URL` | The app | Used for the CSRF `Origin` check on cookie-authenticated mutations. |

## Running locally

```bash
uv sync --all-extras

# a throwaway Postgres
docker run -d --name velodrome-dev-pg -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=velodrome \
  -p 5432:5432 postgis/postgis:16-3.4

export VELODROME_DATABASE_URL_MIGRATE=postgresql+asyncpg://postgres:postgres@localhost:5432/velodrome
export VELODROME_DB_APP_PASSWORD=devpassword1
export VELODROME_DB_AUTH_PASSWORD=devpassword2
export VELODROME_DATABASE_URL_APP=postgresql+asyncpg://velodrome_app:devpassword1@localhost:5432/velodrome
export VELODROME_DATABASE_URL_AUTH=postgresql+asyncpg://velodrome_auth:devpassword2@localhost:5432/velodrome

uv run alembic upgrade head
uv run uvicorn velodrome.app:app --reload
```

`GET /api/v1/healthz` should return `{"status": "ok"}`; `GET /api/v1/docs` has interactive
Swagger UI outside production.

## Testing

```bash
uv run ruff check . && uv run ruff format --check .
uv run mypy --strict velodrome
uv run pytest
```

Tests run against a real Postgres (a service container in CI, or point `tests/conftest.py`'s
defaults at your own) — never mocks for DB behaviour, per CLAUDE.md. The test suite runs the real
Alembic migration at session start, not a parallel schema-creation shortcut, so it's exercising
the exact same path a real deploy uses.

The test worth reading if you're new to this codebase is
`tests/test_auth.py::test_rls_blocks_cross_user_session_reads` — it doesn't trust that the RLS
policy SQL is correct because it reads correctly; it proves it by actually trying to read another
user's row through the scoped role and asserting zero come back.

## A note on `alembic check`

CI's `migrations` job runs `alembic check` to catch drift between the ORM models and the actual
migrations. `alembic/env.py`'s `include_object` filter restricts that comparison to tables our own
metadata declares — **deliberately an allowlist, not a denylist of PostGIS/TIGER tables**, because
reflected foreign tables can come back with `schema=None` regardless of which schema they actually
live in (confirmed against a real `postgis/postgis:16-3.4` container), which makes a schema-based
denylist unreliable. If you add a new model, it's automatically covered — no filter to update.