# mnataraj2006/road-logistics-space-utilization architecture

> Architecture diagram of the GitHub repository mnataraj2006/road-logistics-space-utilization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mnataraj2006/road-logistics-space-utilization
- Repository: https://github.com/mnataraj2006/road-logistics-space-utilization

## Overview

This is a multi-stop freight capacity and truck-space optimization platform. Customers search corridor capacity, get deterministic quotes, and book shipments; logistics managers plan and approve 3D load assignments, then dispatch and operate trips with stop verification and in-transit re-optimization. The graph also includes analytics and audit capabilities documented by the README. Relationships reflect the excerpts, SOURCE INDEX references, and README; unsampled route wiring and some subsystem internals are not asserted.

Main entry points: [`backend/optimizer/engine.js`](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/optimizer/engine.js) (Load-plan optimizer), [`backend/controllers/tripController.js`](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/controllers/tripController.js) (Trip planning API), [`backend/services/tripLifecycleService.js`](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/tripLifecycleService.js) (Trip lifecycle), [`frontend/src/App.jsx`](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/frontend/src/App.jsx) (Role workspaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_webapp["Role workspaces<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_load_console["Load-plan console"]
  node_load_visuals["Load visualizers"]
end

subgraph group_api["API and booking"]
  node_backend_api["Backend API<br/>[server.js]"]
  node_auth["Authentication and roles<br/>[auth.js]"]
  node_capacity["Capacity search and booking"]
  node_pricing["Deterministic pricing<br/>[pricingService.js]"]
end

subgraph group_operations["Fleet operations"]
  node_trip_controller["Trip planning API<br/>[tripController.js]"]
  node_lifecycle["Trip lifecycle"]
  node_reoptimization["Dynamic re-optimization"]
  node_audit["Audit ledger<br/>[auditService.js]"]
end

subgraph group_intelligence["Optimization and analytics"]
  node_optimizer["Load-plan optimizer<br/>[engine.js]"]
  node_solver["Local search solver<br/>[localSearch.js]"]
  node_geometry["3D spatial engine<br/>[spatialEngine.js]"]
  node_validation["Constraint validation<br/>[validator.js]"]
  node_analytics_api["Prediction and analytics<br/>[routes.py]"]
end

subgraph group_records["Operational records"]
  node_booking_records[("Booking and shipment records<br/>[Booking.js]")]
  node_trip_records[("Trip and route records<br/>[Trip.js]")]
  node_load_records[("Load-plan records<br/>[LoadPlan.js]")]
end

node_customer(("Customer"))
node_manager(("Logistics manager"))
node_driver(("Driver"))
node_mongo[("MongoDB")]

node_customer -->|"uses"| node_webapp
node_manager -->|"uses"| node_webapp
node_driver -->|"uses"| node_webapp
node_webapp -->|"requests data"| node_api_client
node_api_client -.->|"calls"| node_backend_api
node_backend_api -->|"protects routes"| node_auth
node_backend_api -.->|"serves capacity"| node_capacity
node_capacity -->|"calculates quotes"| node_pricing
node_capacity -->|"writes bookings"| node_booking_records
node_booking_records -.->|"persists"| node_mongo
node_trip_controller -->|"generates plans"| node_optimizer
node_optimizer -->|"solves packing"| node_solver
node_optimizer -->|"checks placements"| node_geometry
node_optimizer -->|"validates input"| node_validation
node_geometry -->|"checks bounds"| node_validation
node_trip_controller -->|"stores assignments"| node_load_records
node_load_records -.->|"persists"| node_mongo
node_load_console -->|"requests plans"| node_api_client
node_load_console -->|"renders loads"| node_load_visuals
node_manager -->|"runs and approves"| node_trip_controller
node_trip_controller -->|"reads trip data"| node_trip_records
node_trip_records -.->|"persists"| node_mongo
node_manager -->|"operates trip"| node_lifecycle
node_driver -->|"verifies stops"| node_lifecycle
node_lifecycle -->|"rebalances downstream"| node_reoptimization
node_reoptimization -->|"rebuilds plan"| node_optimizer
node_lifecycle -->|"records events"| node_audit
node_manager -->|"inspects ledger"| node_audit
node_manager -->|"reviews forecasts"| node_analytics_api

click node_webapp "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/frontend/src/services/api.js"
click node_load_console "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/frontend/src/views/manager/ManagerOptimizationView.jsx"
click node_load_visuals "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/frontend/src/components/optimizer/OperationalLoadVisualizer.jsx"
click node_backend_api "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/server.js"
click node_auth "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/middleware/auth.js"
click node_capacity "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/capacitySearchService.js"
click node_pricing "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/pricingService.js"
click node_trip_controller "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/controllers/tripController.js"
click node_lifecycle "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/tripLifecycleService.js"
click node_reoptimization "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/dynamicReoptimizationService.js"
click node_optimizer "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/optimizer/engine.js"
click node_solver "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/optimizer/localSearch.js"
click node_geometry "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/optimizer/spatialEngine.js"
click node_validation "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/optimizer/validator.js"
click node_analytics_api "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/analytics/app/routes.py"
click node_audit "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/auditService.js"
click node_booking_records "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/models/Booking.js"
click node_trip_records "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/models/Trip.js"
click node_load_records "https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/models/LoadPlan.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_webapp,node_api_client,node_load_console,node_load_visuals toneBlue
class node_backend_api,node_auth,node_capacity,node_pricing,node_mongo toneAmber
class node_trip_controller,node_lifecycle,node_reoptimization,node_audit toneMint
class node_optimizer,node_solver,node_geometry,node_validation,node_analytics_api toneRose
class node_booking_records,node_trip_records,node_load_records,node_customer,node_manager,node_driver toneIndigo
```

## Components

### User experience

- [Role workspaces](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Load-plan console](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/frontend/src/views/manager/ManagerOptimizationView.jsx): `frontend/src/views/manager/ManagerOptimizationView.jsx`
- [Load visualizers](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/frontend/src/components/optimizer/OperationalLoadVisualizer.jsx): `frontend/src/components/optimizer/OperationalLoadVisualizer.jsx`

### API and booking

- [Backend API](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/server.js): `backend/server.js`
- [Authentication and roles](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/middleware/auth.js): `backend/middleware/auth.js`
- [Capacity search and booking](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/capacitySearchService.js): `backend/services/capacitySearchService.js`
- [Deterministic pricing](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/pricingService.js): `backend/services/pricingService.js`

### Fleet operations

- [Trip planning API](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/controllers/tripController.js): `backend/controllers/tripController.js`
- [Trip lifecycle](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/tripLifecycleService.js): `backend/services/tripLifecycleService.js`
- [Dynamic re-optimization](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/dynamicReoptimizationService.js): `backend/services/dynamicReoptimizationService.js`
- [Audit ledger](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/services/auditService.js): `backend/services/auditService.js`

### Optimization and analytics

- [Load-plan optimizer](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/optimizer/engine.js): `backend/optimizer/engine.js`
- [Local search solver](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/optimizer/localSearch.js): `backend/optimizer/localSearch.js`
- [3D spatial engine](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/optimizer/spatialEngine.js): `backend/optimizer/spatialEngine.js`
- [Constraint validation](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/optimizer/validator.js): `backend/optimizer/validator.js`
- [Prediction and analytics](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/analytics/app/routes.py): `analytics/app/routes.py`

### Operational records

- [Booking and shipment records](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/models/Booking.js): `backend/models/Booking.js`
- [Trip and route records](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/models/Trip.js): `backend/models/Trip.js`
- [Load-plan records](https://github.com/mnataraj2006/road-logistics-space-utilization/blob/main/backend/models/LoadPlan.js): `backend/models/LoadPlan.js`

### Other components

- **Customer**
- **Logistics manager**
- **Driver**
- **MongoDB**

## Connections

- Customer → Role workspaces: uses
- Logistics manager → Role workspaces: uses
- Driver → Role workspaces: uses
- Role workspaces → API client: requests data
- API client → Backend API: calls
- Backend API → Authentication and roles: protects routes (evidence: `backend/server.js`)
- Backend API → Capacity search and booking: serves capacity
- Capacity search and booking → Deterministic pricing: calculates quotes (evidence: `backend/services/capacitySearchService.js`)
- Capacity search and booking → Booking and shipment records: writes bookings (evidence: `backend/services/capacitySearchService.js`)
- Booking and shipment records → MongoDB: persists
- Trip planning API → Load-plan optimizer: generates plans (evidence: `backend/controllers/tripController.js`)
- Load-plan optimizer → Local search solver: solves packing (evidence: `backend/optimizer/engine.js`)
- Load-plan optimizer → 3D spatial engine: checks placements (evidence: `backend/optimizer/engine.js`)
- Load-plan optimizer → Constraint validation: validates input (evidence: `backend/optimizer/engine.js`)
- 3D spatial engine → Constraint validation: checks bounds (evidence: `backend/optimizer/spatialEngine.js`)
- Trip planning API → Load-plan records: stores assignments (evidence: `backend/controllers/tripController.js`)
- Load-plan records → MongoDB: persists
- Load-plan console → API client: requests plans (evidence: `frontend/src/views/manager/ManagerOptimizationView.jsx`)
- Load-plan console → Load visualizers: renders loads (evidence: `frontend/src/views/manager/ManagerOptimizationView.jsx`)
- Logistics manager → Trip planning API: runs and approves
- Trip planning API → Trip and route records: reads trip data (evidence: `backend/controllers/tripController.js`)
- Trip and route records → MongoDB: persists
- Logistics manager → Trip lifecycle: operates trip
- Driver → Trip lifecycle: verifies stops
- Trip lifecycle → Dynamic re-optimization: rebalances downstream (evidence: `backend/services/tripLifecycleService.js`)
- Dynamic re-optimization → Load-plan optimizer: rebuilds plan (evidence: `backend/services/dynamicReoptimizationService.js`)
- Trip lifecycle → Audit ledger: records events (evidence: `backend/services/tripLifecycleService.js`)
- Logistics manager → Audit ledger: inspects ledger
- Logistics manager → Prediction and analytics: reviews forecasts
