bike-app/apps/api/README.md

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

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

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.