c98512cfcc
All checks were successful
secrets-guard / encrypted (pull_request) Successful in 10s
PR build (required check) / changes (pull_request) Successful in 17s
shell-lint / shellcheck (pull_request) Successful in 14s
PR build (required check) / validate-observability (pull_request) Successful in 44s
PR build (required check) / build-frontend (pull_request) Successful in 2m13s
PR build (required check) / build-backend (pull_request) Successful in 2m31s
PR build (required check) / gate (pull_request) Successful in 3s
The four domain CLAUDE.md files still described the pre-monorepo split-repo topology, and several statements were the exact inverse of current reality: infra/CLAUDE.md told a reader that emi/thermograph is archived and must not be pointed at, when that is the live repo; backend/ and frontend/ both claimed there is no Makefile and no requirements-dev.txt when all four files exist; frontend/ described itself as one of four sibling repos; observability/ claimed a single unprotected main branch. These files are read before every change, so a stale one is a correctness problem rather than a documentation one. Rewritten against the tree: - Root CLAUDE.md now owns the cross-cutting truth once — branch model, the SERVICE + *_IMAGE_TAG deploy contract, image names, which orchestrator each environment runs, and that everything is a PR. Domain files carry only what differs and are capped at ~70 lines. - Records that prod runs Swarm from deploy/stack/thermograph-stack.yml while beta and LAN dev run compose, routed by /etc/thermograph/deploy-mode. - Documents the *-deploy-dev.yml workflows as inert rather than leaving a reader to discover it. Deletes infra/docker-stack.yml. It defined db/app/worker, matched nothing that deploys, and was referenced only by prose describing it as a future design record — while the real 8-service prod stack lives under deploy/stack/. A file that looks authoritative and affects nothing is the worst case for a reader asked to change the prod stack. infra/README.md claimed "compose in production today" and that Swarm was "not currently live"; corrected, and infra-sync.yml's existence is now recorded instead of "there is no separate infra deploy trigger". The compose file's timescale-pin comment now points at how deploy-stack.sh actually resolves the digest from the running container.
72 lines
3.5 KiB
Markdown
72 lines
3.5 KiB
Markdown
# 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.
|