# harini-buildon/roadtrack-ai architecture

> Architecture diagram of the GitHub repository harini-buildon/roadtrack-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harini-buildon/roadtrack-ai
- Repository: https://github.com/harini-buildon/roadtrack-ai

## Overview

RoadTrack AI presents a traffic-intelligence command center for multi-camera vehicle tracking, cross-camera association, route forecasting, and alerts. The intended workflow is camera observations through vision processing and track association, then road-graph-informed prediction and operator-facing maps. The excerpts show the API router’s dependencies, prediction and association internals, and map composition, but do not establish a live camera-ingestion deployment or every UI-to-API connection. The README describes additional capabilities—such as ALPR, homography, RBAC, and Gemini forensics—that are not fully verifiable in the sampled implementation.

Main entry points: [`src/server/routes.ts`](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/routes.ts) (API Routes), [`src/App.tsx`](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/App.tsx) (Application Shell), [`src/server/db/inMemoryDb.ts`](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/db/inMemoryDb.ts) (Tracking State), [`src/components/TrafficIntelligenceDashboard.tsx`](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/TrafficIntelligenceDashboard.tsx) (Intelligence Map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Operator Interface"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_traffic_ui["Traffic Dashboard"]
  node_association_ui["Association View"]
  node_alerts_ui["Alerts View<br/>[AlertsTab.tsx]"]
  node_audit_ui["Audit Trail<br/>[AuditTrailTab.tsx]"]
  node_drive["Drive Export"]
  node_drive_auth["Drive Authorization<br/>[googleDriveAuth.ts]"]
end

subgraph group_api["API Orchestration"]
  node_router["API Routes<br/>[routes.ts]"]
end

subgraph group_tracking["Tracking Intelligence"]
  node_vision["Vision Pipeline<br/>[visionPipeline.ts]"]
  node_association["Track Association"]
  node_state[("Tracking State<br/>[inMemoryDb.ts]")]
  node_alerts["Alert Engine<br/>[alertEngine.ts]"]
end

subgraph group_spatial["Spatial Prediction"]
  node_graph_engine["Road Graph<br/>[roadGraphEngine.ts]"]
  node_prediction["Route Prediction"]
  node_evaluation["Model Evaluation"]
  node_gemini["Route Forensics<br/>[geminiService.ts]"]
end

subgraph group_presentation["Command Visualization"]
  node_command_map["Command Map"]
  node_dashboard_map["Intelligence Map"]
  node_maplibre["MapLibre Renderer"]
  node_osm["Realtime OSM Map"]
  node_vehicle_layer["Vehicle Layer<br/>[VehicleLayer.tsx]"]
  node_route_layer["Prediction Layer"]
  node_alert_layer["Alert Layer<br/>[AlertLayer.tsx]"]
  node_projection["Geo Projection"]
end

node_operator(("Operator"))
node_google_drive(("Google Drive"))

node_operator -->|"uses"| node_app
node_app -->|"renders"| node_traffic_ui
node_app -->|"renders"| node_association_ui
node_app -->|"renders"| node_alerts_ui
node_app -->|"renders"| node_audit_ui
node_router -->|"reads and writes"| node_state
node_router -->|"invokes"| node_vision
node_router -->|"invokes"| node_association
node_router -->|"invokes"| node_prediction
node_router -->|"invokes"| node_alerts
node_router -->|"invokes"| node_evaluation
node_router -->|"invokes"| node_gemini
node_association -->|"reads"| node_state
node_prediction -->|"reads"| node_state
node_prediction -->|"gets outgoing edges"| node_graph_engine
node_graph_engine -->|"reads road data"| node_state
node_alerts -->|"reads and records alerts"| node_state
node_app -->|"renders"| node_command_map
node_command_map -->|"selects renderer"| node_maplibre
node_command_map -->|"selects renderer"| node_osm
node_traffic_ui -->|"renders map"| node_dashboard_map
node_dashboard_map -->|"uses layer"| node_vehicle_layer
node_dashboard_map -->|"uses layer"| node_route_layer
node_dashboard_map -->|"uses layer"| node_alert_layer
node_vehicle_layer -->|"projects coordinates"| node_projection
node_route_layer -->|"projects coordinates"| node_projection
node_drive -->|"uses authorization"| node_drive_auth
node_drive_auth -.->|"authorizes access"| node_google_drive

click node_app "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/App.tsx"
click node_traffic_ui "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/TrafficIntelligenceDashboard.tsx"
click node_association_ui "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/VehicleAssociationTab.tsx"
click node_alerts_ui "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/AlertsTab.tsx"
click node_audit_ui "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/AuditTrailTab.tsx"
click node_router "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/routes.ts"
click node_vision "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/ai/visionPipeline.ts"
click node_association "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/ai/associationEngine.ts"
click node_state "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/db/inMemoryDb.ts"
click node_alerts "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/services/alertEngine.ts"
click node_graph_engine "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/graph/roadGraphEngine.ts"
click node_prediction "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/ai/predictionEngine.ts"
click node_evaluation "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/services/modelEvaluationService.ts"
click node_gemini "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/ai/geminiService.ts"
click node_command_map "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/EcoCommandCenterMap.tsx"
click node_dashboard_map "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/TrafficIntelligenceDashboard.tsx"
click node_maplibre "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/MapLibreCommandMap.tsx"
click node_osm "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/RealtimeOpenStreetMap.tsx"
click node_vehicle_layer "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/VehicleLayer.tsx"
click node_route_layer "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/PredictionRouteLayer.tsx"
click node_alert_layer "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/AlertLayer.tsx"
click node_projection "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/services/map/GeoProjectionService.ts"
click node_drive "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/services/googleDriveService.ts"
click node_drive_auth "https://github.com/harini-buildon/roadtrack-ai/blob/main/src/services/googleDriveAuth.ts"

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_app,node_traffic_ui,node_association_ui,node_alerts_ui,node_audit_ui,node_drive,node_drive_auth toneBlue
class node_router toneAmber
class node_vision,node_association,node_state,node_alerts toneMint
class node_graph_engine,node_prediction,node_evaluation,node_gemini toneRose
class node_command_map,node_dashboard_map,node_maplibre,node_osm,node_vehicle_layer,node_route_layer,node_alert_layer,node_projection,node_operator,node_google_drive toneIndigo
```

## Components

### Operator Interface

- [Application Shell](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/App.tsx): `src/App.tsx`
- [Traffic Dashboard](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/TrafficIntelligenceDashboard.tsx): `src/components/TrafficIntelligenceDashboard.tsx`
- [Association View](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/VehicleAssociationTab.tsx): `src/components/VehicleAssociationTab.tsx`
- [Alerts View](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/AlertsTab.tsx): `src/components/AlertsTab.tsx`
- [Audit Trail](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/AuditTrailTab.tsx): `src/components/AuditTrailTab.tsx`
- [Drive Export](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/services/googleDriveService.ts): `src/services/googleDriveService.ts`
- [Drive Authorization](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/services/googleDriveAuth.ts): `src/services/googleDriveAuth.ts`

### API Orchestration

- [API Routes](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/routes.ts): `src/server/routes.ts`

### Tracking Intelligence

- [Vision Pipeline](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/ai/visionPipeline.ts): `src/server/ai/visionPipeline.ts`
- [Track Association](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/ai/associationEngine.ts): `src/server/ai/associationEngine.ts`
- [Tracking State](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/db/inMemoryDb.ts): `src/server/db/inMemoryDb.ts`
- [Alert Engine](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/services/alertEngine.ts): `src/server/services/alertEngine.ts`

### Spatial Prediction

- [Road Graph](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/graph/roadGraphEngine.ts): `src/server/graph/roadGraphEngine.ts`
- [Route Prediction](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/ai/predictionEngine.ts): `src/server/ai/predictionEngine.ts`
- [Model Evaluation](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/services/modelEvaluationService.ts): `src/server/services/modelEvaluationService.ts`
- [Route Forensics](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/server/ai/geminiService.ts): `src/server/ai/geminiService.ts`

### Command Visualization

- [Command Map](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/EcoCommandCenterMap.tsx): `src/components/EcoCommandCenterMap.tsx`
- [Intelligence Map](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/TrafficIntelligenceDashboard.tsx): `src/components/TrafficIntelligenceDashboard.tsx`
- [MapLibre Renderer](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/MapLibreCommandMap.tsx): `src/components/map/MapLibreCommandMap.tsx`
- [Realtime OSM Map](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/RealtimeOpenStreetMap.tsx): `src/components/map/RealtimeOpenStreetMap.tsx`
- [Vehicle Layer](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/VehicleLayer.tsx): `src/components/map/VehicleLayer.tsx`
- [Prediction Layer](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/PredictionRouteLayer.tsx): `src/components/map/PredictionRouteLayer.tsx`
- [Alert Layer](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/components/map/AlertLayer.tsx): `src/components/map/AlertLayer.tsx`
- [Geo Projection](https://github.com/harini-buildon/roadtrack-ai/blob/main/src/services/map/GeoProjectionService.ts): `src/services/map/GeoProjectionService.ts`

### Other components

- **Operator**
- **Google Drive**

## Connections

- Operator → Application Shell: uses
- Application Shell → Traffic Dashboard: renders (evidence: `src/App.tsx`)
- Application Shell → Association View: renders (evidence: `src/App.tsx`)
- Application Shell → Alerts View: renders (evidence: `src/App.tsx`)
- Application Shell → Audit Trail: renders (evidence: `src/App.tsx`)
- API Routes → Tracking State: reads and writes (evidence: `src/server/routes.ts`)
- API Routes → Vision Pipeline: invokes (evidence: `src/server/routes.ts`)
- API Routes → Track Association: invokes (evidence: `src/server/routes.ts`)
- API Routes → Route Prediction: invokes (evidence: `src/server/routes.ts`)
- API Routes → Alert Engine: invokes (evidence: `src/server/routes.ts`)
- API Routes → Model Evaluation: invokes (evidence: `src/server/routes.ts`)
- API Routes → Route Forensics: invokes (evidence: `src/server/routes.ts`)
- Track Association → Tracking State: reads (evidence: `src/server/ai/associationEngine.ts`)
- Route Prediction → Tracking State: reads (evidence: `src/server/ai/predictionEngine.ts`)
- Route Prediction → Road Graph: gets outgoing edges (evidence: `src/server/ai/predictionEngine.ts`)
- Road Graph → Tracking State: reads road data (evidence: `src/server/graph/roadGraphEngine.ts`)
- Alert Engine → Tracking State: reads and records alerts (evidence: `src/server/services/alertEngine.ts`)
- Application Shell → Command Map: renders (evidence: `src/App.tsx`)
- Command Map → MapLibre Renderer: selects renderer (evidence: `src/components/EcoCommandCenterMap.tsx`)
- Command Map → Realtime OSM Map: selects renderer (evidence: `src/components/EcoCommandCenterMap.tsx`)
- Traffic Dashboard → Intelligence Map: renders map (evidence: `src/components/TrafficIntelligenceDashboard.tsx`)
- Intelligence Map → Vehicle Layer: uses layer (evidence: `src/components/TrafficIntelligenceDashboard.tsx`)
- Intelligence Map → Prediction Layer: uses layer (evidence: `src/components/TrafficIntelligenceDashboard.tsx`)
- Intelligence Map → Alert Layer: uses layer (evidence: `src/components/TrafficIntelligenceDashboard.tsx`)
- Vehicle Layer → Geo Projection: projects coordinates (evidence: `src/components/map/VehicleLayer.tsx`)
- Prediction Layer → Geo Projection: projects coordinates (evidence: `src/components/map/PredictionRouteLayer.tsx`)
- Drive Export → Drive Authorization: uses authorization (evidence: `src/services/googleDriveService.ts`)
- Drive Authorization → Google Drive: authorizes access (evidence: `src/services/googleDriveAuth.ts`)
