Emi Griffith 12441be0c1

secrets-guard / encrypted (push) Successful in 5s

Details

shell-lint / shellcheck (push) Successful in 6s

Details

docs: add a developer onboarding guide for the monorepo

Twelve documents under docs/onboarding/ covering orientation, local setup,
the repo map, per-domain deep dives, the cross-service contracts, CI and the
release flow, infra and secrets, observability, task recipes, and a list of
which docs in this tree are currently stale.

Every command in the setup guide was run against this checkout: the backend
suite (429 passed, 8 skipped), the frontend Go suite, a venv boot of the
backend, and a build+boot of the Go frontend.

Two findings recorded along the way:

- static/units.js's F_REGIONS is guarded by no test, despite three source
  comments claiming "a test asserts all three stay identical". The Go test
  only cross-checks the Go copy against the backend's Python. All four copies
  are currently identical.
- backend/ and frontend/docker-compose.test.yml still default to the retired
  emi/thermograph-backend/app image path, and the frontend harness pins the
  split-era v0.0.2-split-ci tag.

Claude-Session: https://claude.ai/code/session_01AfXqHrxCJLs2D7hpQkiUiJ

2026-07-25 18:34:44 +00:00

4.1 KiB

Raw Blame History

Onboarding — becoming a full contributor to Thermograph

This is the developer onboarding path for the emi/thermograph monorepo: what the product is, how the code is shaped, how to run it, what will break silently if you get it wrong, and how a change actually travels from your editor to thermograph.org.

Scope. This covers working in this repo. Cross-cutting architecture decision records and operator runbooks live in the separate thermograph-docs repo (reachable through Centralis's docs_search) — this set links out rather than duplicating them. Where a fact is owned by a CLAUDE.md, that file stays the source of truth and this set explains the context around it.

Reading order

#	Doc	Read it when
1	Orientation	First. What the product actually claims, the estate, the four non-negotiable rules.
2	Local setup	Before you touch anything. Toolchain, verified run/test recipes for every service.
3	Repo map	To find things. Every domain and directory, and which files matter.
4	Backend deep dive	Before your first backend change. Data pipeline, grading, caching, roles, daemon.
5	Frontend deep dive	Before your first frontend change. The Go SSR service, static assets, design system.
6	Cross-service contracts	Before any change that touches both. These break silently and in production.
7	CI and release	Before you open a PR. Nine workflows, three branches, three environments.
8	Infra and secrets	Before you touch deploy, compose, or a secret.
9	Observability	When something is wrong and you need to see it.
10	Recipes	Task-shaped walkthroughs for the things you'll actually do.
11	Traps and stale docs	Skim early, re-read often. Which docs in this repo currently lie, and why.

The short version

Thermograph grades how unusual today's weather is at any point on Earth against ~45 years of that exact location's own history. Percentiles, never thermometer readings.

backend/ — Python 3.12 / FastAPI. Owns all climate data, grading, the API, accounts, notifications, plus a Go daemon (backend/daemon/) that owns the Discord gateway and recurring timers. Ships as emi/thermograph/backend.
frontend/ — Go SSR service (frontend/server/) plus every static asset. No climate data, no database, no compute. Ships as emi/thermograph/frontend. (The Python implementation at frontend/*.py is the superseded original — see traps.)
infra/ — compose and Swarm files, deploy scripts, the SOPS secrets vault, Terraform, ops query tooling.
observability/ — Loki + Grafana on beta, an Alloy agent per node.

Branches stage environments: PR → dev (LAN dev) → main (beta) → release (prod). The two app domains build and deploy independently — that independence is the whole reason the split-then-reunify history exists, and contracts is the list of things that keep it safe.

Your first day

Read Orientation and Traps.
Work through Local setup until make test is green in both backend/ and frontend/server/.
Read Repo map with the tree open beside it.
Pick something small in the domain you're least afraid of, and follow Recipes end to end — including opening the PR.

Your first week

Read Contracts properly. Every item on that list has already cost someone a production incident somewhere in this project's history; that's why each one is written down.
Get Centralis wired up (see Local setup) and ask it fleet_status, logs_overview, deployed_version. You cannot debug this estate blind, and the boxes are not reachable from a laptop off the WireGuard mesh.
Read the CLAUDE.md for each domain. They are terse, current, and binding.

4.1 KiB Raw Blame History