---
title: Directus
type: entity
created: 2026-04-30
updated: 2026-05-01
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]] **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]].

## 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]].