# saiganesh-09/fleet-management-platform architecture

> Architecture diagram of the GitHub repository saiganesh-09/fleet-management-platform, 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/saiganesh-09/fleet-management-platform
- Repository: https://github.com/saiganesh-09/fleet-management-platform

## Overview

FleetOps is a fleet operations platform spanning inventory, driver management, trip lifecycle, tracking, maintenance, fuel, documents, analytics, reporting, and AI assistance. The principal flow is an operator using the dashboard to make a fleet change or request; the frontend calls the backend, which applies domain logic and persists or retrieves data. The README documents backend layering and realtime behavior; unsampled service wiring is represented only where documented, and some domain endpoints are grouped at their documented boundaries.

Main entry points: [`backend/src/controllers/domain.controller.ts`](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/controllers/domain.controller.ts) (Controllers), [`backend/src/repositories`](https://github.com/saiganesh-09/fleet-management-platform/tree/main/backend/src/repositories) (Data repositories), [`backend/src/routes/domain.routes.ts`](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/routes/domain.routes.ts) (API routes), [`ai-service/app/main.py`](https://github.com/saiganesh-09/fleet-management-platform/blob/main/ai-service/app/main.py) (AI service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Fleet dashboard"]
  node_dashboard["Fleet dashboard"]
  node_frontendapi["API client<br/>[api.ts]"]
  node_socketclient["Socket client<br/>[socket.ts]"]
end

subgraph group_api["Backend API"]
  node_routes["API routes<br/>[domain.routes.ts]"]
  node_controllers["Controllers"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_repositories["Data repositories"]
end

subgraph group_operations["Fleet operations"]
  node_vehicle["Fleet inventory<br/>[vehicle.service.ts]"]
  node_drivers["Driver roster<br/>[driver.service.ts]"]
  node_trips["Trip lifecycle<br/>[trip.service.ts]"]
  node_maintenance["Maintenance"]
  node_fuel["Fuel operations<br/>[fuel.service.ts]"]
  node_documents["Documents"]
  node_notifications["Notifications"]
end

subgraph group_intelligence["Analytics and AI"]
  node_reports["Reports and analytics<br/>[report.service.ts]"]
  node_search["Global search<br/>[search.service.ts]"]
  node_aiproxy["AI proxy<br/>[ai.service.ts]"]
  node_airest["AI service<br/>[main.py]"]
  node_aidata["Curated AI data"]
end

subgraph group_realtime["Live tracking"]
  node_gps["GPS simulator"]
  node_locations["Location service"]
  node_sockets["Socket.IO server<br/>[index.ts]"]
end

node_operator(("Fleet user"))
node_database[("PostgreSQL")]
node_llm(("LLM provider"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_frontendapi
node_frontendapi -->|"REST calls"| node_routes
node_routes -->|"dispatches"| node_controllers
node_controllers -->|"calls"| node_vehicle
node_controllers -->|"calls"| node_drivers
node_controllers -->|"calls"| node_trips
node_controllers -->|"calls"| node_maintenance
node_controllers -->|"calls"| node_fuel
node_controllers -->|"calls"| node_documents
node_controllers -->|"calls"| node_notifications
node_controllers -->|"calls"| node_reports
node_controllers -->|"calls"| node_search
node_routes -->|"routes auth"| node_auth
node_vehicle -->|"queries"| node_repositories
node_drivers -->|"queries"| node_repositories
node_trips -->|"queries"| node_repositories
node_maintenance -->|"queries"| node_repositories
node_fuel -->|"queries"| node_repositories
node_documents -->|"queries"| node_repositories
node_notifications -->|"queries"| node_repositories
node_reports -->|"reads"| node_repositories
node_search -->|"searches"| node_database
node_repositories -->|"reads and writes"| node_database
node_aiproxy -->|"proxies requests"| node_airest
node_airest -->|"fetches context"| node_aidata
node_aidata -->|"reads curated data"| node_database
node_airest -.->|"tool calls"| node_llm
node_gps -->|"records positions"| node_locations
node_locations -->|"persists locations"| node_database
node_gps -->|"broadcasts updates"| node_sockets
node_sockets -->|"pushes events"| node_socketclient
node_socketclient -->|"updates views"| node_dashboard

click node_dashboard "https://github.com/saiganesh-09/fleet-management-platform/tree/main/frontend/app/(app)"
click node_frontendapi "https://github.com/saiganesh-09/fleet-management-platform/blob/main/frontend/lib/api.ts"
click node_socketclient "https://github.com/saiganesh-09/fleet-management-platform/blob/main/frontend/lib/socket.ts"
click node_routes "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/routes/domain.routes.ts"
click node_controllers "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/controllers/domain.controller.ts"
click node_auth "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/auth.service.ts"
click node_vehicle "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/vehicle.service.ts"
click node_drivers "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/driver.service.ts"
click node_trips "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/trip.service.ts"
click node_maintenance "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/maintenance.service.ts"
click node_fuel "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/fuel.service.ts"
click node_documents "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/document.service.ts"
click node_notifications "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/notification.service.ts"
click node_reports "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/report.service.ts"
click node_search "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/search.service.ts"
click node_aiproxy "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/ai.service.ts"
click node_airest "https://github.com/saiganesh-09/fleet-management-platform/blob/main/ai-service/app/main.py"
click node_aidata "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/controllers/aiData.controller.ts"
click node_gps "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/gpsSimulator.service.ts"
click node_locations "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/location.service.ts"
click node_sockets "https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/sockets/index.ts"
click node_repositories "https://github.com/saiganesh-09/fleet-management-platform/tree/main/backend/src/repositories"

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_dashboard,node_frontendapi,node_socketclient,node_operator toneBlue
class node_routes,node_controllers,node_auth,node_repositories,node_database toneAmber
class node_vehicle,node_drivers,node_trips,node_maintenance,node_fuel,node_documents,node_notifications toneMint
class node_reports,node_search,node_aiproxy,node_airest,node_aidata toneRose
class node_gps,node_locations,node_sockets,node_llm toneIndigo
```

## Components

### Fleet dashboard

- [Fleet dashboard](https://github.com/saiganesh-09/fleet-management-platform/tree/main/frontend/app/(app)): `frontend/app/(app)`
- [API client](https://github.com/saiganesh-09/fleet-management-platform/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Socket client](https://github.com/saiganesh-09/fleet-management-platform/blob/main/frontend/lib/socket.ts): `frontend/lib/socket.ts`

### Backend API

- [API routes](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/routes/domain.routes.ts): `backend/src/routes/domain.routes.ts`
- [Controllers](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/controllers/domain.controller.ts): `backend/src/controllers/domain.controller.ts`
- [Authentication](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/auth.service.ts): `backend/src/services/auth.service.ts`
- [Data repositories](https://github.com/saiganesh-09/fleet-management-platform/tree/main/backend/src/repositories): `backend/src/repositories`

### Fleet operations

- [Fleet inventory](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/vehicle.service.ts): `backend/src/services/vehicle.service.ts`
- [Driver roster](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/driver.service.ts): `backend/src/services/driver.service.ts`
- [Trip lifecycle](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/trip.service.ts): `backend/src/services/trip.service.ts`
- [Maintenance](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/maintenance.service.ts): `backend/src/services/maintenance.service.ts`
- [Fuel operations](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/fuel.service.ts): `backend/src/services/fuel.service.ts`
- [Documents](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/document.service.ts): `backend/src/services/document.service.ts`
- [Notifications](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/notification.service.ts): `backend/src/services/notification.service.ts`

### Analytics and AI

- [Reports and analytics](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/report.service.ts): `backend/src/services/report.service.ts`
- [Global search](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/search.service.ts): `backend/src/services/search.service.ts`
- [AI proxy](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/ai.service.ts): `backend/src/services/ai.service.ts`
- [AI service](https://github.com/saiganesh-09/fleet-management-platform/blob/main/ai-service/app/main.py): `ai-service/app/main.py`
- [Curated AI data](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/controllers/aiData.controller.ts): `backend/src/controllers/aiData.controller.ts`

### Live tracking

- [GPS simulator](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/gpsSimulator.service.ts): `backend/src/services/gpsSimulator.service.ts`
- [Location service](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/services/location.service.ts): `backend/src/services/location.service.ts`
- [Socket.IO server](https://github.com/saiganesh-09/fleet-management-platform/blob/main/backend/src/sockets/index.ts): `backend/src/sockets/index.ts`

### Other components

- **Fleet user**
- **PostgreSQL**
- **LLM provider**

## Connections

- Fleet user → Fleet dashboard: uses
- Fleet dashboard → API client: requests data
- API client → API routes: REST calls
- API routes → Controllers: dispatches
- Controllers → Fleet inventory: calls
- Controllers → Driver roster: calls
- Controllers → Trip lifecycle: calls
- Controllers → Maintenance: calls
- Controllers → Fuel operations: calls
- Controllers → Documents: calls
- Controllers → Notifications: calls
- Controllers → Reports and analytics: calls
- Controllers → Global search: calls
- API routes → Authentication: routes auth
- Fleet inventory → Data repositories: queries
- Driver roster → Data repositories: queries
- Trip lifecycle → Data repositories: queries
- Maintenance → Data repositories: queries
- Fuel operations → Data repositories: queries
- Documents → Data repositories: queries
- Notifications → Data repositories: queries
- Reports and analytics → Data repositories: reads
- Global search → PostgreSQL: searches
- Data repositories → PostgreSQL: reads and writes
- AI proxy → AI service: proxies requests
- AI service → Curated AI data: fetches context
- Curated AI data → PostgreSQL: reads curated data
- AI service → LLM provider: tool calls
- GPS simulator → Location service: records positions
- Location service → PostgreSQL: persists locations
- GPS simulator → Socket.IO server: broadcasts updates
- Socket.IO server → Socket client: pushes events
- Socket client → Fleet dashboard: updates views