# Architecture

```mermaid
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.