julian
9acde675d9
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.
36 lines
2.4 KiB
Markdown
36 lines
2.4 KiB
Markdown
# Index
|
|
|
|
Content catalog for the TRM wiki. Maintained by the LLM on every ingest. See [[CLAUDE]] for schema and conventions.
|
|
|
|
## Sources
|
|
|
|
- [[gps-tracking-architecture]] — System-level architecture: four-component platform, three planes, failure domains.
|
|
- [[teltonika-ingestion-architecture]] — Internal Teltonika protocol adapter design; Phase 1 (8/8E/16) and Phase 2 (12/13/14) roadmap.
|
|
- [[teltonika-data-sending-protocols]] — Official Teltonika canonical wiki; full codec inventory including Codec 15 and SMS protocols, UDP transport, ACK/nACK details.
|
|
|
|
## Entities
|
|
|
|
- [[directus]] — Business plane: schema owner, REST/GraphQL/WSS, admin UI, permissions, Flows.
|
|
- [[postgres-timescaledb]] — Durable storage: positions hypertable + business schema. The system's only single point of failure.
|
|
- [[processor]] — Domain-logic service consuming Redis Streams; per-device hot state in memory; sole writer for telemetry tables.
|
|
- [[react-spa]] — End-user UI; talks exclusively to Directus; role-based views in a single bundle.
|
|
- [[redis-streams]] — Durable in-flight queue between Ingestion and Processor; Phase 2 transport for outbound commands.
|
|
- [[tcp-ingestion]] — Per-vendor TCP listener service; parses binary protocols and emits normalized records.
|
|
- [[teltonika]] — GPS hardware vendor; Codec 8/8E/16 telemetry today, Codec 12/14 commands deferred (13/15 one-way, 15 out of scope).
|
|
|
|
## Concepts
|
|
|
|
- [[avl-data-format]] — Canonical Teltonika packet structure: envelope, AVL record, GPS element, IO element layouts per codec.
|
|
- [[codec-dispatch]] — Flat registry keyed on codec ID; the seam that makes Phase 2 additive.
|
|
- [[failure-domains]] — Independent component failure behavior; database is the only SPOF.
|
|
- [[io-element-bag]] — The pass-through principle for model-specific telemetry inside AVL records.
|
|
- [[live-channel-architecture]] — Dual-WebSocket design for live UX: Processor's endpoint for telemetry firehose, Directus's for business-plane updates.
|
|
- [[phase-2-commands]] — Deferred design for server-to-device commands via Teltonika codecs 12/14.
|
|
- [[plane-separation]] — Three-plane architecture (telemetry / business / presentation) split by data velocity and failure domain.
|
|
- [[position-record]] — Boundary contract between vendor adapters and the rest of the system.
|
|
- [[protocol-adapter]] — Vendor-abstraction interface (bytes in → normalized Position out) at the Ingestion layer.
|
|
|
|
## Synthesis
|
|
|
|
_None yet._
|