TelemetryMonitor/ARCHITECTURE.md

# Architecture

This document describes the design of the Telemetry Monitor application.
Read it before making non-trivial changes.

## Goals

- Smoothly render up to 16 rolling charts at 60 Hz from a 1 kHz packet stream.
- Run identically on Linux, Android, and Web from one codebase.
- Provide CSV export, scrollback, zoom, and pause without coupling these
  features to each other.
- Stay maintainable: small modules, clear data flow, single sources of truth.

## High-level data flow

    WebSocket
       │ Uint8List frames
       ▼
    TransportLayer ──── ValueListenable<WsConnectionState>
       │ Stream<Uint8List>
       ▼
    DecoderLayer (isolate on native, inline on Web)
       │ Stream<Envelope>
       ▼
    SessionController
       ├── PacketBuffer (ring, ~10 min @ 1 kHz)
       ├── LogBuffer (ring, ~5k entries)
       ├── ViewState (window, anchor, userPaused)
       ├── PpsCounter (sliding 1s arrival times)
       ├── Ticker (vsync) ──┬─► frameTick (ValueNotifier<int>)
       │                    └─► statusSnapshot (recomputed per frame)
       └── logTick (ValueNotifier<int>, fires per new log)

    UI layer subscribes to the notifiers above:
       - ChartGrid → ChartWidget (CustomPainter, repaint: frameTick)
       - StatusBar → statusSnapshot, connectionState
       - ErrorLogPanel / FullLogTab → logTick
       - Toolbar → ViewState, dialogs

## Layers

### Transport (`lib/transport/`)

Abstraction over `web_socket_channel` so the rest of the app doesn't know
about platform-specific channels.

- `WebSocketTransport` (abstract): `connect`, `disconnect`, `frames`, `state`.
- `websocket_transport_io.dart`: native, uses `IOWebSocketChannel`.
- `websocket_transport_web.dart`: Web, uses `HtmlWebSocketChannel`.
- Conditional import via `websocket_transport.dart`.

Owns reconnection with exponential backoff. Reconnect parameters configurable
in Settings.

### Decoder (`lib/decoder/`)

Turns raw frames into `Envelope` messages.

- `Decoder` (abstract): `feed(Uint8List)`, `envelopes` stream.
- `decoder_isolate.dart`: native. Spawns an isolate that decodes and
  accumulates envelopes, sending them back as a `List<Envelope>` every
  ~8 ms (configurable). Reduces SendPort overhead at 1 kHz.
- `decoder_inline.dart`: Web. Decodes synchronously in `feed()`.
- Conditional import via `decoder.dart`.

The 8 ms batch interval is chosen to be half a frame at 60 Hz, ensuring no
batch ever crosses a frame boundary unobserved.

### Session (`lib/session/`)

Central state owner.

- `PacketBuffer`: fixed-capacity ring of `DataPacket`. Supports binary search
  by timestamp and iteration over a time range.
- `LogBuffer`: fixed-capacity ring of `LogPacket`.
- `ViewState`: window width (Duration), anchor (followLive | absolute(t)),
  userPaused. Window-clamping logic lives here. Does *not* hold proto-pause.
- `PpsCounter`: `Queue<DateTime>` of arrival times, popped to a 1-second
  window. PPS = queue length.
- `Decimator`: per-channel min/max decimation with LRU cache keyed on
  `(viewStart, viewEnd, pixelWidth)`. Also computes gap segments classified
  as "hatched" (≥ pixel width) or "marker" (< pixel width). Marker pixel-x
  positions are deduplicated.
- `SessionController`: owns the above, subscribes to the decoder stream,
  drives the Ticker, exposes notifiers.

#### Status snapshot computation (per frame)

`StatusSnapshot { connection, pps, statusValues[8], protoPaused }` is
recomputed each frame by walking backward through the packet buffer up to
`settings.statusLookback` packets, collecting the most recent value for each
of the 8 status fields and the pause flag. Fields not seen within the
lookback window are reported as `null` (rendered as "unknown" in the UI).

This guarantees single-source-of-truth: the buffer is the only store. The
walk is bounded and stops early once all 9 fields are resolved.

#### Pause composition

`isPaused = userPaused || (statusSnapshot.protoPaused ?? false)`

The status bar attributes the pause source by inspecting both flags.

#### Clear-all

`clearAll()` empties both buffers, resets the PPS counter, and forces the
view back to live mode. The status snapshot becomes all-null on the next
frame (since the buffer is empty), which is correct.

### Layout (`lib/layout/`)

Display configuration. Persisted to `shared_preferences` under `layout.*`.

- `ChartConfig`: per-chart settings — channel ID, enabled flag, name,
  Y mode (auto / fixed / userZoomed), yMin, yMax.
- `GridConfig`: rows, cols, cell-to-channel mapping.
- `LayoutController` (`ChangeNotifier`): owns the above plus the 8 status
  indicator names. Provides `loadFromPrefs` / `saveToPrefs`.

### Export (`lib/export/`)

CSV writers behind a platform-split interface.

- `CsvExporter` (abstract): `exportData`, `exportLog`.
- `csv_exporter_io.dart`: native. Uses `path_provider` for save location.
- `csv_exporter_web.dart`: Web. Builds a Blob and triggers a download via
  an anchor element.
- Both yield to the event loop between chunks (chunk size ~1000 rows) and
  report progress via callback.

#### Data CSV format

Columns: `timestamp_us, ch1, ch2, ..., ch16, pause, status1, ..., status8`.
Disabled channels are *omitted from the column set*. Missing values within
included columns appear as blank cells. Pause and status values appear as
integers (or blank if absent in that packet).

#### Log CSV format

Columns: `timestamp_us, severity, error_number, description`. The description
field is taken verbatim from the proto. Severity is the enum name.

### UI (`lib/ui/`)

- `app.dart`: MaterialApp, providers (via plain `InheritedNotifier`).
- `toolbar.dart`: pause, go-live, reset-view, layout, settings, export-data,
  clear-all, zoom readout.
- `tab_scaffold.dart`: tabs (Dashboard, Full log).
- `chart_grid.dart`: builds `ChartWidget` per cell from `LayoutController`.
- `chart_widget.dart`: `RepaintBoundary` + `CustomPaint` (painter listens to
  `frameTick`).
- `chart_painter.dart`: per-frame draw — decimation, gaps, line, axes, labels.
- `status_bar.dart`: connection pill, PPS, pause indicator with attribution,
  8 status pills (subscribes to `statusSnapshot`).
- `mini_log_panel.dart`: filtered log view (severity from settings).
- `full_log_tab.dart`: chip-filterable log view + log export button.
- `settings_dialog.dart`, `layout_dialog.dart`: configuration UIs.

## Persistence keys

Both stored in `shared_preferences`:

| Prefix       | Owner               | Contents                          |
| ------------ | ------------------- | --------------------------------- |
| `settings.*` | `Settings`          | WS URL, buffer caps, decoder/reconnect params, mini-log severity set, status lookback |
| `layout.*`   | `LayoutController`  | Grid shape, per-chart config, channel names, status names |

## Frame budget at 1 kHz / 60 Hz

Per frame (16.6 ms):

- Decoder isolate has already produced ~16 packets, batched to one SendPort message.
- Main isolate writes those packets to `PacketBuffer` (16 × O(1) writes).
- Ticker fires.
- `statusSnapshot` walks back ≤ 1000 packets × 9 fields, stops early when
  all resolved. Typically completes in 1 step.
- 16 charts repaint:
  - Each looks up its decimation cache.
  - On cache hit: just draws ~400 line segments.
  - On cache miss (zoom/pan): re-decimates (one pass over visible packets per channel).
- Status bar reads `statusSnapshot` and renders.

Total CPU per frame is dominated by chart drawing, which Skia/Impeller handle
well. Cache hit rate is ~100% in live-follow mode (the tail extends, prior
columns are unchanged) and drops only during zoom/pan.

## Threading model

- Native: 2 isolates. Main runs Flutter and everything except protobuf
  decoding. The decoder isolate parses bytes and emits envelope batches.
- Web: 1 isolate. Decoder runs inline on the main isolate. At 1 kHz with
  small protobuf messages this is acceptable; if it becomes a bottleneck,
  consider Web Workers via JS interop (significant work).

## Conditional imports pattern

Each platform-split module follows:

    // foo.dart (the public import)
    export 'foo_io.dart' if (dart.library.html) 'foo_web.dart';

    // foo_io.dart — native impl
    // foo_web.dart — web impl

This means UI code just `import 'foo.dart'` and gets the right one.

## Non-goals

- Multiple simultaneous WebSocket connections.
- Server-side filtering or downsampling.
- Recording to disk continuously (export is on-demand only).
- Per-chart x-axis (X is global).
- Internationalization (English only for now).