Heartbeat · Pulse

The network's breathing — an append-only event log, a pulse worker, and the components that make its state visible at a glance.

---

.. toc::

The event log is the truth

Everything the heartbeat knows is an event: a small JSON record with a UTC timestamp, a kind (tick, task_start, task_end, api_call, error, note), a phase (idle, working, error), and a task slug. Events append to data/heartbeat/events.jsonl (never rewritten, except by the nightly prune) and mirror best-effort into Postgres.

Every dashboard number derives from this log — nothing is stored twice, so nothing can disagree. On the hub, an api_call is an outbound HTTP probe (a satellite check, the wallet-provision POST) and carries target / status / ok / latency_ms in its extras.

The dial

The HeartbeatPulse component is pure DOM + CSS — three nested rings whose animation cadence and color follow the phase:

.. exec::docs.heartbeat.pulse_examples

The rhythm bar

One cell per minute; the fill height encodes total events, the colored stack encodes kinds (error on top — the loudest thing wins the eye). Tooltips are CSS pseudo-elements, not component tooltips: 120 React portals re-rendering every second destabilized the original page, and a data-tooltip attribute costs nothing.

.. exec::docs.heartbeat.rhythm_examples

Process ownership

One environment flag decides who runs the pulse:

• Dev (no flags): the web process runs the tick loop, the job

dispatcher, everything — off shared JSONL.

• Prod: the web sets HEARTBEAT_PULSE_WORKER=1 and defers; the

2plotai-pulse sidecar owns the pulse, the APScheduler, and the dispatcher. The web reads the worker's state through the Postgres mirror — separate containers share no filesystem.

.. admonition::Truthful by construction :icon: tabler:scale :color: teal

The control board's liveness badge derives from the last tick's age in the shared log — not from any process's in-memory flag — so it tells the truth no matter which container did the ticking.

Live updates

The dashboard streams over Server-Sent Events on the FastAPI backend (/api/heartbeat/stream, owner-gated) and falls back to interval polling everywhere else. WebSocket callbacks stay off app-wide.

.. llms_copy::Heartbeat · Pulse

---

*Source: /docs/heartbeat-pulse*