docs/wiki/sources/gps-tracking-architecture.md

title, type, created, updated, sources, tags, source_path, source_kind

title	type	created	updated	sources	tags	source_path	source_kind
GPS Tracking Platform — Architecture Overview	source	2026-04-30	2026-04-30	gps-tracking-architecture	architecture system-design overview	raw/gps-tracking-architecture.md	note

GPS Tracking Platform — Architecture Overview

TL;DR

System-level reference for a real-time GPS telemetry platform built around four cooperating components: a TCP Ingestion service, a Processor, a Directus instance, and a React SPA. The architecture splits the system along data velocity and failure domain: a hot telemetry plane (Ingestion → Redis Streams → Processor), a business plane (Directus over PostgreSQL/TimescaleDB), and a presentation plane (React SPA). Each component scales, fails, and deploys independently.

Key claims

• The system is structured as three concentric planes — telemetry, business, presentation. Boundaries are enforced by Redis Streams on one side and the database/API on the other; no component reaches across two boundaries. See plane-separation.
• TCP Ingestion maintains persistent device connections, parses vendor binary protocols, ACKs frames, and pushes normalized records to a Redis Stream. It does not apply business rules, write to Postgres, or serve user APIs. See tcp-ingestion.
• Vendor abstraction lives at the Ingestion layer via a protocol adapter interface (bytes in → normalized Position out). Adding a new device family means writing a new adapter; nothing downstream changes. See protocol-adapter.
• The TCP handler never blocks on downstream work. If the Processor or DB is slow, the Stream absorbs pressure; Ingestion keeps accepting and acknowledging. This single discipline is "the difference between a system that survives a bad day and one that doesn't."
• Processor owns domain logic: hot per-device state in memory, durable writes to PostgreSQL/TimescaleDB, derived events. It is the only writer for high-volume telemetry tables (positions hypertable). See processor.
• Directus owns the schema, REST/GraphQL APIs, permissions, WebSockets, admin UI, and Flows — but is not in the telemetry hot path. The Processor writes directly to Directus-owned tables; schema authority stays with Directus. See directus.
• React SPA is the only user-facing surface. It talks exclusively to Directus (REST/GraphQL/WSS via the official SDK); it never touches Ingestion, Processor, Redis, or the database. See react-spa.
• Redis Streams between Ingestion and Processor provides buffering, replayability (consumer-group offsets), and horizontal scaling. NATS or Kafka are reasonable upgrades for multi-region or very high throughput; Redis is the right choice at current scale. See redis-streams.
• Failure domains are isolated. Ingestion crash → devices reconnect. Processor crash → resume from offset. Directus crash → telemetry continues; UI offline. The database is the only single point of failure. See failure-domains.
• Recommended SPA stack: Vite + React + TS, TanStack Router, TanStack Query, @directus/sdk, MapLibre GL + react-map-gl, shadcn/ui + Tailwind, Zustand, react-hook-form + Zod.
• Observability: Redis Stream consumer lag is the single most important metric — it reflects the health of the entire telemetry pipeline in one number.

Notable quotes

"The architecture is deliberately split along the lines of data velocity and failure domain."

"The TCP handler never blocks on downstream work. … This single discipline is the difference between a system that survives a bad day and one that doesn't."

"The architecture deliberately makes the database the only part of the system that requires careful operational attention. Everything else is restartable, replaceable, or naturally redundant."

Open questions / follow-ups

• No specific business domain modeled here ("intentionally generic"). Future sources should clarify the actual TRM domain (events, alerts, geofencing rules).
• WebSocket fan-out limits cited as "tens to low hundreds" of subscribers — what's the expected scale for TRM?
• Multi-region is mentioned as a possible future evolution. Is it on the roadmap?