julian
9acde675d9
Researched Directus's WebSocket subscription mechanism via context7 and confirmed it only fires events for writes that go through Directus's own ItemsService. Direct INSERTs from Processor are invisible to subscribers. The previous claim in entities/directus.md that Directus broadcasts Processor's writes was wrong. New: wiki/concepts/live-channel-architecture.md captures the corrected design with three options table, chosen-architecture diagram, authorization flow, failure modes, multi-instance plumbing, scale considerations, and open questions. Chosen path: Processor exposes its own WebSocket endpoint for the high-volume telemetry firehose (authentication via Directus-issued JWT, authorization delegated to Directus once at subscribe time); Directus's built-in WebSocket covers business-plane events. Each WebSocket serves the writes its plane manages — preserves plane-separation and gives the gentlest failure mode (Directus down only blocks new authorizations). Updated: - entities/directus.md — corrected the real-time-delivery section, added pointer to the new concept page. - entities/processor.md — added Live broadcast section in responsibilities and a section explaining the dual-consumer-group plumbing for multi-instance HA. - index.md — listed the new concept. - log.md — synthesis entry for 2026-05-01 documenting the correction.
3.9 KiB
title, type, created, updated, sources, tags
| title | type | created | updated | sources | tags | |||||
|---|---|---|---|---|---|---|---|---|---|---|
| Directus | entity | 2026-04-30 | 2026-05-01 |
|
|
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.