Algol Terminology¶

Canonical reference for terms and concepts used throughout the Algol platform. Referenced by CLAUDE.md and README.md.

Platform Overview¶

Algol Platform - The whole universe of Algol: devices, cloud, ideas, algorithms, etc.

Algol Cloud - Analytics and device management for field-deployed Algol devices.

Algol Software - The software running on the device.

RET (Rail Edge Telemetry) - A device series deployed in the field, typically for sensor measurement and recording.

RAR (Robust Automotive Router) - A device series deployed in the field, typically for gateway and remote-access roles.

Multi-Tenancy¶

Tenant - Top-level isolation boundary per customer.

Workspace - A logical partition within a tenant for organizing data, devices, and configurations (like a project). A tenant can have multiple workspaces.

Devices & Identity¶

Device - A physical device deployed in the field (RET, RAR, or similar), identified by a unique device ID (e.g. mobgpx181).

User key - A person's identity on the device bus: a key, carrying a label and a role (RFC-034 D2). A CLI user's laptop key, a script's key, a web user's key, and the boot's root key are each one. Its counterpart is a module key, which names a module rather than a person and carries no role; the two are published as nats.userkeyinfo.<key> and nats.modulekeyinfo.<key>, and which one answers for a key is what decides whether a write is checked against a role at all.

The word operator in this repo means the human working on the device, not their key - "an operator plugs in a stick", "operator intent". It named the key class until 2026-09-05, which is why older prose may still read that way.

Role - A named set of rights a person holds, on both doors (the CLI and the web UI). Two are built in and reserved:

keymaster - everything, including the auth verbs that change the identity registry (algol nats ls | enrol | revoke). It holds the keys, which is what the name says. Host root is one every boot.
superuser - everything except those verbs.

Every other role is a cfg.role.<name> config naming what its holders may read, patch and write (RFC-035). admin and operator are not built in - they are ordinary configured names, deliberately left free for a deployment to use for its own roles and logins.

Component System¶

All addressable entities in Algol are identified by a Component Reference.

Component - A uniquely addressable unit identified by a three-part dot-separated reference:

{moduleId}.{componentName}.{componentId}

Example: gps.channel.position, adc.channel.ain2, bbc.bcapp.main

ComponentGroup - A partial component reference identifying a module + component type, without a specific instance:

{moduleId}.{componentName}

Example: gps.channel, adc.channel

ModuleId - The top-level system or module identifier (e.g., adc, gps, bbc).

ComponentName - The component type within a module (e.g., channel, app, sensor).

ComponentId - The specific instance identifier within a component type (e.g., ain2, position, main).

Attribute - A named field within a component, identified by appending the field name to a component reference:

{componentRef}.{attributeName}

Example: gps.channel.position.lat, adc.channel.ain2.value

Measurement System¶

Measurement - A data collection with a precise start time and eventually an end time. Triggered (and extended when needed) on the device by certain conditions (e.g. gps.channel.direction.speed > 0.2).

Measurement ID - Unique identifier for a measurement (e.g. FfdbMaYBcRVZBPHYVKSdaKYKZe).

Sequence Number - A monotonically increasing counter per device per measurement, independent of time (e.g. 0000JVXdECy).

Recording - A persisted segment of a measurement, split by (device, measurement id, channel, part), stored in a specific format (e.g. parquet).

Data Concepts¶

Sensor - A physical or logical sensor managed by a Data Source. Examples: GPS module, IMU, pressure sensor, magnetic field sensor.

Data Source - Responsible for managing its sensors/channels and publishing data. Samples from a single Data Source share a common timestamp per sampling cycle. A Data Source advertises its channels periodically.

Data Stream - A continuous flow of time-stamped data.

Data Frame - A batch of samples, typically with time information attached.

Data Channel - A named, typed bundle of Data Columns from a Data Stream. Managed and advertised by a Data Source. Identified by a Component Reference (e.g. gps.channel.position).

A channel requires at least one columnSelector processor. Processors handle transformations, resampling, and validation of incoming Data Frames. Channels can be (re-)configured at runtime.

Channel Type - Classifies the shape and semantics of a channel's columns: - Scalar - Numeric values (default) - GeographicCoordinate - GPS position data (lat, lon, alt) - GPSVelocity - GPS direction data (speed, track, climb) - CartesianCoordinate - Cartesian coordinates (x, y, z - e.g. gyro, accelerometer) - MonoPCMAudio16 - PCM 16-bit mono audio

Channel Column - A single named column within a channel. Columns within the same channel share a timestamp (that's the reason for bundling them). Also referred to as subchannel in some contexts. Example: lat, lon from the gps.channel.position channel.

Channel Reference (ChannelRef) - The Component Reference of a Data Channel (e.g., adc.channel.ain2, gps.channel.position).

AggChannelColumn - A channel column with an aggregation function applied (e.g., adc.channel.ain2.value:min).

Channel Examples¶

ChannelRef	Type	Columns
`gps.channel.position`	`GeographicCoordinate`	`lat` (deg, float64), `lon` (deg, float64), `alt` (m, float64)
`gps.channel.direction`	`GPSVelocity`	`speed`, `track`, `climb`
`adc.channel.ain0`	`Scalar`	`ain0` (raw, uint32)
`pressure.sensor.main`	`Scalar`	`pres` (mbar, float64), `temp` (degC, float64)

Data Processing¶

Aggregation - Statistical operation applied to time-series data. Supported: min, max, count, sum.

Unified Data Format¶

All data sources publish data in a columnar, batched format over NATS, supporting: - Column-based data with named typed columns - Meta information (stats, row count, column names, types, sampling rate) - Batching (e.g. 10k samples per message)

Supported column types: float64, int32, uint32, unix nanosecond timestamp.

Advertisement¶

Advertisement - A periodic broadcast of a component's configuration (channel config, trigger config, etc.) over NATS to ensure other components have up-to-date knowledge before they need it (e.g. before starting a measurement or applying reconfiguration).

Trigger System¶

Trigger - A rule consisting of a match condition and an action. When the match is satisfied, the action executes (e.g. start a measurement, run a command). Triggers advertise their configuration periodically.

Events¶

Event - A discrete one-time occurrence on the event2 context (local.<module>.event2.<eventName>.<entityId>). An event announces that something just happened; current state lives on config status or periodic telemetry. Events are not durable. See Events.

Configuration¶

Configuration Store - The central service for managing component configurations (owned by the configurer). Key operations: - Update - updates the running configuration for a given component - Commit - persists the latest intent of non-read-only configurations to disk for use on next startup, whether or not the module has answered it

Bundle - The per-config attribution and exclusivity key, carried next to managedBy on the config record and startup file: a name one Bundle Variant at a time occupies. It has no file of its own and no config-store presence; it exists while a variant of it is installed or a running config carries its stamp. Set only by the bundle verbs: an activation stamps the members it places or adopts, and bundle update --adopt stamps the refs it adds (taking one over from another bundle only with --force) and unstamps the refs it removes. See RFC-014.

Bundle Variant - One installed set of configs of a Bundle, stored as one file (/var/algol/cfg/bundles/<bundle>@<variant>.json), installed inert and activated explicitly. Several variants of one Bundle may be installed and activating one evicts what another placed; "active" is derived per variant from the content, never stored. Variants are unordered - retx@v1 / retx@v2 are alternatives, bcapp@1.0 / bcapp@1.1 succeed one another, and only the author's naming says which.

Bundle Address - <bundle>@<variant>, how a Bundle Variant is named on the command line, in a manifest key and in a file name (retx@v2). A bare bundle addresses every variant of it, which some verbs accept. Unrelated to component addressing: a variant is not a component ref part and never appears in a component ref or a NATS subject.

Manifest - The transport artifact for configuration: bundle variants + an ordered activation intent + optionally plain device config. The only artifact that travels (a single variant ships as a one-variant manifest); also the backup/restore form. Distinct from the usbexport destination manifest (RFC-024).

Unattributed - A config no bundle placed (no bundle stamp). The default state of every config, and the state bundle update --remove --adopt returns a member to; invisible to teardown (config delete --bundle) and claimable only via explicit adoption (bundle activate --adopt, bundle update --add --adopt).

Key Modules¶

Module	Role
`board-controller`	Controls the MCU on board
`configurer`	Configuration management (disk persistence)
`gps`	GPS module control, positional data
`nats`	Central NATS communication broker
`trigger`	Trigger management
`sys`	System management (network, GSM, DNS, ...)