thermograph/CLAUDE.md

Thermograph frontend — agent instructions

This repo is the SSR + static-asset service split out of the emi/thermograph monorepo (repo-split Stage 7). It has no climate data, no DB, and does no polars/compute work — everything comes from the backend's content API over HTTP. It is one of four sibling repos in thermograph-repos/:

• thermograph-backend — FastAPI API + grading/scoring/grid compute + DB. This repo's only dependency.
• thermograph-frontend (this repo) — SSR content pages + the interactive tool's SPA shells + every static asset.
• thermograph-infra — Terraform, docker-compose*.yml, deploy/ (incl. deploy.sh, the SOPS secrets vault), Caddy config. No app code.
• thermograph-docs — architecture decision records + operator runbooks. No code.

See MONOREPO-CUTOVER-PLAN.md (one level up, in thermograph-repos/) for the full split status and the remaining gap list before the monorepo can be archived.

What this repo is

• content.py — server-rendered, crawlable pages (climate hub, per-city, month, records, glossary, about, privacy) + robots.txt + sitemap.xml. Every route fetches its data from the backend's content API (api_client.py) instead of computing in-process; content_payloads.py on the backend owns page_title/canonical_path/breadcrumb/jsonld, not this repo.
• static/*.js — the interactive tool: app.js (map/search/graded results + inline SVG chart), calendar.js/day.js/score.js/compare.js (SPA shells served by app.py's _page()), account.js (auth), cache.js (IndexedDB response cache + /cell bundle prefetch), shared.js (format helpers shared across views).
• static/style.css — the single hand-written stylesheet; all design tokens live here (see DESIGN.md).
• templates/*.html.j2 — Jinja templates content.py renders.
• content/*.yaml — structured SSR copy (glossary, static-page SEO meta), loaded by content_loader.py. Committed here as a starter copy extracted alongside the split; real cross-repo copy vendoring (a pinned thermograph-copy checkout at build time) is deferred, unbuilt follow-up — don't assume it exists.

Branch/PR + deploy flow

• Work happens on feature branches; PR into main. (The monorepo's dev→main→release three-stage promotion and its LAN deploy-dev.yml path do not exist in this repo yet — a documented gap, see the cutover plan §4. Don't assume a dev branch here.)
• .forgejo/workflows/build-push.yml — on push to dev/main/release or a v*.*.* tag: builds THIS repo's own Dockerfile and pushes git.thermograph.org/emi/thermograph-frontend/app, tagged sha-<12 hex> (every push) and the semver tag (tag pushes only). Backend publishes its own separate image the same way — the two are no longer one shared emi/thermograph/app image.
• .forgejo/workflows/build.yml — push/PR to main: proves the Dockerfile builds. It is a build check only, not a boot/health check — booting the real app crashes at import without a reachable backend (see API-version section below), so a standalone boot check would need to check out thermograph-backend too. Not yet built; flagged, not silently skipped.
• .forgejo/workflows/deploy.yml — push to main: SSH to beta, run SERVICE=frontend FRONTEND_IMAGE_TAG=sha-<12 hex> /opt/thermograph/deploy/deploy.sh (that script lives in thermograph-infra). Rolls only the frontend container (--no-deps); backend is untouched and deployed independently by its own repo's workflow. deploy.sh retries the image pull for ~5 min (Forgejo has no cross-workflow needs:, so this deploy can race ahead of build-push.yml) and waits for a healthy backend before declaring the roll OK (frontend's boot fetches the IndexNow key from backend — see below).
• .forgejo/workflows/deploy-prod.yml — push to release: same shape, targets prod via its own PROD_SSH_* secret set (fully separate from beta's, so a beta credential leak can't touch prod). Nothing else deploys to prod; there is no release-triggered Terraform apply from this repo.
• The SERVICE=frontend + FRONTEND_IMAGE_TAG=sha-<12 hex> pair is the entire contract into thermograph-infra/deploy/deploy.sh: it persists each service's live tag in deploy/.image-tags.env (host-side, untracked) so a frontend-only roll never disturbs backend's currently-running tag, and vice versa.

How to run / test

There is no run.sh/Makefile in this repo yet (the monorepo's make lan-run/make run/make stop/venv targets have no home here — see the cutover plan's gap list). Run directly:

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
THERMOGRAPH_API_BASE_INTERNAL=http://127.0.0.1:8137 \
THERMOGRAPH_BASE=/thermograph \
  .venv/bin/uvicorn app:app --host 0.0.0.0 --port 8080

THERMOGRAPH_API_BASE_INTERNAL is required — api_client.py raises RuntimeError at import if it's unset. Other env vars: THERMOGRAPH_BASE (default /thermograph; the Dockerfile sets / for the deployed clean-root topology), THERMOGRAPH_API_VERSION (default v2, see below), THERMOGRAPH_API_BASE_PUBLIC (browser-facing backend origin for asset URLs when frontend and backend are cross-origin; empty = same-origin, today's default), THERMOGRAPH_SSR_CACHE_TTL (default 600s, the content-API response cache in api_client.py), THERMOGRAPH_GOOGLE_VERIFY/THERMOGRAPH_BING_VERIFY (search-console <meta> tags).

Known gap — tests/conftest.py does not run standalone in this repo. It still assumes the pre-split layout: a sibling backend/ checkout with its own tests/conftest.py (make_history/make_recent) and an api.content_payloads module, neither of which exists here. It was extracted verbatim as reference material for the real fix (a genuine cross-repo contract-test job, or a self-contained set of fixtures owned in this repo) — not yet built. Do not assume pytest tests passes here until that lands; .forgejo/workflows/build.yml only proves the image builds, for the same reason. There is also no requirements-dev.txt in this repo yet (pytest/httpx test deps aren't pinned).

API-version pinning contract

Every backend call in this repo goes through a single pinned constant instead of scattered api/v2/... literals:

• Python (SSR): api_client.py's module-level API_VERSION (default "v2", overridable via THERMOGRAPH_API_VERSION). Every path builder (hub(), sitemap(), indexnow_key(), home(), city(), city_month(), city_records()) reads it.
• JS (interactive tool): static/account.js's exported API_VERSION constant and the uv(path) helper — every fetch in cache.js, account.js itself, etc. is built by wrapping the path in uv(...) rather than hardcoding a version.

Bump only in lockstep with a verified backend /api/version check — the backend exposes GET {BASE}/api/version → {backend_version, min_frontend, payload_ver} (web/app.py's API_CONTRACT_VERSION/MIN_SUPPORTED_FRONTEND). Before bumping this repo's API_VERSION, confirm the target backend's backend_version actually supports it and its min_frontend doesn't already exclude the version you're moving away from.

A v3 cutover would work like this: backend mounts a new v3 = APIRouter() alongside v2, re-registering only the changed handlers (v2 keeps serving old clients); backend bumps API_CONTRACT_VERSION to "3" in that same PR. Only once that's deployed and verified does this repo bump API_VERSION to "v3" in both api_client.py and account.js — one PR, both pins together, never one without the other. v2 (and the /api, /api/v1 aliases) stay mounted and working until no client depends on them.

The frontend's own boot is resilient to the backend being down: the indexnow_key() fetch in content.py's register() is tried once eagerly (so the common case still serves /<key>.txt as a plain static route), but a failure is caught, logged, and falls back to a lazy per-request lookup instead of crashing boot — asynchronous frontend/backend deploys depend on this (a briefly-unreachable backend at frontend boot must be survivable, not fatal).

Cross-repo contracts this repo depends on

These are live contracts with the backend — a change on either side without the other breaks something silently, not loudly:

• The /cell bundle + ETag/If-None-Match — static/cache.js fetches /api/v2/cell once per view-set and slices it for calendar/day/score/compare instead of one request per view; conditional refetch is via If-None-Match against the stored ETag, so an unchanged payload costs an empty 304. The URL map (which slice serves which view) must stay in sync with thermograph-backend's route/payload shape.
• shared.js's pctOrd() must mirror thermograph-backend's data/grading.py's pct_ordinal() byte-for-byte in behavior: floor a percentile into 1..99 (never round to 100/0 — "100th percentile" reads as measurement error, not "as extreme as it has ever been"). Every percentile shown anywhere (Day page, calendar tooltip, chart, city pages, homepage strip) goes through one of these two functions; if they diverge, the same reading says two different things on two different surfaces.
• Unit/region logic (format.py's F_COUNTRIES / static/units.js's F_REGIONS / backend's api/content_payloads.py's F_COUNTRIES) — the set of Fahrenheit-using country codes must stay identical across all three; backend has a test asserting this.

Design & visual verification

Design tokens + conventions are documented in DESIGN.md (source of truth: static/style.css). To see a change rendered, see DESIGN.md's make shots section (tools/shoot.py).

Commits & PRs

Describe only the substance of the change; concise, technical. Never mention AI/Claude/assistants or automated authorship anywhere — no trailers, co-authors, emoji, or "as requested"/"per the agent" narration.