# oshone-system/fleetsystem architecture

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

- Interactive diagram: https://gitdiagram.com/oshone-system/fleetsystem
- Repository: https://github.com/oshone-system/fleetsystem

## Overview

Fleet Khata is a truck-fleet operations portal. Staff sign in, maintain fleet and party records, plan routes, record gate-out and gate-in, then review trip sheets, settlements, alerts and reports. GPS updates can feed live route alerts and gate-in distance checks; vehicle documents have expiry alerts. The graph uses the root backend/frontend/shared tree, which matches the README. The duplicate fleet-khata-pern tree appears to be a parallel copy. Some feature wiring is documented but its implementation was not sampled, so uncertain calls are omitted.

Main entry points: [`frontend/src/lib/api.js`](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/lib/api.js) (API client), [`backend/src/app.js`](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/app.js) (Express API), [`backend/src/db/crud.js`](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/db/crud.js) (Database access), [`backend/src/routes/trips.js`](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/trips.js) (Trip workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Web portal"]
  node_frontend["Portal entry<br/>[main.jsx]"]
  node_appstate["App state<br/>[store.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_operations["Fleet operations"]
  node_gate_out["Gate out<br/>[GateOut.jsx]"]
  node_gate_in["Gate in<br/>[GateIn.jsx]"]
  node_trip_views["Trips and sheets<br/>[Trips.jsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_master_pages["Fleet and parties<br/>[Parties.jsx]"]
  node_documents_ui["Vehicle documents<br/>[Documents.jsx]"]
  node_reports_ui["Reports<br/>[Reports.jsx]"]
  node_users_ui["Users and roles<br/>[Users.jsx]"]
  node_master_api["Master records<br/>[master.js]"]
  node_trips_api["Trip workflow<br/>[trips.js]"]
  node_docs_api["Document handling<br/>[docs.js]"]
  node_reports_api["Reports and alerts<br/>[reports.js]"]
end

subgraph group_services["Tracking services"]
  node_gps_api["GPS endpoints<br/>[gps.js]"]
  node_route_planner["Route planning<br/>[routePlanner.js]"]
  node_gps_live["Live GPS checks<br/>[liveGps.js]"]
  node_gps_vendor["Vendor polling<br/>[gpsVendor.js]"]
  node_alerts["Alert handling<br/>[alerts.js]"]
  node_scheduler["Expiry schedule<br/>[cron.js]"]
end

subgraph group_platform["API and data"]
  node_api_app["Express API<br/>[app.js]"]
  node_auth["Authentication and roles<br/>[auth.js]"]
  node_context["Trip calculations context<br/>[context.js]"]
  node_calc["Fleet calculations<br/>[calc.js]"]
  node_db_access["Database access<br/>[crud.js]"]
  node_postgres[("PostgreSQL")]
end

node_staff(("Fleet staff"))
node_gps_company(("GPS provider"))
node_maps(("Google Maps"))

node_staff -->|"uses"| node_frontend
node_frontend -->|"provides state"| node_appstate
node_appstate -->|"requests data"| node_api_client
node_gate_out -->|"submits gate-out"| node_api_client
node_gate_in -->|"submits gate-in"| node_api_client
node_trip_views -->|"loads trips"| node_api_client
node_dashboard -->|"loads dashboard"| node_api_client
node_master_pages -->|"manages records"| node_api_client
node_documents_ui -->|"uploads documents"| node_api_client
node_reports_ui -->|"requests reports"| node_api_client
node_users_ui -->|"manages users"| node_api_client
node_api_client -->|"HTTP requests"| node_api_app
node_api_app -->|"mounts routes"| node_auth
node_api_app -->|"mounts routes"| node_master_api
node_api_app -->|"mounts routes"| node_trips_api
node_api_app -->|"mounts routes"| node_docs_api
node_api_app -->|"mounts routes"| node_reports_api
node_api_app -->|"mounts routes"| node_gps_api
node_auth -->|"reads and writes"| node_db_access
node_master_api -->|"reads and writes"| node_db_access
node_trips_api -->|"reads and writes"| node_db_access
node_trips_api -->|"loads calculations"| node_context
node_context -->|"calculates trips"| node_calc
node_docs_api -->|"stores metadata"| node_db_access
node_reports_api -->|"reads report data"| node_db_access
node_gps_api -->|"stores GPS points"| node_db_access
node_gps_api -->|"processes locations"| node_gps_live
node_gps_api -->|"accepts webhook"| node_gps_company
node_gps_vendor -.->|"polls locations"| node_gps_company
node_gps_vendor -.->|"provides locations"| node_gps_live
node_trips_api -->|"plans routes"| node_route_planner
node_route_planner -.->|"gets distance"| node_maps
node_scheduler -->|"checks expiry"| node_alerts
node_gps_live -->|"raises deviations"| node_alerts
node_db_access -->|"queries"| node_postgres

click node_frontend "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/main.jsx"
click node_appstate "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/lib/store.jsx"
click node_api_client "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/lib/api.js"
click node_gate_out "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/GateOut.jsx"
click node_gate_in "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/GateIn.jsx"
click node_trip_views "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Trips.jsx"
click node_dashboard "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Dashboard.jsx"
click node_master_pages "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Parties.jsx"
click node_documents_ui "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Documents.jsx"
click node_reports_ui "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Reports.jsx"
click node_users_ui "https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Users.jsx"
click node_api_app "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/app.js"
click node_auth "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/auth.js"
click node_master_api "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/master.js"
click node_trips_api "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/trips.js"
click node_docs_api "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/docs.js"
click node_reports_api "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/reports.js"
click node_gps_api "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/gps.js"
click node_route_planner "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/routePlanner.js"
click node_gps_live "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/liveGps.js"
click node_gps_vendor "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/gpsVendor.js"
click node_alerts "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/alerts.js"
click node_scheduler "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/jobs/cron.js"
click node_context "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/context.js"
click node_calc "https://github.com/oshone-system/fleetsystem/blob/main/shared/calc.js"
click node_db_access "https://github.com/oshone-system/fleetsystem/blob/main/backend/src/db/crud.js"

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_frontend,node_appstate,node_api_client toneBlue
class node_gate_out,node_gate_in,node_trip_views,node_dashboard,node_master_pages,node_documents_ui,node_reports_ui,node_users_ui,node_master_api,node_trips_api,node_docs_api,node_reports_api toneAmber
class node_gps_api,node_route_planner,node_gps_live,node_gps_vendor,node_alerts,node_scheduler toneMint
class node_api_app,node_auth,node_context,node_calc,node_db_access,node_postgres toneRose
class node_staff,node_gps_company,node_maps toneIndigo
```

## Components

### Web portal

- [Portal entry](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [App state](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/lib/store.jsx): `frontend/src/lib/store.jsx`
- [API client](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`

### Fleet operations

- [Gate out](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/GateOut.jsx): `frontend/src/pages/GateOut.jsx`
- [Gate in](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/GateIn.jsx): `frontend/src/pages/GateIn.jsx`
- [Trips and sheets](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Trips.jsx): `frontend/src/pages/Trips.jsx`
- [Dashboard](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Fleet and parties](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Parties.jsx): `frontend/src/pages/Parties.jsx`
- [Vehicle documents](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Documents.jsx): `frontend/src/pages/Documents.jsx`
- [Reports](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Reports.jsx): `frontend/src/pages/Reports.jsx`
- [Users and roles](https://github.com/oshone-system/fleetsystem/blob/main/frontend/src/pages/Users.jsx): `frontend/src/pages/Users.jsx`
- [Master records](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/master.js): `backend/src/routes/master.js`
- [Trip workflow](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/trips.js): `backend/src/routes/trips.js`
- [Document handling](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/docs.js): `backend/src/routes/docs.js`
- [Reports and alerts](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/reports.js): `backend/src/routes/reports.js`

### Tracking services

- [GPS endpoints](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/gps.js): `backend/src/routes/gps.js`
- [Route planning](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/routePlanner.js): `backend/src/services/routePlanner.js`
- [Live GPS checks](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/liveGps.js): `backend/src/services/liveGps.js`
- [Vendor polling](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/gpsVendor.js): `backend/src/services/gpsVendor.js`
- [Alert handling](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/alerts.js): `backend/src/services/alerts.js`
- [Expiry schedule](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/jobs/cron.js): `backend/src/jobs/cron.js`

### API and data

- [Express API](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/app.js): `backend/src/app.js`
- [Authentication and roles](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/routes/auth.js): `backend/src/routes/auth.js`
- [Trip calculations context](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/services/context.js): `backend/src/services/context.js`
- [Fleet calculations](https://github.com/oshone-system/fleetsystem/blob/main/shared/calc.js): `shared/calc.js`
- [Database access](https://github.com/oshone-system/fleetsystem/blob/main/backend/src/db/crud.js): `backend/src/db/crud.js`
- **PostgreSQL**

### Other components

- **Fleet staff**
- **GPS provider**
- **Google Maps**

## Connections

- Fleet staff → Portal entry: uses
- Portal entry → App state: provides state
- App state → API client: requests data
- Gate out → API client: submits gate-out
- Gate in → API client: submits gate-in
- Trips and sheets → API client: loads trips
- Dashboard → API client: loads dashboard
- Fleet and parties → API client: manages records
- Vehicle documents → API client: uploads documents
- Reports → API client: requests reports
- Users and roles → API client: manages users
- API client → Express API: HTTP requests
- Express API → Authentication and roles: mounts routes
- Express API → Master records: mounts routes
- Express API → Trip workflow: mounts routes
- Express API → Document handling: mounts routes
- Express API → Reports and alerts: mounts routes
- Express API → GPS endpoints: mounts routes
- Authentication and roles → Database access: reads and writes
- Master records → Database access: reads and writes
- Trip workflow → Database access: reads and writes
- Trip workflow → Trip calculations context: loads calculations
- Trip calculations context → Fleet calculations: calculates trips
- Document handling → Database access: stores metadata
- Reports and alerts → Database access: reads report data
- GPS endpoints → Database access: stores GPS points
- GPS endpoints → Live GPS checks: processes locations
- GPS endpoints → GPS provider: accepts webhook
- Vendor polling → GPS provider: polls locations
- Vendor polling → Live GPS checks: provides locations
- Trip workflow → Route planning: plans routes
- Route planning → Google Maps: gets distance
- Expiry schedule → Alert handling: checks expiry
- Live GPS checks → Alert handling: raises deviations
- Database access → PostgreSQL: queries