From e4fd1411ad85f0615dd18285e650face12b66e11 Mon Sep 17 00:00:00 2001 From: mikael-lovqvists-claude-agent Date: Wed, 25 Mar 2026 23:02:20 +0000 Subject: [PATCH] Correct control plane description: no hub, controller is a node role MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No central message hub or broker. Controller is a function_flags bit — any node with a user interface (e.g. web UI) holds it. Multiple nodes can hold the role simultaneously. Controller communicates directly with peers over the binary protocol; no intermediary. Co-Authored-By: Claude Sonnet 4.6 --- architecture.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/architecture.md b/architecture.md index 9187767..f7b9839 100644 --- a/architecture.md +++ b/architecture.md @@ -62,11 +62,13 @@ Priority is a property of the *path*, not of the source. The same source can fee ## Control Plane -A central **message hub** coordinates the graph. Nodes self-register with an identity (`origin`, `function`, `description`) and communicate via unicast or broadcast messages. +There is no central hub or broker. Nodes communicate directly with each other over the binary transport. Any node can hold the **controller role** (`function_flags` bit 3) — this means it has a user-facing interface (such as the web UI) through which the user can inspect the network, load a topology configuration, and establish or tear down connections between nodes. -The hub does not dictate topology — nodes announce their capabilities and the controller assembles connections. This keeps the hub stateless with respect to stream routing; it only routes control messages. +The controller role is a capability, not a singleton. Multiple nodes could hold it simultaneously; which one a user interacts with is a matter of which they connect to. A node that is purely a source or relay with no UI holds no controller bits. -The hub protocol is newline-delimited JSON over TCP. V4L2 device control and enumeration are carried as control messages within the encapsulated transport rather than on a separate connection — see [Transport Protocol](#transport-protocol). +The practical flow is: a user starts a node with the controller role and a web interface, discovers the other nodes on the network via the multicast announcement layer, and uses the UI to configure how streams are routed between them. The controller node issues connection instructions directly to the relevant peers over the binary protocol — there is no intermediary. + +V4L2 device control and enumeration are carried as control messages within the encapsulated transport on the same connection as video — see [Transport Protocol](#transport-protocol). --- @@ -74,14 +76,12 @@ The hub protocol is newline-delimited JSON over TCP. V4L2 device control and enu ```mermaid graph LR - CAM[V4L2 Camera\ndev/video0] -->|raw MJPEG| PI[Pi: forward over TCP\nno processing] - PI -->|TCP stream| INGEST[Ingest Node\nmore capable machine] - INGEST -->|well-formed stream| RELAY[Relay] + CAM[V4L2 Camera\ndev/video0] -->|raw MJPEG| PI[Pi: ingest node] + PI -->|encapsulated stream| RELAY[Relay] RELAY -->|high priority| DISPLAY[Display / Preview\nlow latency] RELAY -->|low priority| ARCHIVE[Archiver\nhigh quality] - INGEST -.->|V4L2 control\nvia transport| PI - CTRL[Control Plane\nmessage hub] -.->|node control| INGEST - CTRL -.->|node control| RELAY + CTRL[Controller node\nweb UI] -.->|V4L2 control\nvia transport| PI + CTRL -.->|connection config| RELAY ``` The Pi runs a node process that dequeues V4L2 buffers and forwards each buffer as an encapsulated frame over TCP. It also exposes the V4L2 control endpoint for remote parameter adjustment.