System Architecture¶

Overview¶

Algol is a multi-process edge platform. All inter-process communication goes through NATS. Each module is an independent process that connects to the NATS broker on startup.

/-------------\  /-------------\  /--------------\  /--------------\
|   board-    |  |     gps     |  |    (other    |  |   (modules   |
| controller  |  |             |  | data source) |  |   & events)  |
\------+------/  \------+------/  \------+-------/  \------+-------/
  data/data_status  data/data_status  data/data_status  status/event2
       \-----------------+-----------------+----------------/
                                   |
                             /-----v------\
                             |    NATS    |  <- central broker
                             \-----+------/
              /------------------+-+--------------\
   status / data_status / event2 |                |
        /-----v-------\   /------v------\  /------v------\
        |   trigger   |   |   flower    |  |    gate     |
        \-----+-------/   |(measurement |  | (cloud fwd) |
              |           |coordination)|  \-------------/
    /---------|           \------+------/
    | actions |                  |
    |- measurement --------------/
    |- cmd -> any component
    |- event -> NATS
    \- patchConfig -> configurer
                    |
          /---------v----------\
          |      recorder      |
          |(parquet, catalog,  |
          |     export)        |
          \--------------------/

Communication¶

Every message belongs to a messaging context that defines its subject prefix and semantics. The full subject pattern is:

local.<moduleId>.<context>.<componentName>.<componentId>

Context	Description
`data`	Raw batched sensor samples published by data sources. Internal transport - not directly matchable by triggers.
`data_status`	Per-batch column statistics (min, max, sum, count) derived from each `data` batch. The matchable form of sensor data.
`status`	Periodic aggregate telemetry from modules - snapshots of component state (health, counters, computed values). Every field is listed in the Telemetry Reference.
`event2`	Discrete one-time occurrences (something happened). Typed envelope `{time, data}`. See Events.
`measurement`	Measurement lifecycle signals (start, extend, stop) exchanged between `trigger` and `flower`.
`config`	Configuration updates applied to components.
`config_status`	Validation result published after a config update.
`cmd`	Request-reply commands targeting a specific attribute: `local.<moduleId>.cmd.<componentName>.<componentId>.<verb>`

The on-device event context is retired. Gate still forwards event2 onto the cloud event subject. The recording and archive contexts are unused: the recorder publishes recording_completed on event2 and serves inventory through the catalog endpoints.

See Messaging for subject conventions, request-reply endpoints per module, and how the CLI maps onto them.

Actions on RET¶

The trigger module is the primary mechanism for executing any action in response to live data on a RET device. Trigger expressions can subscribe to exactly three contexts: status, data_status, and event (which reads event2). Raw data messages cannot be matched directly - use data_status to access sensor data in aggregated (per-batch) form.

Modules¶

Each module is a process with a NATS module id (often overridable with --id). See Modules for the inventory, the configs and events each one owns, and its request-reply endpoints.

Shared design pieces used across modules:

Piece	Purpose
Component references	Addressing: `moduleId.componentName.componentId`
Messaging	Wire types: subjects, context types, component status, telemetry measurements, events

The component and messaging libraries are also published as versioned modules for Algol Cloud. See Shared Modules.