julian
411b08d02f
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.
2.8 KiB
2.8 KiB
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.
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 exclusively to Directus; 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.
- 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.