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
wiki/entities/directus.md
+9 -2
View File
@@ -2,7 +2,7 @@
title: Directus
type: entity
created: 2026-04-30
updated: 2026-04-30
updated: 2026-05-01
sources: [gps-tracking-architecture, teltonika-ingestion-architecture]
tags: [service, business-plane, api]
---
@@ -47,7 +47,14 @@ Used for things that genuinely belong in the business layer:
## Real-time delivery
Directus's WebSocket subscriptions push live data to the [[react-spa]]. When [[processor]] writes a row, Directus broadcasts the change to subscribed clients. Sufficient for tens to low hundreds of concurrent subscribers. If fan-out becomes a bottleneck, a dedicated WebSocket gateway can read directly from [[redis-streams]] and push to clients, bypassing Directus for the live channel only — REST/GraphQL stays in Directus.
Directus's WebSocket subscriptions push live data to the [[react-spa]] **for writes that go through Directus's own services** (REST, GraphQL, Admin UI, Flows, custom endpoints). The mechanism is action hooks (`action('items.create', ...)`) firing from the `ItemsService`, not Postgres-level change detection.
This means **direct database writes from [[processor]] are not visible** to Directus's subscription system. The platform handles this with two cleanly-separated WebSocket channels:
- **[[directus]]'s WebSocket** — broadcasts business-plane events: timing edits, configuration changes, manual entries, anything operators do through the admin UI or via [[directus]]'s API.
- **[[processor]]'s WebSocket** — broadcasts the high-volume telemetry firehose: live position updates fanned out from [[redis-streams]] directly to subscribed [[react-spa]] clients. Authentication uses Directus-issued JWTs; per-subscription authorization delegates to Directus once at subscribe time.
See [[live-channel-architecture]] for the full design, including why this split is preferable to routing telemetry writes through [[directus]]'s API or running a bridging extension inside [[directus]].
## Phase 2 role