2026-07-23 05:11:33 +00:00
|
|
|
# thermograph
|
|
|
|
|
|
|
|
|
|
The Thermograph monorepo — the split repos reunified (2026-07-22) with full
|
|
|
|
|
history via subtree merges, while keeping everything the split was actually
|
|
|
|
|
for: **per-domain images, per-domain deploys, and an async FE/BE contract**.
|
|
|
|
|
|
|
|
|
|
## Domains
|
|
|
|
|
|
|
|
|
|
| Dir | What | CI |
|
|
|
|
|
|---|---|---|
|
2026-07-25 07:48:49 +00:00
|
|
|
| `backend/` | FastAPI graded-climate API, accounts, notifications (Discord bot, push, mail), data pipeline | `build-push` → image `emi/thermograph/backend`; `deploy` |
|
|
|
|
|
| `frontend/` | Public client: static JS/CSS + SSR pages | same `build-push` / `deploy` workflows, matrixed by domain; image `emi/thermograph/frontend` |
|
2026-07-26 06:56:38 +00:00
|
|
|
| `infra/` | Compose (dev, on vps1) + two Swarm stacks co-resident on vps2 (beta, prod), deploy scripts, terraform, SOPS secrets vault, ops cron | `infra-sync` (host checkout + secrets render), `secrets-guard`, `ops-cron` |
|
2026-07-23 05:11:33 +00:00
|
|
|
| `observability/` | Loki + Grafana + Alloy stack | `observability-validate` |
|
|
|
|
|
|
|
|
|
|
`thermograph-docs` deliberately **stays its own repo** (ADRs + runbooks, no
|
|
|
|
|
build artifacts, different change cadence).
|
|
|
|
|
|
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:25:52 +00:00
|
|
|
## New here?
|
|
|
|
|
|
|
|
|
|
[`docs/onboarding/`](docs/onboarding/README.md) is the developer onboarding
|
|
|
|
|
path: orientation, verified local-setup recipes, a per-domain deep dive, the
|
|
|
|
|
cross-service contracts that break silently, the release flow, and a list of
|
|
|
|
|
which docs in this repo are currently stale.
|
|
|
|
|
|
2026-07-23 05:11:33 +00:00
|
|
|
## How CI stays decoupled
|
|
|
|
|
|
|
|
|
|
Every workflow in `.forgejo/workflows/` is **path-filtered to its domain**: a
|
|
|
|
|
push touching only `frontend/**` builds/deploys nothing else. Images stay
|
|
|
|
|
separate (`emi/thermograph/backend`, `emi/thermograph/frontend`, each tagged
|
|
|
|
|
`sha-<12hex>`), deploys stay per-service (`infra/deploy/deploy.sh
|
|
|
|
|
SERVICE=backend|frontend|all`), and the API version contract
|
|
|
|
|
(`GET /api/version`, `PAYLOAD_VER`) still lets FE and BE ship out of lockstep.
|
|
|
|
|
The one intentionally *coupled* piece is `pr-build.yml`: a single always-running
|
|
|
|
|
`gate` required check that builds only the domains a PR touches (a
|
|
|
|
|
path-filtered required check would deadlock auto-merge).
|
|
|
|
|
|
|
|
|
|
Branch model (unchanged from the split era): PRs → `dev`, `main` → beta,
|
2026-07-26 06:56:38 +00:00
|
|
|
`release` → prod. Infra isn't environment-staged the same way app images are:
|
|
|
|
|
beta's and prod's checkouts (both on vps2) track `main`; dev's checkout (on
|
|
|
|
|
vps1) tracks `dev` itself, since it's the one environment that isn't a
|
|
|
|
|
rehearsal for something downstream.
|
2026-07-23 05:11:33 +00:00
|
|
|
|
|
|
|
|
**Before pointing anything live at this repo, read `CUTOVER-NOTES.md`.**
|
