# thermograph-backend

The Thermograph API service: grades recent local weather against ~45 years of
climate history, and hosts the accounts, notification, and SSR-content
back-end that the rest of the split Thermograph stack (`thermograph-frontend`)
talks to over HTTP. Split from the `Jinemi/thermograph` monorepo — this repo owns
the API/DB/accounts/notifications layer only; it renders no HTML/CSS/JS of its
own.

See [`CLAUDE.md`](CLAUDE.md) for the full split topology, deploy flow, and
API version contract, and [`thermograph-docs`](../thermograph-docs) (a sibling
repo) for cross-cutting architecture decisions and operator runbooks.

## How it works

1. **Grid** — a lat/lon is snapped to a stable **~4 sq mi cell**
   (`data/grid.py`); longitude spacing is scaled by `cos(latitude)` so cells
   stay roughly square at any latitude. The cell id is the cache key, so the
   same spot always resolves to the same data.
2. **Data (on-demand, cached to parquet)** — the first request for a cell
   fetches the full **1980–present daily record** (max/min temp, precip) from
   the free [Open-Meteo](https://open-meteo.com) archive (ERA5) and writes it
   to `data/cache/<cell_id>.parquet` (zstd, ~200 KB for 45 years). Later
   requests read the parquet directly. Recent days come from Open-Meteo's
   forecast API (`past_days`), so history and grading share one source.
3. **Percentiles & grading** (`data/grading.py`) — each day is graded against
   every historical day within **±7 days** of it (a 15-day seasonal window,
   wrapping year-end), as an empirical mid-rank percentile. Temperature uses a
   symmetric tier ladder (`TEMP_BANDS`: Near Record / High / Above Normal /
   Normal / Below Normal / Low / Near Record); precipitation is graded
   separately (`RAIN_BANDS`) since most days are dry — a rainy day is ranked
   only among rain days in its window, dry days are colored by dry-streak
   length instead.
4. **Caching & ETags** — every derived payload (grade/calendar/day/SSR
   content) is cached in SQLite (`data/store.py`) under `(kind, cell_id, key)`,
   validated by a token that only advances when the cell's history actually
   changes. That token doubles as a weak ETag, so an unchanged request costs a
   304 with no payload rebuild (`api/payloads.py`, `web/app.py`).

## Layout

```
accounts/       fastapi-users models/schemas/db + api_accounts routes
alembic/        Postgres schema migrations (alembic upgrade head on boot)
api/            versioned payload builders (payloads.py, content_payloads.py)
                + route wiring (content_routes.py, sitemap.py, homepage.py)
core/           metrics, audit/access logging, a singleton helper
data/           grid snapping, climate fetch/cache, grading/scoring,
                places/cities, the derived-payload store
notifications/  push (VAPID), email, Discord bot (interactions + linking),
                monthly digest, the in-process scheduler (city warming, IndexNow)
web/app.py      the FastAPI app (routes, CORS, ETag/versioning, middleware)
deploy/         container entrypoint.sh (alembic migrate, then serve)
app.py          shim re-exporting web.app:app — keeps the launch target
                `app:app` stable regardless of internal package layout
scripts/        one-off admin scripts (Discord slash-command registration)
tests/          pytest suite, hermetic (see tests/conftest.py)
cities.json,
cities_flavor.json   bundled reference data (generated by gen_cities.py /
                     gen_flavor.py), not runtime state
```

## How it fits the split

- **`thermograph-frontend`** calls this service's `GET /api/v2/...` endpoints
  (grade, geocode, calendar) and the SSR content endpoints under
  `/content/...`; it negotiates compatibility via `GET /api/version`.
- **`thermograph-infra`** owns the deploy/Compose/Terraform layer — this repo
  only builds and publishes its own container image
  (`git.thermograph.org/admin_emi/thermograph-backend/app`) and hands infra a tag to
  roll out (`SERVICE=backend` + `BACKEND_IMAGE_TAG` into infra's
  `infra/deploy/deploy.sh`).
- **`thermograph-docs`** holds the cross-repo architecture/runbook docs; this
  README only covers what's local to this service.

## Build & run

```bash
docker build -t thermograph-backend .
docker run -p 8137:8137 --env-file .env thermograph-backend
```

The image runs `deploy/entrypoint.sh`: `alembic upgrade head` against
`THERMOGRAPH_DATABASE_URL` (retried, since a fresh Postgres volume can still be
starting up), then `uvicorn app:app` on `$PORT` (default `8137`) with
`$WORKERS` workers (default 4). `/healthz` is an I/O-free liveness probe.

For local development without a container, see the "Run / test locally"
section of [`CLAUDE.md`](CLAUDE.md) — there is no Makefile in this repo yet,
so it's a plain venv + `pytest`/`uvicorn` invocation.

## Notifications: Discord slash commands

`notifications/discord_interactions.py` answers Discord's HTTP Interactions
endpoint (`/discord/interactions`) for the `/grade <city>` slash command.
Registering (or updating) the command definition with Discord's REST API is a
one-off admin action, not part of the running app:

```bash
THERMOGRAPH_DISCORD_APP_ID=... THERMOGRAPH_DISCORD_BOT_TOKEN=... \
    python3 scripts/register_discord_commands.py
```

Global command changes can take up to an hour to propagate.

<!-- monorepo cutover 2026-07-23 -->