julian
f92595a62a
Catches up the wiki with several pieces of work accumulated during this session. INGEST: TRACCAR_MAPS_ARCHITECTURE.md - raw/TRACCAR_MAPS_ARCHITECTURE.md (source doc, read-only). - wiki/sources/traccar-maps-architecture.md — TL;DR + key claims + notable quotes + TRM divergences (PostGIS-native GeoJSON, rAF coalescer, Zustand, longer trail, racing sprite set). - wiki/concepts/maps-architecture.md — distilled patterns for the SPA's map subsystem: singleton MapLibre + side-effect-only Map* components + two GeoJSON sources + style-swap mapReady gate + sprite preload + WS- to-map data flow (with rAF coalescer) + geofence editing + camera control trio. - wiki/entities/react-spa.md — corrected the "talks exclusively to Directus" contradiction with [[live-channel-architecture]] (SPA connects to two endpoints — Directus + Processor); locked stack (raw MapLibre over react-map-gl, Zustand over Redux); added Auth section. - wiki/concepts/live-channel-architecture.md — single sentence cross- referencing [[maps-architecture]] for consumer-side throughput discipline. - index.md — Sources + Concepts entries. SYNTHESIS: processor-ws-contract - wiki/synthesis/processor-ws-contract.md — wire-level spec for the live-position WebSocket: endpoint, transport, auth handshake, subscribe/snapshot/streaming/unsubscribe protocol, reconnect, multi- instance behaviour, connection limits, versioning, open questions. Implementation-agnostic; the producer is cookie-name-agnostic so the spec doesn't pin to a specific Directus auth mode. - index.md — Synthesis entry. AUTH-MODE REALIGNMENT (cookie -> session) - SPA implementation surfaced that Directus SDK 'cookie' mode doesn't survive a hard reload cleanly. Switched the SPA to 'session' mode (separate commit in trm/spa). Wiki updates here: - wiki/entities/react-spa.md §Auth pattern — describes session mode (single httpOnly session cookie, no separate access token, no /auth/refresh dance). Added "Mode choice context" note. - wiki/synthesis/processor-ws-contract.md §Auth handshake — emphasises the producer is cookie-name-agnostic; reframed "Cookie refresh while connected" as "Session expiry while connected". Plus all the chronological log.md entries documenting the above plus Phase 1.5 planning, SPA Phase 1 planning, and stage verify+seed work from earlier in the session. Skipped from this commit: .claude/agent-memory/* (user-local agent state, not project content); .gitignore (already-modified by user outside this session's scope). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
40 lines
3.4 KiB
Markdown
40 lines
3.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.
|
|
- [[rally-albania-regulations-2025]] — Federation rulebook for Rally Albania 2025; canonical real-world reference for classes, start-order rules, penalty taxonomy, tracking requirements.
|
|
- [[teltonika-data-sending-protocols]] — Official Teltonika canonical wiki; full codec inventory including Codec 15 and SMS protocols, UDP transport, ACK/nACK details.
|
|
- [[teltonika-ingestion-architecture]] — Internal Teltonika protocol adapter design; Phase 1 (8/8E/16) and Phase 2 (12/13/14) roadmap.
|
|
- [[traccar-maps-architecture]] — Deep dive into traccar-web's MapLibre + GeoJSON + WebSocket maps subsystem. The reference architecture our SPA inherits, with deliberate divergences.
|
|
|
|
## 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 to Directus (REST + business-plane WS) and Processor (live-position WS); 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.
|
|
- [[maps-architecture]] — Singleton MapLibre + side-effect React components + GeoJSON setData pipeline. The pattern the SPA uses, with rAF coalescing as the throughput discipline.
|
|
- [[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
|
|
|
|
- [[directus-schema-draft]] — Working draft of the business-plane schema: orgs, users, teams, vehicles, devices, events, entries with crew/devices. Open for revision.
|
|
- [[processor-ws-contract]] — Wire-level spec for the live-position WebSocket: auth handshake, subscribe/snapshot/streaming/unsubscribe protocol, reconnect, multi-instance, versioning. Implementation-agnostic; flags the wiki/planning drift on which service hosts it.
|