Bootstrap LLM-maintained wiki with TRM architecture knowledge

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.
2026-04-30 13:12:24 +02:00
parent d62d50b30b
commit 22b1b069df
24 changed files with 3084 additions and 0 deletions
@@ -0,0 +1,57 @@
+---
+title: React SPA
+type: entity
+created: 2026-04-30
+updated: 2026-04-30
+sources: [gps-tracking-architecture]
+tags: [service, presentation-plane, frontend]
+---
+
+# React SPA
+
+The end-user experience for operators and external participants. Single React application, role-based views, served as a static bundle.
+
+## Why a separate SPA (not just the Directus admin UI)
+
+The Directus admin UI is generic CRUD over collections — right for back-office editing and operators who think in records, wrong for end users who think in domain concepts. A dedicated SPA delivers:
+
+- **Domain-shaped UX** — screens organized around the user's mental model.
+- **Independent deployment** — front-end ships on its own cadence.
+- **Targeted access control** — public/partner-facing routes without exposing the admin surface.
+- **Mobile/offline tuning** — bundles tuned for the actual user environment.
+
+## Single app, role-based views
+
+One application serves multiple user types via role-based routing and conditional UI. All users authenticate through [[directus]]; the SPA receives a JWT, reads role, and renders appropriate navigation/screens. Splitting into multiple apps is only justified when user populations are genuinely disjoint (public site vs. authenticated console) or when bundle size for one audience harms another.
+
+## Data access pattern
+
+The SPA talks **exclusively** to Directus:
+
+- REST/GraphQL via `@directus/sdk`.
+- WebSocket subscriptions via the same SDK.
+- JWT auth managed by the SDK; refresh handled transparently.
+
+**Never** talks to the [[processor]], [[tcp-ingestion]], [[redis-streams]], or [[postgres-timescaledb]] directly. This boundary lets the back-end evolve internally and keeps the security model coherent — every request goes through Directus's permission system.
+
+## Recommended stack
+
+- **Vite + React + TypeScript**
+- **TanStack Router** — better TS support than React Router; optional file-based routing
+- **TanStack Query** — server state, caching, invalidation, optimistic updates
+- **@directus/sdk** — typed access + real-time
+- **MapLibre GL + react-map-gl** — open-source WebGL maps, no token needed
+- **shadcn/ui + Tailwind** — UI primitives
+- **Zustand** — client-only state (filters, UI prefs)
+- **react-hook-form + Zod** — forms and validation
+
+Covers the spectrum from form-heavy admin screens to real-time map dashboards without architectural changes between them.
+
+## Real-time rendering
+
+- **Live maps with many markers**: React reconciler is not the bottleneck — drawing happens in WebGL via MapLibre, which manages features outside React's tree. The React layer manages subscriptions and feeds the map updates.
+- **High-frequency tabular updates** (live leaderboards, event feeds): split components so high-update areas re-render in isolation; use TanStack Query for live data; memoize at component boundaries that receive frequent updates.
+
+## Failure mode
+
+UI unavailable → back-end unaffected. See [[failure-domains]].