julian
22b1b069df
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.
3.1 KiB
title, type, created, updated, sources, tags
| title | type | created | updated | sources | tags | |||||
|---|---|---|---|---|---|---|---|---|---|---|
| Directus | entity | 2026-04-30 | 2026-04-30 |
|
|
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.