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.
37 lines
2.8 KiB
Markdown
37 lines
2.8 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.
|
|
|
|
## 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.
|