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>
trm/directus Phase 1 image is on the registry; trm/deploy's
compose.yaml has been extended with a directus service block that
shares the existing postgres service with processor (different
tables, no contention). Bringing the architecture wiki up to date.
wiki/entities/directus.md updates:
- New "Deployment" section: links to the deploy compose, names the
shared-Postgres model with processor, spells out the 5-step boot
pipeline (db-init pre-schema → bootstrap → schema apply →
db-init post-schema → start), notes first-boot (~60-90 s) vs
warm-boot (~10 s) timing, points at deploy/README.md's first-deploy
checklist.
- New "Network exposure" subsection: directus is internal-only on
stage / prod (expose: 8055 not ports:). A reverse proxy on the
host or attached to trm_default terminates TLS and forwards the
public domain to http://directus:8055. The asymmetry with
tcp-ingestion (which must host-publish for GPS devices) is named.
The dev compose's deliberate divergence (host-publishes 8055 for
local iteration) is noted.
- Schema management section: db-init split into pre-schema (db-init/)
and post-schema (db-init-post/) phases. Post-schema landed because
the composite UNIQUE constraints target Directus-managed tables
that don't exist until schema apply runs. Both phases run via the
same apply-db-init.sh with DB_INIT_DIR overridden between calls.
- Destructive-apply hazard callout: corrected entrypoint step
reference (now step 3/5, not 2/4) after the bootstrap-before-apply
reorder that landed during CI iterations.
log.md entry records the three CI iterations that surfaced three
distinct production-breaking bugs (port collision; ordering + silent
ERROR exit; ghost-collection apply conflict) — all caught by the
dry-run gate before reaching stage. Ghost-collection stripping is
now automated in scripts/schema-snapshot.sh so future captures
don't regress.
A real incident hit during directus Phase 1 task 1.5: 5 newly-created
collections were destroyed by a container rebuild because the baked-in
snapshot was stale. directus schema apply --yes enforces the snapshot
as the single source of truth — anything not in the snapshot gets
deleted.
This is correct for fresh-environment provisioning and prod, but
catastrophic during active schema development. Adding a callout to the
directus entity page so future readers see the operator rule alongside
the snapshot/apply pattern documentation:
Never restart or rebuild the Directus container while there are
uncommitted schema changes. Always: change → snapshot → commit →
rebuild/restart.
The recovery path (re-apply via MCP / admin UI, snapshot before
restart) is straightforward in dev but would be data-loss in prod.
Phase 3 hardening will introduce a DIRECTUS_SCHEMA_APPLY_MODE env var
with auto/dry-run/skip modes so dev environments default to
non-destructive behavior.
Substantial design artifact + canonical-source ingest for the TRM
business plane.
Schema draft (synthesis):
- wiki/synthesis/directus-schema-draft.md — working agreement for the
multi-tenant schema. Pseudo multi-tenant under organizations; entries
as the unit of timing; course definition (stages/segments/geofences/
waypoints/SLZs); penalty system "numbers in DB, math in code" with an
evaluator registry and progressive bracket math; per-entry timing
tables; per-stage start-order strategies (manual /
previous_stage_clean_result / inverse_top_n_then_natural /
inverse_of_overall) covering both Tirana 24h and Rally Albania
patterns. Two role surfaces (org role vs racing role) called out
explicitly. Decisions captured; Open questions reduced to one
(geometry retroactivity engine, deferred to Phase 2.5).
Source ingest:
- raw/Regulations_2025.pdf + wiki/sources/rally-albania-regulations-
2025.md — formal ingest of the canonical Rally Albania 2025
rulebook. Section numbers preserved as §X.Y so the schema draft and
future SPA work can cite precisely. Flagged follow-ups: the SLZ
formula lives in the Supplementary Regulations (don't hardcode);
M-7 numbering bug; unmodeled neutralization zones.
Faulty-position flag (cross-plane operator workflow):
- entities/postgres-timescaledb.md, entities/processor.md,
concepts/position-record.md — operator-controlled boolean on the
positions hypertable; processor filters WHERE faulty = false on
every read; flagging triggers windowed recompute via the
recompute:requests stream.
Implementation strategy on entity pages:
- entities/directus.md — Schema management section documenting the
snapshots/ + db-init/ convention, container-startup apply pipeline.
- entities/processor.md — Phase 2 long-lived branch model with
PROCESSOR_PHASE_2_ENABLED flag-gating for incremental main merges;
Phase 2.5 deferral note.
Index and log updated.
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.
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