Overview
Heartbeat — what it is, who it's for, how to navigate these docs.
Heartbeat is Satchel's TV cockpit — a single screen that shows the state of the business in red-zones-first order, refreshes itself, and catches silent failures before they cost money. It pulls from every source system Satchel runs on (webbank, AML, PDVS, VSS, card management, currency rates) and surfaces one number per question that matters.
These docs are the single source of truth for the project — product, lifecycle, sources, decisions, operations. Every new feature, product decision, user scenario, or behavioural change updates a page here in the same PR as the code. CLAUDE.md and the repo README are thin pointers into this site; ARCHITECTURE.md has been retired.
Where to start
| You want to… | Read |
|---|---|
| Understand the pipeline, data contract, principles | Architecture |
| Know what's landed, what's pending, how sources are organised | Sources |
| Add, tune, audit, or retire a metric | Metrics |
| See how a metric goes from idea to a verified tile | Metric lifecycle |
| Understand how the audit pages are built | Audit cuts |
| Ship a change to the VM | Operations › Deploy |
| Look up a past architectural choice | Decisions |
| See what's coming next | Roadmap |
| Browse the live API spec | API reference |
How to read the cockpit
The home page (/) is a grid of metric tiles. Each tile shows:
- a number (today's value),
- a status pill —
red,amber, orgreenagainst the metric's thresholds, - a sparkline of recent history,
- a methodology hover so you know exactly what's being counted.
Green metrics fade. Red metrics surface. The principle is "show me what's broken, not what's fine".
Tiles ship unverified by default — the dashed border + pill
mean a number is computing and visible, but no owner has yet
cross-checked it against reality. That's the
expected normal state
for most tiles; verification happens naturally the first time the
tile crosses red.
Two surfaces, one data model
| Surface | What it answers | Lives at |
|---|---|---|
| Cockpit | Is anything red right now? | / |
| Audit | Why is this number what it is? | /audit/{revenue,clients,journeys} |
Both read from the same Postgres marts (heartbeat.metric_history,
heartbeat.audit_cut_snapshot). Audit pages are narrative — they
break a topic into cuts, each cut a small chart
with prose, so you can scroll the page and understand the story.
Updating these docs
This site is part of the same Next.js app as the cockpit; pages live
under dashboard/content/docs/ as MDX. To update a doc, edit the
file and ship it through the standard
deploy flow (the web service rebuild
picks the change up).
Every page should answer one question. When you add a new feature or make a product decision, ask: which existing page does this belong in? If none, add a new page and link it from architecture and the Overview.