# deepakksah/v-gpstracker architecture

> Architecture diagram of the GitHub repository deepakksah/v-gpstracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deepakksah/v-gpstracker
- Repository: https://github.com/deepakksah/v-gpstracker

## Overview

V-Fleet turns vehicle GPS packets into live fleet status and history: device streams are decoded, filtered and evaluated, then served through persistent storage and WebSockets to a dashboard. The dashboard also exposes fleet management, geofences, alerts, playback and reports. Backend source excerpts establish the available implementation modules, while README architecture statements support several connections; unsampled details and some wiring remain unverified, so those relationships are dashed.

Main entry points: [`frontend/src/App.tsx`](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/App.tsx) (Dashboard Shell), [`backend/internal`](https://github.com/deepakksah/v-gpstracker/tree/main/backend/internal) (Alert Evaluation), [`backend/internal/database/db.go`](https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/database/db.go) (Database Access), [`frontend/src/components/TelemetryDrawer.tsx`](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/components/TelemetryDrawer.tsx) (Telemetry Drawer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Telemetry Ingestion"]
  node_simulator["Fleet Simulator<br/>[main.go]"]
  node_listeners["Socket Listeners<br/>[listener.go]"]
  node_parsers["Protocol Parsers"]
end

subgraph group_processing["Processing and Storage"]
  node_filter["Kalman Filter<br/>[kalman.go]"]
  node_rules["Alert Evaluation"]
  node_state["Hot State Cache<br/>[state.go]"]
  node_database["Database Access<br/>[db.go]"]
end

subgraph group_services["Fleet Services"]
  node_websocket["WebSocket Hub<br/>[hub.go]"]
  node_api["REST API<br/>[routes.go]"]
  node_reporter["Scheduled Reports<br/>[reporter.go]"]
end

subgraph group_dashboard["Fleet Dashboard"]
  node_app["Dashboard Shell<br/>[App.tsx]"]
  node_map["Live Fleet Map<br/>[FleetMap.tsx]"]
  node_drawer["Telemetry Drawer"]
  node_geocoding["Reverse Geocoding<br/>[geocoding.ts]"]
  node_vehicleimages["Vehicle Illustrations<br/>[vehicleImages.tsx]"]
  node_playback["Trip Playback<br/>[PlaybackView.tsx]"]
  node_geofences["Geofence Manager<br/>[GeofencesView.tsx]"]
  node_alerts["Alerts View<br/>[AlertsView.tsx]"]
  node_fleet["Fleet Management"]
  node_reports["Reports View<br/>[ReportsView.tsx]"]
end

node_devices(("GPS Devices"))
node_postgres[("PostgreSQL")]
node_browser(("Fleet Operator"))

node_devices -->|"send packets"| node_listeners
node_simulator -->|"sends telemetry"| node_listeners
node_listeners -->|"decode packets"| node_parsers
node_parsers -->|"filter fixes"| node_filter
node_filter -.->|"evaluate telemetry"| node_rules
node_rules -->|"update hot state"| node_state
node_rules -->|"write telemetry"| node_database
node_state -->|"publish updates"| node_websocket
node_rules -.->|"broadcast alerts"| node_websocket
node_database -.->|"read and write"| node_postgres
node_api -->|"access records"| node_database
node_reporter -.->|"query telemetry"| node_database
node_websocket -->|"push live updates"| node_app
node_api -->|"serve dashboard data"| node_app
node_browser -.->|"use dashboard"| node_app
node_app -->|"renders"| node_map
node_app -->|"renders"| node_drawer
node_app -->|"renders"| node_playback
node_app -->|"renders"| node_geofences
node_app -.->|"renders"| node_alerts
node_app -->|"renders"| node_fleet
node_app -->|"renders"| node_reports
node_drawer -->|"fetches locations"| node_geocoding
node_drawer -->|"renders"| node_vehicleimages
node_app -->|"renders"| node_vehicleimages

click node_simulator "https://github.com/deepakksah/v-gpstracker/blob/main/backend/cmd/simulator/main.go"
click node_listeners "https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/ingestion/listener.go"
click node_parsers "https://github.com/deepakksah/v-gpstracker/tree/main/backend/internal/ingestion"
click node_filter "https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/filter/kalman.go"
click node_rules "https://github.com/deepakksah/v-gpstracker/tree/main/backend/internal"
click node_state "https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/state/state.go"
click node_database "https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/database/db.go"
click node_websocket "https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/websocket/hub.go"
click node_api "https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/api/routes.go"
click node_reporter "https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/cron/reporter.go"
click node_app "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/App.tsx"
click node_map "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/components/FleetMap.tsx"
click node_drawer "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/components/TelemetryDrawer.tsx"
click node_geocoding "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/utils/geocoding.ts"
click node_vehicleimages "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/utils/vehicleImages.tsx"
click node_playback "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/PlaybackView.tsx"
click node_geofences "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/GeofencesView.tsx"
click node_alerts "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/AlertsView.tsx"
click node_fleet "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/FleetManagementView.tsx"
click node_reports "https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/ReportsView.tsx"

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_simulator,node_listeners,node_parsers toneBlue
class node_filter,node_rules,node_state,node_database,node_postgres toneAmber
class node_websocket,node_api,node_reporter toneMint
class node_app,node_map,node_drawer,node_geocoding,node_vehicleimages,node_playback,node_geofences,node_alerts,node_fleet,node_reports toneRose
class node_devices,node_browser toneIndigo
```

## Components

### Telemetry Ingestion

- [Fleet Simulator](https://github.com/deepakksah/v-gpstracker/blob/main/backend/cmd/simulator/main.go): `backend/cmd/simulator/main.go`
- [Socket Listeners](https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/ingestion/listener.go): `backend/internal/ingestion/listener.go`
- [Protocol Parsers](https://github.com/deepakksah/v-gpstracker/tree/main/backend/internal/ingestion): `backend/internal/ingestion`

### Processing and Storage

- [Kalman Filter](https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/filter/kalman.go): `backend/internal/filter/kalman.go`
- [Alert Evaluation](https://github.com/deepakksah/v-gpstracker/tree/main/backend/internal): `backend/internal`
- [Hot State Cache](https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/state/state.go): `backend/internal/state/state.go`
- [Database Access](https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/database/db.go): `backend/internal/database/db.go`

### Fleet Services

- [WebSocket Hub](https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/websocket/hub.go): `backend/internal/websocket/hub.go`
- [REST API](https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/api/routes.go): `backend/internal/api/routes.go`
- [Scheduled Reports](https://github.com/deepakksah/v-gpstracker/blob/main/backend/internal/cron/reporter.go): `backend/internal/cron/reporter.go`

### Fleet Dashboard

- [Dashboard Shell](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Live Fleet Map](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/components/FleetMap.tsx): `frontend/src/components/FleetMap.tsx`
- [Telemetry Drawer](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/components/TelemetryDrawer.tsx): `frontend/src/components/TelemetryDrawer.tsx`
- [Reverse Geocoding](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/utils/geocoding.ts): `frontend/src/utils/geocoding.ts`
- [Vehicle Illustrations](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/utils/vehicleImages.tsx): `frontend/src/utils/vehicleImages.tsx`
- [Trip Playback](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/PlaybackView.tsx): `frontend/src/views/PlaybackView.tsx`
- [Geofence Manager](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/GeofencesView.tsx): `frontend/src/views/GeofencesView.tsx`
- [Alerts View](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/AlertsView.tsx): `frontend/src/views/AlertsView.tsx`
- [Fleet Management](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/FleetManagementView.tsx): `frontend/src/views/FleetManagementView.tsx`
- [Reports View](https://github.com/deepakksah/v-gpstracker/blob/main/frontend/src/views/ReportsView.tsx): `frontend/src/views/ReportsView.tsx`

### Other components

- **GPS Devices**
- **PostgreSQL**
- **Fleet Operator**

## Connections

- GPS Devices → Socket Listeners: send packets (evidence: `README.md`)
- Fleet Simulator → Socket Listeners: sends telemetry (evidence: `README.md`)
- Socket Listeners → Protocol Parsers: decode packets (evidence: `README.md`)
- Protocol Parsers → Kalman Filter: filter fixes (evidence: `README.md`)
- Kalman Filter → Alert Evaluation: evaluate telemetry
- Alert Evaluation → Hot State Cache: update hot state (evidence: `README.md`)
- Alert Evaluation → Database Access: write telemetry (evidence: `README.md`)
- Hot State Cache → WebSocket Hub: publish updates (evidence: `README.md`)
- Alert Evaluation → WebSocket Hub: broadcast alerts
- Database Access → PostgreSQL: read and write
- REST API → Database Access: access records (evidence: `README.md`)
- Scheduled Reports → Database Access: query telemetry
- WebSocket Hub → Dashboard Shell: push live updates (evidence: `README.md`)
- REST API → Dashboard Shell: serve dashboard data (evidence: `README.md`)
- Fleet Operator → Dashboard Shell: use dashboard
- Dashboard Shell → Live Fleet Map: renders (evidence: `frontend/src/App.tsx`)
- Dashboard Shell → Telemetry Drawer: renders (evidence: `frontend/src/App.tsx`)
- Dashboard Shell → Trip Playback: renders (evidence: `frontend/src/App.tsx`)
- Dashboard Shell → Geofence Manager: renders (evidence: `frontend/src/App.tsx`)
- Dashboard Shell → Alerts View: renders (evidence: `frontend/src/App.tsx`)
- Dashboard Shell → Fleet Management: renders (evidence: `frontend/src/App.tsx`)
- Dashboard Shell → Reports View: renders (evidence: `frontend/src/App.tsx`)
- Telemetry Drawer → Reverse Geocoding: fetches locations (evidence: `frontend/src/components/TelemetryDrawer.tsx`)
- Telemetry Drawer → Vehicle Illustrations: renders (evidence: `frontend/src/components/TelemetryDrawer.tsx`)
- Dashboard Shell → Vehicle Illustrations: renders (evidence: `frontend/src/App.tsx`)
