thermograph/frontend/server/README.md

thermograph-frontend (Go)

The SSR frontend service, ported from the Python implementation one directory up (app.py / content.py / api_client.py / format.py): server-rendered content pages, the interactive tool's SPA shells, and every static asset. It is I/O-bound glue over the backend's /content/* JSON API — no climate maths, no database, no auth.

Layout

go.mod                        module thermograph/frontend (Go 1.26)
main.go                       config + mux + static + graceful shutdown
internal/config/              every env var the service reads (same names,
                              defaults and required/optional split as the
                              Python — see config.go's field docs)
internal/contentapi/          backend /content/* client: TTL cache, bounded
                              LRU, per-key single-flight, origin forwarding;
                              typed payloads in types.go
internal/render/              html/template engine over an embed.FS +
                              response ETag helpers (W/"sha1[:20]",
                              If-None-Match handling)
internal/render/templates/    the page templates (embedded; *.tmpl)
internal/contentdata/         glossary.yaml / pages.yaml loader (fail-loud
                              validation, file order preserved)

Dependencies: stdlib plus gopkg.in/yaml.v3 — the committed SSR copy in frontend/content/*.yaml is shared with the rest of the repo and uses block/ folded scalars, so a YAML parser is genuinely required.

Run locally

cd frontend/server
go build -o thermograph-frontend .
cd ..            # static/ and content/ resolve relative to the working dir
THERMOGRAPH_API_BASE_INTERNAL=http://127.0.0.1:8137 \
THERMOGRAPH_BASE=/thermograph \
  ./server/thermograph-frontend

THERMOGRAPH_API_BASE_INTERNAL is required — the boot fails loudly without it, same as the Python raised at import. Other env vars (all optional): THERMOGRAPH_BASE (default /thermograph; the image sets /), THERMOGRAPH_API_VERSION (default v2 — bump only per the API-version pinning contract in frontend/CLAUDE.md), THERMOGRAPH_API_BASE_PUBLIC, THERMOGRAPH_SSR_CACHE_TTL (seconds, default 600), THERMOGRAPH_GOOGLE_VERIFY / THERMOGRAPH_BING_VERIFY, and PORT (default 8080).

The process expects static/ and content/ in its working directory (frontend/ locally, /app in the image). Templates are embedded in the binary; static assets and the YAML copy are read from disk.

Test / verify

cd frontend/server
go build ./... && go vet ./... && go test ./...

The deployed binary is /usr/local/bin/thermograph-frontend inside the emi/thermograph/frontend image; the image name, frontend-* CI workflows and deploy path are unchanged from the Python service.