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.
71 lines
4.0 KiB
Markdown
71 lines
4.0 KiB
Markdown
---
|
||
title: Position Record
|
||
type: concept
|
||
created: 2026-04-30
|
||
updated: 2026-05-01
|
||
sources: [gps-tracking-architecture, teltonika-ingestion-architecture, teltonika-data-sending-protocols]
|
||
tags: [data-model, boundary-contract]
|
||
---
|
||
|
||
# Position Record
|
||
|
||
The normalized record produced by [[tcp-ingestion]] and consumed by [[processor]]. The boundary contract between vendor adapters and the rest of the system.
|
||
|
||
## Shape (Teltonika reference)
|
||
|
||
```ts
|
||
type Position = {
|
||
device_id: string // IMEI from the handshake
|
||
timestamp: Date // from the AVL record's GPS timestamp
|
||
latitude: number
|
||
longitude: number
|
||
altitude: number
|
||
angle: number // heading, 0-360
|
||
speed: number // km/h
|
||
satellites: number
|
||
priority: 0 | 1 | 2 // 0=Low, 1=High, 2=Panic (Teltonika spec)
|
||
attributes: {
|
||
[io_id: string]: number | bigint | Buffer
|
||
}
|
||
}
|
||
```
|
||
|
||
The system architecture doc lists a slimmer canonical form — `device_id`, `timestamp`, `lat`, `lon`, `speed`, `heading`, plus an attribute bag — and the Teltonika doc extends it with `altitude`, `satellites`, `priority`. Treat the Teltonika shape as the current concrete contract.
|
||
|
||
## The `attributes` bag — pass through unchanged
|
||
|
||
The Ingestion service does **not** name, interpret, filter, or unit-convert IO elements. `attributes` is a verbatim representation of the IO element bag from the AVL record, keyed by the numeric IO element ID **as a string**.
|
||
|
||
Two reasons:
|
||
|
||
- **Model-specific interpretation belongs where the model is known.** The [[processor]] configures per-model IO mappings; doing this in the parser would couple Ingestion to a registry of every device model in the fleet.
|
||
- **A new model never breaks Ingestion.** A packet with `IO 1234` from a device whose config we have not yet imported gets stored under `"1234"` and the position is still useful; the attribute is recoverable later.
|
||
|
||
This is the property that makes the [[protocol-adapter]] model-agnostic.
|
||
|
||
## What's codec-defined vs. model-defined
|
||
|
||
For [[teltonika]]:
|
||
|
||
- **Codec-defined** (always present, same shape per codec): timestamp, lat/lon/alt, angle, satellites, speed, priority. These fill out the typed fields above.
|
||
- **Model-defined** (varies between models, opaque to parser): everything in the IO bag.
|
||
|
||
### Codec-specific quirks
|
||
|
||
- **Speed = `0x0000` means GPS data is invalid**, not "stationary." The parser preserves this verbatim (speed = 0); the [[processor]] decides whether to surface it as "no GPS fix" or coalesce with the stationary case.
|
||
- **Lat/Lon are two's complement** signed integers — first bit = sign. Parsing must be sign-aware.
|
||
- **Codec 16 carries a Generation Type** (0–7: On Exit, On Entrance, On Both, Reserved, Hysteresis, On Change, Eventual, Periodical) that is codec-defined but not currently in the Position shape. Open question on whether to promote it to a typed field. See [[avl-data-format]].
|
||
- **Codec 8 Extended NX section** carries variable-length IO values — these land in `attributes` as `Buffer`, alongside the fixed-width N1/N2/N4/N8 entries.
|
||
|
||
## Downstream contract
|
||
|
||
[[processor]] is responsible for naming IO elements (e.g. `"16"` → `"odometer_km"`), unit conversions, and any filtering. It writes the typed fields to the positions hypertable and may write derived/named attributes to other tables.
|
||
|
||
## Wire shape vs. storage shape
|
||
|
||
The Position type above is the **wire shape** — what [[tcp-ingestion]] produces and what flows through [[redis-streams]]. The **storage shape** in the positions hypertable extends it with one operator-controlled field:
|
||
|
||
- **`faulty: boolean`** (default `false`) — set after the fact by track operators through [[directus]] when a position is unrealistic (jumpy GPS, impossible coordinate/speed). [[processor]] evaluators filter `WHERE faulty = false` on every read; flagged positions are excluded from peak-speed calculations, crossing detection, and recompute. See the operator workflow in the [[directus-schema-draft]].
|
||
|
||
This field exists only at rest. Ingestion and the live channel never see it; it has no meaning until a human reviews the data.
|