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.
3.8 KiB
Log
Chronological activity log. Append-only. Entry headers use the format ## [YYYY-MM-DD] <op> | <title> so they can be grepped:
grep "^## \[" log.md | tail -10
[2026-04-30] note | Wiki bootstrapped
Created CLAUDE.md (schema + workflows), index.md (empty catalog), and this log. Wiki directory structure (wiki/sources, wiki/entities, wiki/concepts, wiki/synthesis) will be created on first ingest.
[2026-04-30] ingest | gps-tracking-architecture.md + teltonika-ingestion-architecture.md
Ingested both initial architecture docs in one pass. Created:
- Source pages: gps-tracking-architecture, teltonika-ingestion-architecture.
- Entity pages: tcp-ingestion, processor, directus, react-spa, redis-streams, postgres-timescaledb, teltonika.
- Concept pages: plane-separation, protocol-adapter, codec-dispatch, position-record, failure-domains, phase-2-commands.
- Updated index.md with all 15 new pages.
No contradictions to flag — the two docs are coherent (the Teltonika doc explicitly cites and respects the system architecture). Open follow-ups: TRM business domain not yet captured; per-model IO dictionary location TBD; Phase 2 timing unspecified.
[2026-04-30] ingest | Teltonika Data Sending Protocols (official wiki)
Ingested the canonical Teltonika spec covering all codec families. New additions:
- Source page: teltonika-data-sending-protocols.
- New concept: avl-data-format — byte-level reference for codecs 8/8E/16, including UDP envelope.
Updates to existing pages (no contradictions; refinements + additions):
- teltonika — added full codec table with hex IDs, Codec 15 (out of scope), Codec 14 ACK/nACK, packet size limits, UDP support note.
- codec-dispatch — corrected hex IDs, added directionality table covering codecs 8–15.
- position-record — concrete priority enum (0/1/2), two's-complement lat/lon note, Speed=0 means GPS invalid, Generation Type and NX section flagged.
- phase-2-commands — clarified Codec 12 vs 14 selection, added
nackstatus for Codec 14 IMEI-mismatch (Type0x11); noted 13/15 are not part of the outbound design.
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.