---
name: thermograph-orientation
description: What Thermograph is as a product and a business, how the estate is shaped, and the principles behind how it is run.
---

# Thermograph, from the top

## The product

Thermograph answers one question for any point on Earth: **how unusual is the
weather right now, here?** It grades recent and forecast conditions against ~45
years of local climate history (1980–present, ERA5), turning raw numbers into a
percentile and a plain tier — Normal, Above/Below Normal, High/Low, Near Record.

The mechanic: a clicked or searched location snaps to a stable **~4 sq mi grid
cell**; that cell's full daily history is fetched once and cached. Each day is
placed on *its own* day-of-year ±7-day window as an empirical percentile. So
"97th percentile" means hotter than 97% of the last ~45 years of this same
fortnight, at this exact spot.

Precipitation is graded differently, because most days everywhere are dry:
a day with measurable rain is ranked only among the **rain days** in its window,
spreading wet days across intensity tiers. Dry days are coloured by dry streak
instead.

### The framing rule

Grade names are **relative to each location's own climate**, never absolute
temperature words. A 60°F day can be Above Normal in a cool coastal summer and
Below Normal in a hot inland one; the same day can be Near Record for January
and ordinary for July. Calling a percentile "hot" or "warm" implies a scale the
data does not carry. Every grade means "unusual **for this place, this time of
year**." Preserve that in any copy, summary or chart you produce.

## Who it is for

- **Weather-curious people** — "is this heat actually unusual here, or does it
  just feel that way?" The answer is a defensible percentile against that exact
  location's history, not a national average.
- **Movers, travellers, planners** — the city climate pages and compare view.
- **Alert subscribers** — told when their place crosses into genuinely unusual
  territory, without daily noise.

## What exists

Map and grade view, a two-year calendar heatmap, single-day breakdown, location
compare, ~750 SEO-indexed city climate pages, a PWA with an offline shell.
Accounts are optional and exist to power alerts: per-location subscriptions on
any metric with a percentile threshold, delivered by in-app bell, Web Push,
or Discord DM, with a weekly cap and per-event dedup so one alert is at most one
notification a week. A versioned public JSON API (`/api/v1`, `/api/v2`).

**What deliberately does not exist:** any monetisation — no plans, ads or paid
tiers — no native mobile apps, and no user analytics beyond anonymous counters.

## The estate

Four machines on a WireGuard mesh:

| Machine | Runs |
|---|---|
| **prod** (48 GB VPS) | thermograph.org, the Swarm app stack, TimescaleDB, Postfix for the whole fleet, nightly backups |
| **beta** | beta.thermograph.org, Forgejo (git + registry + CI), Grafana + Loki |
| **desktop** | LAN dev server, the main CI runner, working checkouts |
| phone | terminal only; hands work off via git |

`emi/thermograph` is a monorepo (`backend/ frontend/ infra/ observability/`)
with per-domain CI. `thermograph-docs` is separate — the planning layer, on its
own cadence.

## How it is run

One owner/operator, plus provisioned automation agents that work through exactly
the same door as a human: branch → PR → required CI → explicit merge. The
guardrails live in the platform rather than in anyone's memory.

The principles, as actually practised:

1. **Own the whole stack.** Georedundant SaaS replaced by two VPSes, a desktop
   and discipline. The whole estate costs less monthly than one managed database.
2. **Privacy as a feature.** No tracking cookies, no per-visitor IDs, allowlisted
   anonymous counters only. Cheap to keep, expensive to retrofit.
3. **Boring prod.** Anything clever proves itself on dev or beta first; prod
   changes arrive only as already-proven image tags.
4. **Everything is a PR.** Human or agent, infra or app or docs.

## Where to look next

- `docs_search` — architecture decisions, runbooks, and the business layer
  (product overview, operating model, costs, roadmap).
- `notes_search` — what people wrote down along the way.
- `skill id="thermograph-ops"` — deploying and debugging.
- `skill id="thermograph-community"` — Discord.
- `skill id="thermograph-notes"` — where written work belongs.