thermograph/frontend/CLAUDE.md

# frontend/ — agent instructions

The **SSR + static-asset service**: server-rendered crawlable pages, the
interactive tool's SPA shells, and every static asset. No climate data, no DB,
no compute — everything comes from `backend/`'s content API over HTTP.

Read the root `CLAUDE.md` first for the branch model, deploy contract and image
names.

## Build & verify

- `make test` — whole suite (`scripts/test.sh`).
- `make test-unit` — hermetic unit tier: SSR rendering fed committed fixtures,
  no Docker. **This is the tier CI runs.**
- `make test-integration` — pulls and runs the real backend image and tests the
  live contract. Local only; CI does not run it.
- `make backend-up` / `make backend-down` — a local backend container for dev.
- `make capture-fixtures` — refresh `tests/fixtures/*.json` from a live backend.

## Running it

`THERMOGRAPH_API_BASE_INTERNAL` is **required** — `api_client.py` raises at
import if unset.

```bash
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
```

Other env: `THERMOGRAPH_BASE` (default `/thermograph`; the Dockerfile sets `/`),
`THERMOGRAPH_API_VERSION` (default `v2`), `THERMOGRAPH_API_BASE_PUBLIC`
(browser-facing backend origin when cross-origin; empty = same-origin, today's
default), `THERMOGRAPH_SSR_CACHE_TTL` (default 600s).

## Layout

- **`content.py`** — SSR routes (climate hub, city, month, records, glossary,
  about, privacy) + `robots.txt` + `sitemap.xml`. Each fetches from the backend
  via `api_client.py`; the backend's `content_payloads.py` owns `page_title` /
  `canonical_path` / `breadcrumb` / `jsonld`, not this domain.
- **`static/*.js`** — `app.js` (map/search/results + inline SVG chart),
  `calendar.js`/`day.js`/`score.js`/`compare.js` (SPA shells), `account.js`
  (auth), `cache.js` (IndexedDB cache + `/cell` bundle prefetch), `shared.js`.
- **`static/style.css`** — the single hand-written stylesheet; design tokens live
  here, documented in `DESIGN.md`.
- **`templates/*.html.j2`**, **`content/*.yaml`** (structured SSR copy, loaded by
  `content_loader.py`).

## Contracts with the backend

- **API version is pinned in exactly two places** — `api_client.py`'s
  `API_VERSION` (Python) and `static/account.js`'s exported `API_VERSION` plus the
  `uv(path)` helper (JS). Never hardcode `api/v2/...` anywhere else. Bump both in
  one PR, and only after the target backend's `/api/version` confirms it serves
  that version and its `min_frontend` doesn't exclude the one you're leaving.
- **`shared.js::pctOrd()` must mirror `backend`'s `data/grading.py::pct_ordinal()`**
  in behaviour — floor into `1..99`, never 0 or 100. Every percentile on every
  surface goes through one of the two; if they diverge, the same reading says two
  different things in two places.
- **`/cell` bundle + ETag** — `cache.js` fetches `/api/v2/cell` once per view-set
  and slices it, revalidating with `If-None-Match`. The slice→view map must track
  the backend's payload shape.
- **Fahrenheit country set** — `format.py::F_COUNTRIES` and `static/units.js`'s
  `F_REGIONS` must stay identical to the backend's `F_COUNTRIES`.
- **Boot must survive an unreachable backend.** `content.py`'s `register()` tries
  the IndexNow-key fetch once, catches failure, and falls back to a lazy
  per-request lookup. Asynchronous FE/BE deploys depend on this — don't make it
  fatal.

## Commits & PRs

Concise and technical. Never mention AI, assistants or automated authorship.