trm/docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Correct live-channel architecture; document dual-WebSocket design

Browse Source 
Researched Directus's WebSocket subscription mechanism via context7 and
confirmed it only fires events for writes that go through Directus's
own ItemsService. Direct INSERTs from Processor are invisible to
subscribers. The previous claim in entities/directus.md that Directus
broadcasts Processor's writes was wrong.

New: wiki/concepts/live-channel-architecture.md captures the corrected
design with three options table, chosen-architecture diagram,
authorization flow, failure modes, multi-instance plumbing, scale
considerations, and open questions. Chosen path: Processor exposes its
own WebSocket endpoint for the high-volume telemetry firehose
(authentication via Directus-issued JWT, authorization delegated to
Directus once at subscribe time); Directus's built-in WebSocket covers
business-plane events. Each WebSocket serves the writes its plane
manages — preserves plane-separation and gives the gentlest failure
mode (Directus down only blocks new authorizations).

Updated:
- entities/directus.md — corrected the real-time-delivery section,
  added pointer to the new concept page.
- entities/processor.md — added Live broadcast section in
  responsibilities and a section explaining the dual-consumer-group
  plumbing for multi-instance HA.
- index.md — listed the new concept.
- log.md — synthesis entry for 2026-05-01 documenting the correction.
This commit is contained in:
Julian Çuni
2026-05-01 10:40:12 +02:00
parent bf403332d0
commit 9acde675d9
5 changed files with 164 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
log.md
+8
View File
@@ -37,3 +37,11 @@ Updates to existing pages (no contradictions; refinements + additions):
Cleanup: removed stale duplicate concept files from earlier passes (system-planes.md, protocol-adapter-pattern.md, codec-dispatch-registry.md) — superseded by plane-separation.md, protocol-adapter.md, codec-dispatch.md respectively. Fixed dangling [[protocol-adapter-pattern]] link in [[io-element-bag]].
Open questions surfaced by the canonical doc: Codec 16 Generation Type — promote to typed [[position-record]] field? Codec 8E NX values land as `Buffer` in `attributes`; needs explicit fixture coverage. SMS-based protocols (Codec 4 + binary SMS) probably out of scope but worth a deliberate decision.
## [2026-05-01] synthesis | Live channel architecture (corrects a wiki claim)
Researched Directus's WebSocket subscription mechanism via context7. Confirmed that subscriptions only fire for writes that go through Directus's `ItemsService` (REST/GraphQL/Admin UI mutations, not direct database INSERTs). The previous claim in [[directus]] — "When Processor writes a row, Directus broadcasts the change to subscribed clients" — was wrong.
Wrote [[live-channel-architecture]] documenting the corrected design: two WebSocket channels, each in its own plane. Processor exposes its own WebSocket endpoint for high-volume telemetry fan-out (auth via Directus-issued JWT, authorization delegated to Directus once at subscribe time). Directus's built-in WebSocket subscriptions cover business-plane events. Reasoning: preserves [[plane-separation]] and gives the gentlest failure mode (Directus down blocks only new authorizations, not the live firehose).
Updated [[processor]] (added Live broadcast section, multi-instance consumer-group plumbing note), [[directus]] (corrected the real-time-delivery section), and index.md.