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.

The live service is Go — server/

server/ (module thermograph/frontend, Go 1.26) is what builds, tests, ships and runs. It is the only thing in the emi/thermograph/frontend image.

The Python files at this level — app.py, content.py, api_client.py, format.py, content_loader.py, paths.py, templates/*.html.j2 — are the superseded original implementation, kept as the reference the port was made from. Nothing deploys them. Don't add features there; don't take their file paths as current. (They still carry duplicate copies of some contracts below — notably api_client.py's API_VERSION pin and format.py's F_COUNTRIES. If you use them locally, keep them in step or you will debug a phantom.)

Deleting them is a live question, not a settled one — the Python test tiers still run against the fixtures the Go tests share. Raise it rather than doing it in passing.

Build & verify

• cd server && go build ./... && go vet ./... && go test ./... — the suite that matters.
• CI runs it inside Dockerfile's builder stage, which does gofmt -l + go vet + go test ./... before compiling. A failing Go test therefore fails the image build — that is the whole frontend check. There is no separate frontend test step in any workflow.
• make test-unit / make test-integration — the Python tiers. Local only; CI runs neither. The unit tier is hermetic (SSR rendering fed committed fixtures); the integration tier pulls and runs a real backend image.
• make backend-up / make backend-down — a local backend container for dev. The image tag is derived from this checkout (last commit touching backend/, the same domain-keyed rule build-push and deploy use); override with THERMOGRAPH_BACKEND_TEST_TAG=sha-<12hex>.
• make capture-fixtures — refresh tests/fixtures/*.json from a live backend. These fixtures feed the Go tests too, not just the Python ones.

Running it

THERMOGRAPH_API_BASE_INTERNAL is required — the boot fails loudly without it, as the Python raised at import.

Build in server/, run from frontend/: static/ and content/ resolve relative to the working directory, while templates are embedded in the binary.

cd server && go build -o thermograph-frontend .
cd ..
THERMOGRAPH_API_BASE_INTERNAL=http://127.0.0.1:8137 THERMOGRAPH_BASE=/thermograph \
  ./server/thermograph-frontend

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), THERMOGRAPH_GOOGLE_VERIFY / THERMOGRAPH_BING_VERIFY, PORT (default 8080).

Boot is fail-loud on bad config or content: a missing backend URL, a garbage TTL, or malformed content/*.yaml all stop the process rather than 500 on the first request.

Layout

• server/internal/content/ — the SSR page handlers (climate hub, city, month, records, glossary, about, privacy) + robots.txt + sitemap.xml, plus the template funcmap and SEO helpers. The backend's content_payloads.py owns page_title / canonical_path / breadcrumb / jsonld, not this domain.
• server/internal/contentapi/ — the backend /content/* client: TTL cache, bounded LRU, per-key single-flight, origin forwarding. All four properties are load-bearing; read the file before changing caching.
• server/internal/render/ + render/templates/*.tmpl — html/template over an embed.FS, plus the ETag helpers. Templates are embedded, so a template change needs a rebuild.
• server/internal/{config,format,contentdata,handlers}/ — env parsing, unit-aware °C/°F formatting and band names, the glossary/pages loader, and the SPA-shell + static handlers.
• 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.
• content/*.yaml — structured SSR copy, loaded by server/internal/contentdata.

Contracts with the backend

• API version is pinned in exactly two places — server/internal/config's THERMOGRAPH_API_VERSION (Go) 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 — and so must server/internal/format's PctOrdinal. Every percentile on every surface goes through one of the three; 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 — server/internal/format's FCountries and static/units.js's F_REGIONS must stay identical to the backend's F_COUNTRIES. Both are now asserted by tests in server/internal/format/format_test.go: the backend cross-check is a checkout-only guard (the image build context is frontend/, so backend/ is unreachable there), while the units.js check runs in the image build too — Dockerfile copies that one file into the builder stage for exactly that reason.
• Boot must survive an unreachable backend. The IndexNow-key fetch is tried once at boot, caught, 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.