# Overview (/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 [#where-to-start]

| You want to…                                                  | Read                                           |
| ------------------------------------------------------------- | ---------------------------------------------- |
| Understand the pipeline, data contract, principles            | [Architecture](/docs/architecture)             |
| Know what's landed, what's pending, how sources are organised | [Sources](/docs/sources)                       |
| Add, tune, audit, or retire a metric                          | [Metrics](/docs/metrics)                       |
| See how a metric goes from idea to a verified tile            | [Metric lifecycle](/docs/metrics/lifecycle)    |
| Understand how the audit pages are built                      | [Audit cuts](/docs/audit-cuts)                 |
| Ship a change to the VM                                       | [Operations › Deploy](/docs/operations/deploy) |
| Look up a past architectural choice                           | [Decisions](/docs/decisions)                   |
| See what's coming next                                        | [Roadmap](/docs/roadmap)                       |
| Browse the live API spec                                      | [API reference](/docs/api)                     |

## How to read the cockpit [#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`, or `green` against 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](/docs/metrics/lifecycle#6-unverified-—-the-handover-state)
for most tiles; verification happens naturally the first time the
tile crosses red.

## Two surfaces, one data model [#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](/docs/audit-cuts), each cut a small chart
with prose, so you can scroll the page and understand the story.

## Updating these docs [#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](/docs/operations/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](/docs/architecture) and the [Overview](/docs).