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