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>
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.
julian