Comtropy_CargoRadar/docs/ARCHITECTURE.md

Architecture

flowchart LR
    phone["Android driver app"] -->|POST /api/v1/locations| api["CargoRadar API"]
    api --> latest["latest-locations.json"]
    api --> history["locations.jsonl"]
    web["Control web"] -->|GET latest/history| api
    api -->|SSE /api/v1/events| web

MVP Data Flow

1. The Android app starts a foreground location service.
2. The service uploads location JSON with X-Device-Token.
3. The server validates the token against drivers.json.
4. The server stores the newest location per driver and appends history.
5. The control web reads the latest positions and listens for SSE updates.

Storage

The MVP uses simple files:

• drivers.json: driver registry and device tokens.
• latest-locations.json: current position by driver.
• locations.jsonl: append-only location history.

This keeps the first version easy to deploy on Synology NAS. PostgreSQL with PostGIS is the planned upgrade path once route/history queries become central.