# mohcinch/smart-gps architecture

> Architecture diagram of the GitHub repository mohcinch/smart-gps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohcinch/smart-gps
- Repository: https://github.com/mohcinch/smart-gps

## Overview

VTrack is an IoT vehicle-tracking and safety platform. Its main flow is a vehicle tracker sending authenticated VTP frames to the TCP gateway, which persists data and fans live updates to Redis; background workers process trips, geofences, behavior and alerts, while users access tracking and management through the REST and WebSocket APIs. The repository also includes self-hosted map tiles and supporting product services. README capabilities inform unsampled subsystem nodes; the supplied tree has no Flutter application source, so app internals are not mapped.

Main entry points: [`server/internal/worker`](https://github.com/mohcinch/smart-gps/tree/main/server/internal/worker) (Worker jobs), [`server/internal/httpapi`](https://github.com/mohcinch/smart-gps/tree/main/server/internal/httpapi) (REST API), [`server/internal/ingest/server.go`](https://github.com/mohcinch/smart-gps/blob/main/server/internal/ingest/server.go) (VTP gateway), [`server/internal/trips/engine.go`](https://github.com/mohcinch/smart-gps/blob/main/server/internal/trips/engine.go) (Trip engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Device ingest"]
  node_gateway["VTP gateway<br/>[server.go]"]
  node_protocol["VTP protocol"]
  node_key_security["Device keys"]
  node_outbox["Ingest outbox<br/>[outbox.go]"]
end

subgraph group_processing["Fleet processing"]
  node_worker["Worker jobs"]
  node_trips["Trip engine<br/>[engine.go]"]
  node_geofences["Geofence engine<br/>[engine.go]"]
  node_behaviour["Driving behavior<br/>[behaviour.go]"]
  node_alerts["Alerts and theft"]
  node_reports["Reports and billing"]
  node_notifications["Notification delivery"]
  node_safety_features["Anti-theft safeguards<br/>[antitheft.go]"]
end

subgraph group_user_services["User services"]
  node_api["REST API"]
  node_auth["Authentication"]
  node_commands["Commands and OTA"]
  node_live["WebSocket feed"]
  node_tiles["Map tile service<br/>[server.go]"]
end

subgraph group_platform["Platform services"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_tracker(("Vehicle tracker"))
node_user(("Vehicle owner"))
node_mobile(("Flutter app"))

node_tracker -->|"sends frames"| node_gateway
node_gateway -->|"decodes frames"| node_protocol
node_gateway -->|"authenticates device"| node_key_security
node_gateway -->|"persists data"| node_postgres
node_gateway -->|"fans out live data"| node_redis
node_gateway -->|"queues processing"| node_outbox
node_worker -->|"processes queued data"| node_outbox
node_worker -->|"reads and writes"| node_postgres
node_worker -->|"coordinates jobs"| node_redis
node_worker -->|"updates trips"| node_trips
node_worker -->|"evaluates positions"| node_geofences
node_trips -->|"scores trips"| node_behaviour
node_worker -->|"processes alerts"| node_alerts
node_worker -->|"checks theft signals"| node_safety_features
node_worker -->|"runs report jobs"| node_reports
node_worker -->|"delivers notices"| node_notifications
node_user -->|"uses"| node_mobile
node_mobile -->|"requests tracking"| node_api
node_api -->|"authenticates requests"| node_auth
node_api -->|"reads and writes"| node_postgres
node_api -->|"uses shared state"| node_redis
node_api -->|"creates device commands"| node_commands
node_api -->|"starts report exports"| node_reports
node_api -->|"sends account notices"| node_notifications
node_mobile -->|"subscribes to updates"| node_live
node_live -->|"receives live events"| node_redis
node_mobile -->|"requests map tiles"| node_tiles

click node_gateway "https://github.com/mohcinch/smart-gps/blob/main/server/internal/ingest/server.go"
click node_protocol "https://github.com/mohcinch/smart-gps/tree/main/server/internal/vtp"
click node_key_security "https://github.com/mohcinch/smart-gps/tree/main/server/internal/devkeys"
click node_outbox "https://github.com/mohcinch/smart-gps/blob/main/server/internal/outbox/outbox.go"
click node_worker "https://github.com/mohcinch/smart-gps/tree/main/server/internal/worker"
click node_trips "https://github.com/mohcinch/smart-gps/blob/main/server/internal/trips/engine.go"
click node_geofences "https://github.com/mohcinch/smart-gps/blob/main/server/internal/geofence/engine.go"
click node_behaviour "https://github.com/mohcinch/smart-gps/blob/main/server/internal/behaviour/behaviour.go"
click node_alerts "https://github.com/mohcinch/smart-gps/tree/main/server/internal/alerts"
click node_reports "https://github.com/mohcinch/smart-gps/tree/main/server/internal/reports"
click node_notifications "https://github.com/mohcinch/smart-gps/tree/main/server/internal/notify"
click node_api "https://github.com/mohcinch/smart-gps/tree/main/server/internal/httpapi"
click node_auth "https://github.com/mohcinch/smart-gps/tree/main/server/internal/auth"
click node_commands "https://github.com/mohcinch/smart-gps/tree/main/server/internal/commands"
click node_live "https://github.com/mohcinch/smart-gps/tree/main/server/internal/ws"
click node_tiles "https://github.com/mohcinch/smart-gps/blob/main/server/internal/tiles/server.go"
click node_safety_features "https://github.com/mohcinch/smart-gps/blob/main/server/internal/antitheft/antitheft.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_protocol,node_key_security,node_outbox toneBlue
class node_worker,node_trips,node_geofences,node_behaviour,node_alerts,node_reports,node_notifications,node_safety_features toneAmber
class node_api,node_auth,node_commands,node_live,node_tiles toneMint
class node_postgres,node_redis toneRose
class node_tracker,node_user,node_mobile toneIndigo
```

## Components

### Device ingest

- [VTP gateway](https://github.com/mohcinch/smart-gps/blob/main/server/internal/ingest/server.go): `server/internal/ingest/server.go`
- [VTP protocol](https://github.com/mohcinch/smart-gps/tree/main/server/internal/vtp): `server/internal/vtp`
- [Device keys](https://github.com/mohcinch/smart-gps/tree/main/server/internal/devkeys): `server/internal/devkeys`
- [Ingest outbox](https://github.com/mohcinch/smart-gps/blob/main/server/internal/outbox/outbox.go): `server/internal/outbox/outbox.go`

### Fleet processing

- [Worker jobs](https://github.com/mohcinch/smart-gps/tree/main/server/internal/worker): `server/internal/worker`
- [Trip engine](https://github.com/mohcinch/smart-gps/blob/main/server/internal/trips/engine.go): `server/internal/trips/engine.go`
- [Geofence engine](https://github.com/mohcinch/smart-gps/blob/main/server/internal/geofence/engine.go): `server/internal/geofence/engine.go`
- [Driving behavior](https://github.com/mohcinch/smart-gps/blob/main/server/internal/behaviour/behaviour.go): `server/internal/behaviour/behaviour.go`
- [Alerts and theft](https://github.com/mohcinch/smart-gps/tree/main/server/internal/alerts): `server/internal/alerts`
- [Reports and billing](https://github.com/mohcinch/smart-gps/tree/main/server/internal/reports): `server/internal/reports`
- [Notification delivery](https://github.com/mohcinch/smart-gps/tree/main/server/internal/notify): `server/internal/notify`
- [Anti-theft safeguards](https://github.com/mohcinch/smart-gps/blob/main/server/internal/antitheft/antitheft.go): `server/internal/antitheft/antitheft.go`

### User services

- [REST API](https://github.com/mohcinch/smart-gps/tree/main/server/internal/httpapi): `server/internal/httpapi`
- [Authentication](https://github.com/mohcinch/smart-gps/tree/main/server/internal/auth): `server/internal/auth`
- [Commands and OTA](https://github.com/mohcinch/smart-gps/tree/main/server/internal/commands): `server/internal/commands`
- [WebSocket feed](https://github.com/mohcinch/smart-gps/tree/main/server/internal/ws): `server/internal/ws`
- [Map tile service](https://github.com/mohcinch/smart-gps/blob/main/server/internal/tiles/server.go): `server/internal/tiles/server.go`

### Platform services

- **PostgreSQL**
- **Redis**

### Other components

- **Vehicle tracker**
- **Vehicle owner**
- **Flutter app**

## Connections

- Vehicle tracker → VTP gateway: sends frames
- VTP gateway → VTP protocol: decodes frames
- VTP gateway → Device keys: authenticates device
- VTP gateway → PostgreSQL: persists data
- VTP gateway → Redis: fans out live data
- VTP gateway → Ingest outbox: queues processing
- Worker jobs → Ingest outbox: processes queued data
- Worker jobs → PostgreSQL: reads and writes
- Worker jobs → Redis: coordinates jobs
- Worker jobs → Trip engine: updates trips
- Worker jobs → Geofence engine: evaluates positions
- Trip engine → Driving behavior: scores trips
- Worker jobs → Alerts and theft: processes alerts
- Worker jobs → Anti-theft safeguards: checks theft signals
- Worker jobs → Reports and billing: runs report jobs
- Worker jobs → Notification delivery: delivers notices
- Vehicle owner → Flutter app: uses
- Flutter app → REST API: requests tracking
- REST API → Authentication: authenticates requests
- REST API → PostgreSQL: reads and writes
- REST API → Redis: uses shared state
- REST API → Commands and OTA: creates device commands
- REST API → Reports and billing: starts report exports
- REST API → Notification delivery: sends account notices
- Flutter app → WebSocket feed: subscribes to updates
- WebSocket feed → Redis: receives live events
- Flutter app → Map tile service: requests map tiles