# A tour of the architecture

Diyar's architecture keeps one rule absolute: the edge is the only thing that can ever actuate. Everything else — cloud, on-prem gateway, client surfaces — sits around that boundary without ever crossing it.

## The edge

The edge is a single static aarch64 binary running on the field device, deployed under systemd. It is:

- The **sole actuation authority** — nothing else in the system holds a primitive that can energize hardware.
- The **sole evidence authority** — it owns the local, tamper-evident hash chain that every reading is journaled into before anything is published.
- Fully capable of running **offline** — a run completes with no cloud, no network, and no operator phone reachable.

Underneath the edge binary, a hardware abstraction layer (`TempSource` / `RelayBank` / `MonotonicClock`) is the seam a new physical device implements; the `VerdictEngine` trait is the seam a new solution implements (Unit 2). The edge also hosts a local MCP agent surface, and — where deployed — a loopback `agent-gateway` process fronting the same REST API a human operator uses, gated by an operating-mode state machine (Manual by default).

```text
Operator ──┬─ kiosk (LAN)                 ┌──────────────────────────────┐
           ├─ web / mobile ──── signed ──▶│ EDGE  (single aarch64 binary)│
           │                     start    │  • sole actuation authority  │
           └─ web terminal ──▶ massar ───▶│  • local evidence hash chain │
                              (dial-out)  │  • fail-safe interlock       │
   ┌─────────────────────┐   evidence     │  • MCP agent surface (local) │
   │ CLOUD / ON-PREM     │◀── batches ────└──────────────┬───────────────┘
   │  • fleet + shadow   │   (outbox)                    │ HAL seam
   │  • re-derives chain │                    ┌──────────┴──────────┐
   │  • RLS multi-tenant │                    │ local ADC + relays  │
   │  • never actuates   │                    │ or Modbus TCP / RTU │
   └─────────────────────┘                    └─────────────────────┘
```

> [!IMPORTANT]
> Real hardware acquisition is deliberately gated: `DIYAR_HAL=real` refuses to start pending hardware-in-the-loop characterization of the probe chain (the ADC exposes 8 single-ended inputs, which does not yet reconcile with the platform's wider reading set, and per-channel calibration is a metrology task, not a code default). A physical Modbus field device similarly runs a boot preflight and then stops — exit code 2 — until a bench validates its register map and comms-loss watchdog. Both fail loudly by design rather than guessing at unverified values.

## The cloud / on-prem control plane

The control plane — whether run in the cloud or on an on-prem gateway — owns the registry, enrollment, evidence intake, fleet reconciliation, and dispatch. Its deployable services, as they appear in the platform's own day-2 operations runbook:

| Service | Role |
|---|---|
| `diyar-ingest` | evidence firehose: idempotent, tenant-isolated writes plus tamper gates |
| `diyar-cloud` | control plane: enrollment, fleet, alarms, device shadow |
| `diyar-reconcile` | always-on interior-gap scan; pages on divergence |
| `diyar-dispatch` | drains the notification outbox, delivers signed webhooks |
| `diyar-provision` | converges resource provisioning on a scan loop |

**Authority is one-directional.** In the control plane, the cloud can request, advise, and mirror state — it holds no primitive that energizes anything. The device twin's desired-state is config-class only (things like OTA channel, sampling interval, log level), and there is deliberately no broadcast actuation primitive anywhere in the system: mass remote ignition is the top threat the design guards against.

## Running a site fully disconnected

A site does not have to depend on the public cloud at all. The on-prem gateway bundle (`deploy/compose.gateway.yml`) runs the same control-plane and ingest services against a local TimescaleDB with pgBackRest for point-in-time recovery, Caddy for TLS, `step-ca` as the device certificate authority, and a mutually-authenticated MQTT broker (`rumqttd`, MQTT 3.1.1) for LAN devices. A site can run entirely disconnected from any public cloud this way.

## Client surfaces

Operators reach a device through a kiosk (local, LAN), a web or mobile client (remote, signed start), or an audited terminal session dialed out through Massar — a small on-device agent that opens outward to Diyar's console broker so an operator gets a session with no inbound port and no VPN, and no standing shell outside an explicitly-opened, RBAC-gated, TTL-bounded session.

> [!WARNING]
> The kiosk and web portal are early: each currently ships as a minimal stub, not a full interface. Diyar's client strategy schedules the richer React web interfaces for later build phases, so treat any screenshot of a rich kiosk or portal UI as forward-looking, not current state. The cloud's view of a device is also after-the-fact: it shows evidence that has already synced, not a live view of a running session.

## Extension seams, summarized

Two seams carry all future growth without touching the frozen safety core: the hardware abstraction layer for a new physical device, and the `VerdictEngine` trait for a new certified process rule. Everything from Unit 2 — a new solution, a new device profile — is expressed through one of these two seams.