From ea3fcc2c0f629b4e5cef47c92d99df08201d10ea Mon Sep 17 00:00:00 2001 From: mikael-lovqvists-claude-agent Date: Wed, 25 Mar 2026 22:20:55 +0000 Subject: [PATCH] Document web node as protocol peer and future preprocessor SSoT plan architecture.md: - Web interface connects as a first-class binary protocol peer; no JSON bridge in C; DataView in JS maps directly to get_u32 etc. - Future preprocessor section: protocol schema defined once, emits both C (put/get, write_*/read_*) and ESM JS (DataView encode/decode); same tool as planned for error location codes planning.md: - Add web node (entry #11) to module order - Add Future: Protocol Preprocessor section above Deferred Decisions Co-Authored-By: Claude Sonnet 4.6 --- architecture.md | 21 +++++++++++++++++++++ planning.md | 7 +++++++ 2 files changed, 28 insertions(+) diff --git a/architecture.md b/architecture.md index 498a8a5..992b400 100644 --- a/architecture.md +++ b/architecture.md @@ -275,6 +275,27 @@ Each `write_*` function knows the exact wire layout of its message, packs the fu This gives a clean two-layer separation: `serial` handles byte layout, `protocol` handles message semantics and I/O. +### Web Interface as a Protocol Peer + +The web interface (Node.js/Express) participates in the graph as a first-class protocol peer — it speaks the same binary protocol as any C node. There is no JSON bridge or special C code to serve the web layer. The boundary is: + +- **Socket side**: binary protocol, framed messages, little-endian fields read with `DataView` (`dataView.getUint32(offset, true)` maps directly to `get_u32`) +- **Browser side**: HTTP/WebSocket, JSON, standard web APIs + +A `protocol.mjs` module in the web layer mirrors the C `protocol` module — same message types, same wire layout, different language. This lets the web interface connect to any video node, send control requests (V4L2 enumeration, parameter get/set, device discovery), and receive structured responses. + +Treating the web node as a peer also means it exercises the real protocol, which surfaces bugs that a JSON bridge would hide. + +### Future: Single Source of Truth via Preprocessor + +The C `protocol` module and the JavaScript `protocol.mjs` currently encode the same wire format in two languages. This duplication is a drift risk — a change to a message layout must be applied in both places. + +A future preprocessor will eliminate this. Protocol messages will be defined once in a language-agnostic schema, and the preprocessor will emit both: +- C source — `put_*`/`get_*` calls, struct definitions, `write_*`/`read_*` functions +- ESM JavaScript — `DataView`-based encode/decode, typed constants + +The preprocessor is the same tool planned for generating error location codes (see `common/error`). The protocol schema becomes a single source of truth, and both the C and JavaScript implementations are derived artifacts. + --- ## Open Questions diff --git a/planning.md b/planning.md index ee1e2dc..624a692 100644 --- a/planning.md +++ b/planning.md @@ -47,6 +47,7 @@ Modules are listed in intended build order. Each depends only on modules above i | 8 | `relay` | not started | Input dispatch to output queues (low-latency and completeness modes) | | 9 | `ingest` | not started | MJPEG frame parser (two-pass EOI state machine, opaque stream → discrete frames) | | 10 | `archive` | not started | Write frames to disk, control messages to binary log | +| 11 | `web node` | not started | Node.js/Express peer — speaks binary protocol on socket side, HTTP/WebSocket to browser; `protocol.mjs` mirrors C protocol module | --- @@ -62,6 +63,12 @@ Each module gets a corresponding CLI driver in `dev/cli/` that exercises its API --- +## Future: Protocol Preprocessor + +The C `protocol` module and JavaScript `protocol.mjs` will eventually be generated from a single schema by a future preprocessor. This eliminates drift between the two implementations. The preprocessor also handles error location codes (see `common/error`). Neither the schema format nor the preprocessor tool exists yet — the hand-written implementations are the interim state. + +--- + ## Deferred Decisions These are open questions tracked in `architecture.md` that do not need to be resolved before module work begins: