trm/docs

Files

T

julian 411b08d02f Add business-plane schema draft and ingest Rally Albania 2025 regs

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.

2026-05-01 20:31:10 +02:00

5.2 KiB

Raw Blame History

title, type, created, updated, sources, tags

title

type

created

updated

sources

Directus

The business plane. Owns the relational schema, exposes it through auto-generated REST/GraphQL APIs, enforces role-based permissions, and provides the admin UI for back-office users.

What Directus owns

Schema management — collections, fields, relations, migrations.
API generation — REST and GraphQL endpoints, no boilerplate.
Authentication and authorization — users, roles, permissions, JWT issuance.
Real-time — WebSocket subscriptions on collections for live UIs.
Workflow automation — Flows for orchestrating side effects (notifications, integrations).
Admin UI — complete back-office interface for operators.

What Directus is NOT

Not in the telemetry hot path. Does not accept device connections, run a geofence engine, or hold per-device runtime state. Mixing those responsibilities into the same process would couple deployment lifecycles and contaminate failure domains. See plane-separation.

Schema ownership vs. write access

Directus is the schema owner even though processor writes directly to the database. New tables, columns, and relations are defined through Directus. Reasons:

Auto-generated admin UI and APIs are derived from the schema Directus knows about. Tables created outside Directus are invisible to it.
Permissions are configured per-collection in Directus.
Audit columns (created_at, updated_at, user_created) follow Directus conventions; bypassing them inconsistently leads to subtle UI bugs.

This is a normal Directus deployment pattern — it does not require sole write access, only schema authority.

Extensions

Used for things that genuinely belong in the business layer:

Hooks that react to data changes (e.g. on event-write, trigger a notification Flow).
Custom endpoints for permission-gated, audited operations that are not throughput-critical.
Custom admin UI panels for back-office workflows (data review, manual overrides, bulk ops).
Flows for declarative orchestration.

Not used for long-running listeners, persistent network sockets, or anything in the telemetry hot path.

Real-time delivery

Directus's WebSocket subscriptions push live data to the react-spa for writes that go through Directus's own services (REST, GraphQL, Admin UI, Flows, custom endpoints). The mechanism is action hooks (action('items.create', ...)) firing from the ItemsService, not Postgres-level change detection.

This means direct database writes from processor are not visible to Directus's subscription system. The platform handles this with two cleanly-separated WebSocket channels:

directus's WebSocket — broadcasts business-plane events: timing edits, configuration changes, manual entries, anything operators do through the admin UI or via directus's API.
processor's WebSocket — broadcasts the high-volume telemetry firehose: live position updates fanned out from redis-streams directly to subscribed react-spa clients. Authentication uses Directus-issued JWTs; per-subscription authorization delegates to Directus once at subscribe time.

See live-channel-architecture for the full design, including why this split is preferable to routing telemetry writes through directus's API or running a bridging extension inside directus.

Schema management — snapshot/apply pipeline

Schema changes flow through Directus's native snapshot mechanism, kept under git. Two artifact directories:

snapshots/schema.yaml — Directus collections, fields, relations. Generated locally with directus schema snapshot. Applied at container startup with directus schema apply --yes. Idempotent — applies only the diff against the running DB.
db-init/*.sql — schema Directus does not manage: the postgres-timescaledb positions hypertable, the faulty column, indexes that need PostGIS-specific syntax, or any DDL that predates Directus knowing about a collection. Numbered (001_, 002_, …) and applied by a sidecar container or one-shot job ahead of directus schema apply. Tracked via a migrations_applied guard table to skip already-run files.

Local dev edits the schema in the admin UI, then snapshots before commit. CI builds the image with both directories baked in, spins a throwaway Postgres, and dry-runs apply to catch breakage before deploy. Production (Portainer) runs the same apply at container start; multi-env separation is a connection string, not different artifacts.

This treats schema.yaml as the source of truth and the admin UI as its editor. Don't hand-edit schema.yaml; round-trip through the UI to keep the format consistent.

Phase 2 role

Directus owns the commands collection and is the single auth surface for outbound device commands. The SPA inserts command rows; a Directus Flow routes them via Redis to the Ingestion instance holding the device's socket. See phase-2-commands.

Failure mode

Crash → telemetry continues to flow into the database; admin UI and SPA are unavailable; no telemetry is lost. See failure-domains.

5.2 KiB Raw Blame History