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.
38 lines
1.9 KiB
Markdown
38 lines
1.9 KiB
Markdown
---
|
|
title: Plane Separation (Telemetry / Business / Presentation)
|
|
type: concept
|
|
created: 2026-04-30
|
|
updated: 2026-04-30
|
|
sources: [gps-tracking-architecture]
|
|
tags: [architecture, principle]
|
|
---
|
|
|
|
# Plane Separation
|
|
|
|
The system is organized as **three concentric concerns**, deliberately split along **data velocity** and **failure domain**.
|
|
|
|
## The three planes
|
|
|
|
1. **Telemetry plane** — [[tcp-ingestion]] + [[redis-streams]] + [[processor]]. Optimized for throughput, low latency, resilience to bursty input. Stateless or nearly so.
|
|
2. **Business plane** — [[directus]] over [[postgres-timescaledb]]. Owns schema, API surface, permissions, back-office workflows.
|
|
3. **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.
|