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.
1.9 KiB
1.9 KiB
title, type, created, updated, sources, tags
| title | type | created | updated | sources | tags | |||
|---|---|---|---|---|---|---|---|---|
| Plane Separation (Telemetry / Business / Presentation) | concept | 2026-04-30 | 2026-04-30 |
|
|
Plane Separation
The system is organized as three concentric concerns, deliberately split along data velocity and failure domain.
The three planes
- Telemetry plane — tcp-ingestion + redis-streams + processor. Optimized for throughput, low latency, resilience to bursty input. Stateless or nearly so.
- Business plane — directus over postgres-timescaledb. Owns schema, API surface, permissions, back-office workflows.
- Presentation plane — react-spa. Consumes business-plane APIs and real-time subscriptions; never talks to the telemetry plane directly.
How the boundaries are enforced
- Redis Streams is the boundary between Ingestion and the Processor side of the telemetry plane.
- The database + Directus API is the boundary between the telemetry and business planes.
- Directus REST/GraphQL/WSS is the boundary between business and presentation planes.
No component reaches across two boundaries. This is the rule that makes the architecture coherent.
Why this matters
- Each component scales independently (Ingestion horizontally per TCP load; Directus horizontally per HTTP load; database vertically + read replicas).
- Each component fails independently — see failure-domains.
- Adding new device vendors does not touch the business plane. Adding new front-end surfaces does not touch the telemetry plane.
- Security model stays coherent: only Directus exposes user-facing APIs.
The discipline that holds it together
The clearest articulation of the plane discipline: the TCP handler never blocks on downstream work. If the Processor or DB is slow, the queue absorbs pressure; Ingestion keeps accepting and acknowledging. Without this, the planes leak into each other under load.