Build Fase 1 — MVP (Foundation)
Dit document beschrijft wat Fase 1 inhoudt, wat bewust níet in scope is, en hoe dit aansluit op de OmniTrack-repository. Het is een bouw- en acceptatiekader, geen marketingtekst.
Typische schaal (richting): ~1k–10k devices, beperkt aantal gelijktijdige gebruikers — te valideren met tests.
1. Doel
Een minimum werkend platform dat:
- trackers ontvangt (TCP ingest, basisprotocol),
- data persisteert in PostgreSQL,
- een basis-UI heeft (login, voertuigen, laatste positie, kaart),
- authenticatie heeft,
- monitoring genoeg heeft om storingsdiagnose mogelijk te maken.
Niet-doelen (Fase 1):
- Geen Kafka / Redpanda (event backbone komt in Fase 2).
- Geen ClickHouse (analytics-/bulktelemetrica-laag komt in Fase 2).
- Geen multi-region, geen volledige enterprise-RBAC, geen billing.
2. Core infrastructuur (1.1)
| Onderdeel | Richting |
|---|---|
| Regio’s | Eén regio (bijv. EU) |
| Infra | VM’s of kleine cluster (Docker Compose acceptabel voor dev/staging) |
| Load balancing | TCP (trackers → gateway-poort) + HTTP/S (clients → app) — bijv. HAProxy / NGINX |
| Omvang (richting) | 3–4 servers totaal voor eerste productieachtige opzet |
Beslissing: TLS en WAF bij voorkeur op de reverse proxy; app-configuratie volgens README.md (TRUST_PROXY, geen brekende HSTS op plain HTTP).
3. Ingest (1.2)
| Vereiste | Toelichting |
|---|---|
| TCP-listener | Apart proces van de HTTP-API (binary protocol niet mengen met request-per-request webtraffic) |
| IMEI / device handshake | Alleen bekende devices (inventory eerst) |
| Basis AVL-parsing | Minimaal het protocol dat de velddevices gebruiken (bijv. Codec 8 voor Teltonika-class) |
| ACK | Correcte server-antwoorden volgens protocol |
| Opslag | PostgreSQL als tijdelijke alles-in-één store; ruwe bytes/events kunnen in een dedicated tabel |
In deze repo: services/telematics-gateway/, Docker-service telematics-gateway, documentatie onder docs/telematics/README.md.
Tabel voor ruwe / traceerbare data: in het schema bestaat o.a. device_ingest_raw (doel: troubleshooting en audit van binnenkomende data). Dat vervult de functie van “tijdelijk raw storage” in Postgres.
4. Database — basis (1.3)
PostgreSQL als bron voor:
- gebruikers en rollen (of koppeling naar IdP),
- tenants/organisaties (in deze school-app o.a.
schools/ logische tenantgrenzen — evolueer naar expliciettenant-model wanneer nodig), - devices, voertuigen/bussen, trips,
- sessies (indien geen volledig stateless JWT),
- positions / online status / ruwe ingest (huidige tabellen o.a.
device_positions,device_online,device_ingest_raw).
Fase 1: werkende schema’s, backups, geen verplichte partitionering of ClickHouse-migratie.
5. Identity — login (1.4)
Roadmap-doel (platformplan): Keycloak (enkele instance in MVP), OIDC, registratie, rollen admin / user.
Huidige repo: sessie-gebaseerde login via Express + connect-pg-simple (PostgreSQL session-tabel), rollen in users (o.a. overheid, driver, school). Dat is een werkende MVP-login, maar niet dezelfde stack als Keycloak.
| Optie | Wanneer |
|---|---|
| A. Keycloak nu integreren | Als OIDC/MFA en centraal IdP vanaf MVP verplicht zijn — meer integratiewerk in Fase 1. |
| B. Huidige auth behouden + Keycloak in v1 | Sneller “werkend” platform; plan expliciet migratiepad naar Keycloak in Fase 2 samen met JWT/rate limits. |
Gekozen voor deze codebase (Fase 1): optie B — sessie-auth blijft; Keycloak is doel voor Fase 2/v1 samen met gateway-JWT en strakkere rate limits.
6. Webapp — basis (1.5)
| Feature | Beschrijving |
|---|---|
| Login | Zie §5 |
| Voertuig-/fleetlijst | Overzicht bussen/devices |
| Laatste locatie | Uit API of realtime kanaal |
| Eenvoudige kaart | Live of near-live markers |
In deze repo: React (Vite), meertalige UI (src/locales/ — en, ar-IQ, ckb). Nieuwe zichtbare strings: altijd drie talen bij UI-wijzigingen.
7. Basis monitoring (1.6)
| Type | Minimum |
|---|---|
| Logs | Gestructureerd of grep-vriendelijk; ingest + API + gateway |
| Metrics | Gateway: Prometheus-endpoint op METRICS_PORT (compose: 127.0.0.1:9092); app: GET /metrics (Prometheus text, zelfde poort als HTTP API) |
| Uptime / health | Liveness: GET /healthz — proces draait. Readiness: GET /readyz — PostgreSQL reageert (503 als DB weg) |
8. Definition of Done — Fase 1 MVP
Gebruik deze checklist om “Fase 1 af” te verklaren:
- Ingest: devices kunnen verbinden; IMEI wordt herkend; records worden verwerkt en opgeslagen; ACK’s kloppen met protocol — zie
services/telematics-gateway/,docs/telematics/. - PostgreSQL: schema actueel; backups getest (restore-oefening aanbevolen) — zie
backup-restore.md. - API + UI: ingelogde gebruiker ziet voertuigen en recente positie op de kaart (volgens rol).
- Auth: optie B (sessieauth); Keycloak gepland v1/Fase 2 — zie §5.
- Monitoring: logs + gateway-metrics (
:9092) + app/healthz,/readyz,/metrics. - Documentatie: telematics runbooks; README met health-endpoints en platform roadmap; voorbeeld load balancer
examples/nginx-lb-example.conf.
9. Volgende stap — Fase 2 (kort)
Wanneer MVP stabiel is: Kafka/Redpanda, ClickHouse voor telematica-historiek, Redis, opsplitsing ingest/API/services, command- en notificatieflows, verdere security (TLS/JWT/rate limits) — zie het platformplan (Cursor-plan of toekomstige docs/platform/phase-2-v1.md).
10. Referenties
- Telematics gateway & protocol:
docs/telematics/README.md - Gateway ADR (scheiding processen):
docs/telematics/adr/0001-gateway-separate-service.md - Backup / restore:
backup-restore.md - NGINX-voorbeeld (HTTP + TCP ingest):
examples/README.md - Applicatie README:
README.md