thermograph/backend/CLAUDE.md

backend/ — agent instructions

The Thermograph API service: a FastAPI app serving the graded-climate API (/api/v2/...), user accounts, notifications, and the SSR-content JSON API the frontend renders pages from. It owns the climate data pipeline and the derived-payload cache. It serves no HTML/CSS/JS — that is frontend/.

Read the root CLAUDE.md first for the branch model, deploy contract and image names.

Build & verify

• make test — builds a py3.12 venv and runs the hermetic pytest suite (scripts/test.sh; pass ARGS=...). Tests are hermetic per tests/conftest.py: no real Open-Meteo/Nominatim/GeoNames calls, throwaway SQLite, notifier thread disabled.
• make smoke — boots the built image plus a throwaway db and asserts /healthz + /api/version.
• CI runs this suite inside the built image (build.yml), so the exact interpreter and deps that ship are what gets tested.

app.py at the root is a one-line re-export shim for web/app.py, kept stable for systemd/CI callers. Entry target is app:app.

Contracts that break silently if you change them

• GET /api/version → {backend_version, min_frontend, payload_ver}, driven by API_CONTRACT_VERSION and MIN_SUPPORTED_FRONTEND in web/app.py. A breaking change ships as a new v3 router mounted alongside v2, re-registering only changed handlers, with the constant bumped in the same PR. /api and /api/v1 stay mounted as aliases.
• PAYLOAD_VER (api/payloads.py) is separate from URL versioning — it is the cache/ETag invalidation token. Bump it whenever a response payload's shape changes, so one bump atomically orphans every pre-upgrade cached row.
• ETag / If-None-Match — every graded payload is cached against a validity token that doubles as a weak ETag. expose_headers=["ETag"] in the CORS middleware matters as much as allow_origins: without it the frontend's cache.js reads null cross-origin and never revalidates. Don't change the ETag derivation or that list without checking frontend/static/cache.js.
• data/grading.py::pct_ordinal() is mirrored by frontend's server/internal/format::PctOrdinal (SSR) and static/shared.js::pctOrd() (browser) — floor a percentile into 1..99, never 0 or 100. TEMP_BANDS/RAIN_BANDS are the source of truth for tier names and thresholds; changing them without the frontend produces tiers drawn in colours that disagree with the labels the API returns.
• Fahrenheit country set — api/content_payloads.py's F_COUNTRIES is canonical; frontend's server/internal/format::FCountries and static/units.js's F_REGIONS must stay identical to it. Both are asserted by tests in frontend/server/internal/format/format_test.go — but note the backend cross-check skips in CI (the frontend image's build context is frontend/, so this file is unreachable from the builder stage, which is the only place CI runs those tests). It fires on a full checkout. The units.js check does run in the image build. frontend/format.py's copy is the superseded Python service's and is not deployed.
• /healthz and /api/version are deliberately I/O-free so they stay cheap under tight healthcheck intervals.

Layout

accounts/ (fastapi-users + alembic), api/ (payload builders + SSR content routes), core/ (metrics, audit, singleton helper), data/ (grid, climate fetch/cache, grading/scoring, places/cities, derived-payload store), notifications/ (push, email, Discord bot, digest, scheduler), web/app.py (the real app), daemon/.

paths.py resolves every filesystem location from the repo root — don't reintroduce __file__-relative paths in a module; it breaks the moment a module moves. deploy/entrypoint.sh is the container entrypoint (alembic migrate, then serve, with a Swarm-secrets-as-files shim).

Commits & PRs

Concise and technical. Never mention AI, assistants or automated authorship.