Bootstrap LLM-maintained wiki with TRM architecture knowledge

Initialize CLAUDE.md schema, index, and log; ingest three architecture sources (system overview, Teltonika ingestion design, official Teltonika data-sending protocols) into 7 entity pages, 8 concept pages, and 3 source pages with wikilink cross-references.
2026-04-30 13:12:24 +02:00
parent d62d50b30b
commit 22b1b069df
24 changed files with 3084 additions and 0 deletions
@@ -0,0 +1,58 @@
+---
+title: Directus
+type: entity
+created: 2026-04-30
+updated: 2026-04-30
+sources: [gps-tracking-architecture, teltonika-ingestion-architecture]
+tags: [service, business-plane, api]
+---
+
+# 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]]. When [[processor]] writes a row, Directus broadcasts the change to subscribed clients. Sufficient for tens to low hundreds of concurrent subscribers. If fan-out becomes a bottleneck, a dedicated WebSocket gateway can read directly from [[redis-streams]] and push to clients, bypassing Directus for the live channel only — REST/GraphQL stays in Directus.
+
+## 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]].