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 <noreply@anthropic.com>
This commit is contained in:
2026-03-25 22:20:55 +00:00
parent b56dfae672
commit ea3fcc2c0f
2 changed files with 28 additions and 0 deletions

View File

@@ -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