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.
59 lines
3.1 KiB
Markdown
59 lines
3.1 KiB
Markdown
---
|
|
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]].
|