# ankitkapse594/eld-trip-planner architecture

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

- Interactive diagram: https://gitdiagram.com/ankitkapse594/eld-trip-planner
- Repository: https://github.com/ankitkapse594/eld-trip-planner

## Overview

This is a full-stack FMCSA Hours-of-Service dispatch planner. Dispatchers enter origin, pickup, dropoff, cycle usage, and driver/log details; the client submits a plan request, and the backend routes the trip, simulates duty segments, validates compliance, and builds stops and daily logs. The console presents the route, schedule, HOS summary, and printable log sheets, while location autocomplete uses a separate geocoding endpoint. Some backend orchestration is only partially excerpted; relationships not directly shown in source are grounded in the README where noted.

Main entry points: [`backend/trips/views.py`](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/views.py) (Django API), [`frontend/src/App.tsx`](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/App.tsx) (Console App), [`backend/trips/services/routing.py`](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/routing.py) (Truck Routing), [`backend/trips/services/log_builder.py`](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/log_builder.py) (Daily Log Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dispatch["Dispatch Console"]
  node_tripform["Trip Form<br/>[TripForm.tsx]"]
  node_locationinput["Location Search<br/>[LocationInput.tsx]"]
  node_tripmutation["Plan Mutation<br/>[useTripPlan.ts]"]
  node_api_client["API Client<br/>[client.ts]"]
  node_app["Console App<br/>[App.tsx]"]
end

subgraph group_api["API Gateway"]
  node_django["Django API<br/>[views.py]"]
  node_serializer["Request Validation<br/>[serializers.py]"]
  node_geocoding["Geocoding<br/>[geocoding.py]"]
end

subgraph group_planning["Trip Planning"]
  node_routing["Truck Routing<br/>[routing.py]"]
  node_geo_utils["Geo Utilities<br/>[geo_utils.py]"]
  node_hos_planner["HOS Simulation<br/>[hos_planner.py]"]
  node_hos_validator["Compliance Validation<br/>[hos_validator.py]"]
  node_log_builder["Daily Log Builder<br/>[log_builder.py]"]
  node_map_data["Route Geometry<br/>[geo_utils.py]"]
end

subgraph group_presentation["Trip Results"]
  node_summary["Trip Summary<br/>[SummaryCards.tsx]"]
  node_gauges["HOS Gauges<br/>[HosGauges.tsx]"]
  node_route_map["Route Map<br/>[RouteMap.tsx]"]
  node_timeline["Stops Timeline<br/>[StopsTimeline.tsx]"]
  node_log_viewer["Log Viewer<br/>[LogSheetViewer.tsx]"]
  node_log_sheet["Daily Log Sheet<br/>[LogSheet.tsx]"]
end

node_dispatcher(("Dispatcher"))
node_ors["OpenRouteService"]
node_osrm["OSRM Router"]
node_nominatim["Nominatim"]

node_dispatcher -->|"enters trip"| node_tripform
node_tripform -->|"uses search"| node_locationinput
node_locationinput -->|"requests geocodes"| node_api_client
node_dispatcher -->|"submits plan"| node_tripform
node_tripform -->|"submits request"| node_app
node_app -->|"requests plan"| node_tripmutation
node_tripmutation -->|"calls planTrip"| node_api_client
node_api_client -->|"POSTs plan"| node_django
node_api_client -->|"GETs geocodes"| node_django
node_django -->|"validates request"| node_serializer
node_django -->|"gets route"| node_routing
node_django -->|"plans duty"| node_hos_planner
node_django -->|"checks compliance"| node_hos_validator
node_django -->|"builds daily logs"| node_log_builder
node_django -->|"searches locations"| node_geocoding
node_routing -.->|"requests route"| node_ors
node_routing -.->|"fallback route"| node_osrm
node_geocoding -.->|"geocodes locations"| node_nominatim
node_routing -->|"uses distance tools"| node_geo_utils
node_hos_planner -->|"uses mileage tools"| node_geo_utils
node_hos_planner -->|"validates plan"| node_hos_validator
node_log_builder -->|"splits segments"| node_hos_planner
node_log_builder -->|"interpolates locations"| node_geo_utils
node_log_builder -.->|"reverse geocodes remarks"| node_geocoding
node_django -->|"returns plan"| node_app
node_app -->|"renders summary"| node_summary
node_app -->|"renders HOS gauges"| node_gauges
node_app -->|"renders route"| node_route_map
node_app -->|"renders schedule"| node_timeline
node_app -->|"renders logs"| node_log_viewer
node_log_viewer -->|"renders sheets"| node_log_sheet

click node_tripform "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/form/TripForm.tsx"
click node_locationinput "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/form/LocationInput.tsx"
click node_tripmutation "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/hooks/useTripPlan.ts"
click node_api_client "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/api/client.ts"
click node_app "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/App.tsx"
click node_django "https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/views.py"
click node_serializer "https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/serializers.py"
click node_geocoding "https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/geocoding.py"
click node_routing "https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/routing.py"
click node_geo_utils "https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/geo_utils.py"
click node_hos_planner "https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/hos_planner.py"
click node_hos_validator "https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/hos_validator.py"
click node_log_builder "https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/log_builder.py"
click node_summary "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/summary/SummaryCards.tsx"
click node_gauges "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/summary/HosGauges.tsx"
click node_route_map "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/map/RouteMap.tsx"
click node_timeline "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/summary/StopsTimeline.tsx"
click node_log_viewer "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/logs/LogSheetViewer.tsx"
click node_log_sheet "https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/logs/LogSheet.tsx"
click node_map_data "https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/geo_utils.py"

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_tripform,node_locationinput,node_tripmutation,node_api_client,node_app toneBlue
class node_django,node_serializer,node_geocoding toneAmber
class node_routing,node_geo_utils,node_hos_planner,node_hos_validator,node_log_builder,node_map_data,node_ors,node_osrm toneMint
class node_summary,node_gauges,node_route_map,node_timeline,node_log_viewer,node_log_sheet toneRose
class node_dispatcher,node_nominatim toneIndigo
```

## Components

### Dispatch Console

- [Trip Form](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/form/TripForm.tsx): `frontend/src/features/form/TripForm.tsx`
- [Location Search](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/form/LocationInput.tsx): `frontend/src/features/form/LocationInput.tsx`
- [Plan Mutation](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/hooks/useTripPlan.ts): `frontend/src/hooks/useTripPlan.ts`
- [API Client](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Console App](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### API Gateway

- [Django API](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/views.py): `backend/trips/views.py`
- [Request Validation](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/serializers.py): `backend/trips/serializers.py`
- [Geocoding](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/geocoding.py): `backend/trips/services/geocoding.py`

### Trip Planning

- [Truck Routing](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/routing.py): `backend/trips/services/routing.py`
- [Geo Utilities](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/geo_utils.py): `backend/trips/services/geo_utils.py`
- [HOS Simulation](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/hos_planner.py): `backend/trips/services/hos_planner.py`
- [Compliance Validation](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/hos_validator.py): `backend/trips/services/hos_validator.py`
- [Daily Log Builder](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/log_builder.py): `backend/trips/services/log_builder.py`
- [Route Geometry](https://github.com/ankitkapse594/eld-trip-planner/blob/main/backend/trips/services/geo_utils.py): `backend/trips/services/geo_utils.py`

### Trip Results

- [Trip Summary](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/summary/SummaryCards.tsx): `frontend/src/features/summary/SummaryCards.tsx`
- [HOS Gauges](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/summary/HosGauges.tsx): `frontend/src/features/summary/HosGauges.tsx`
- [Route Map](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/map/RouteMap.tsx): `frontend/src/features/map/RouteMap.tsx`
- [Stops Timeline](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/summary/StopsTimeline.tsx): `frontend/src/features/summary/StopsTimeline.tsx`
- [Log Viewer](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/logs/LogSheetViewer.tsx): `frontend/src/features/logs/LogSheetViewer.tsx`
- [Daily Log Sheet](https://github.com/ankitkapse594/eld-trip-planner/blob/main/frontend/src/features/logs/LogSheet.tsx): `frontend/src/features/logs/LogSheet.tsx`

### Other components

- **Dispatcher**
- **OpenRouteService**
- **OSRM Router**
- **Nominatim**

## Connections

- Dispatcher → Trip Form: enters trip (evidence: `README.md`)
- Trip Form → Location Search: uses search (evidence: `frontend/src/features/form/TripForm.tsx`)
- Location Search → API Client: requests geocodes (evidence: `frontend/src/features/form/LocationInput.tsx`)
- Dispatcher → Trip Form: submits plan (evidence: `README.md`)
- Trip Form → Console App: submits request (evidence: `frontend/src/App.tsx`)
- Console App → Plan Mutation: requests plan (evidence: `frontend/src/App.tsx`)
- Plan Mutation → API Client: calls planTrip (evidence: `frontend/src/hooks/useTripPlan.ts`)
- API Client → Django API: POSTs plan (evidence: `README.md`)
- API Client → Django API: GETs geocodes (evidence: `README.md`)
- Django API → Request Validation: validates request (evidence: `backend/trips/views.py`)
- Django API → Truck Routing: gets route (evidence: `backend/trips/views.py`)
- Django API → HOS Simulation: plans duty (evidence: `backend/trips/views.py`)
- Django API → Compliance Validation: checks compliance (evidence: `backend/trips/views.py`)
- Django API → Daily Log Builder: builds daily logs (evidence: `backend/trips/views.py`)
- Django API → Geocoding: searches locations (evidence: `backend/trips/views.py`)
- Truck Routing → OpenRouteService: requests route (evidence: `README.md`)
- Truck Routing → OSRM Router: fallback route (evidence: `README.md`)
- Geocoding → Nominatim: geocodes locations (evidence: `README.md`)
- Truck Routing → Geo Utilities: uses distance tools (evidence: `backend/trips/services/routing.py`)
- HOS Simulation → Geo Utilities: uses mileage tools (evidence: `backend/trips/services/hos_planner.py`)
- HOS Simulation → Compliance Validation: validates plan (evidence: `README.md`)
- Daily Log Builder → HOS Simulation: splits segments (evidence: `backend/trips/services/log_builder.py`)
- Daily Log Builder → Geo Utilities: interpolates locations (evidence: `backend/trips/services/log_builder.py`)
- Daily Log Builder → Geocoding: reverse geocodes remarks (evidence: `README.md`)
- Django API → Console App: returns plan (evidence: `README.md`)
- Console App → Trip Summary: renders summary (evidence: `frontend/src/App.tsx`)
- Console App → HOS Gauges: renders HOS gauges (evidence: `frontend/src/App.tsx`)
- Console App → Route Map: renders route (evidence: `frontend/src/App.tsx`)
- Console App → Stops Timeline: renders schedule (evidence: `frontend/src/App.tsx`)
- Console App → Log Viewer: renders logs (evidence: `frontend/src/App.tsx`)
- Log Viewer → Daily Log Sheet: renders sheets (evidence: `frontend/src/features/logs/LogSheetViewer.tsx`)
