julian
90d036dbf0
The wiki was silent on the actual stream name used by tcp-ingestion and
processor — anyone reading it to understand the architecture had no way
to find out what stream the services use. This gap contributed to a
stage-side bug where the two services' compiled defaults drifted
(tcp-ingestion: telemetry:teltonika, processor: telemetry:t), causing
~7 hours of silent zero-throughput before symptoms surfaced.
Changes:
- entities/redis-streams.md — added "Stream and key naming" table
covering the inbound telemetry stream, Phase 2 command streams, and
registry/heartbeat keys. Documented the telemetry:{vendor} convention
so a future Queclink/Concox adapter fits predictably.
- entities/processor.md — opening paragraph names the stream and
consumer group consumed.
- entities/tcp-ingestion.md — opening paragraph names the stream
produced; defers full naming convention to redis-streams.
- log.md — note entry recording the canonicalization and the stage
incident that triggered it.
4.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] note | Stream-name canonicalization
Documented the canonical stream/key names in redis-streams — the wiki was previously silent on the actual telemetry:teltonika name, so anyone reading it had no way to find out what stream the services use. Added a "Stream and key naming" table covering the inbound telemetry stream, Phase 2 command streams, and registry/heartbeat keys. Also added the naming convention (telemetry:{vendor}) so future adapters fit predictably. Cross-referenced the actual stream name in processor and tcp-ingestion entities so each entity is self-contained but the convention has one canonical home.
Triggered by a stage-side bug where tcp-ingestion's compiled default (telemetry:teltonika) and processor's compiled default (telemetry:t) had drifted; pipeline ran with both services talking past each other for ~7 hours before symptoms surfaced. Fix landed in deploy stack (shared env var) and processor (default realigned). Wiki update closes the documentation loop.
[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.