# meetmendapara09/eld-trip-planner architecture

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

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

## Overview

#### Purpose and Entry Points
RouteLog Pro is a full-stack commercial-driver trip planner that produces FMCSA Hours-of-Service schedules and ELD-style daily logs. The React client starts at `frontend/src/main.jsx` and `frontend/src/App.jsx`; its API boundary is `frontend/src/services/api.js`. Django starts through `backend/manage.py`, with HTTP routing rooted in `backend/eld_backend/urls.py` and deployment-oriented API entry modules at `api/index.py` and `backend/api/index.py`.

#### Client Application
The Vite/React frontend collects trip inputs, invokes the backend, and renders planning artifacts rather than computing compliance logic itself. `frontend/src/components/TripForm.jsx` captures locations and cycle usage; `frontend/src/components/ResultsView.jsx` composes returned results. Map, schedule, fuel, summary, and daily-log views consume the resulting trip payload through `frontend/src/components/MapView.jsx`, `frontend/src/components/ScheduleTable.jsx`, and `frontend/src/components/DailyLogSheet.jsx`.

Authentication-aware dashboard and saved/shared-trip views are also client-side application surfaces: `frontend/src/pages/DashboardPage.jsx`, `frontend/src/components/SavedTripView.jsx`, and `frontend/src/components/SharedTripView.jsx`.

#### API and Domain Boundary
Django REST endpoints are organized into two domains: accounts and trips. URL-to-view dispatch lives in `backend/accounts/urls.py` and `backend/trips/urls.py`, with request orchestration in `backend/accounts/views.py` and `backend/trips/views.py`. Serializers form the API validation/representation boundary in `backend/trips/serializers.py` and `backend/accounts/serializers.py`.

The primary planning endpoint is `POST /api/trip/`: it accepts current/pickup/dropoff locations plus consumed cycle hours and returns route geometry, scheduled duty segments, logs, coordinates, and aggregate trip metrics.

#### Trip Planning Pipeline
Trip processing is service-layer orchestration behind `backend/trips/views.py`:
1. Resolve textual locations to coordinates via `backend/trips/services/geocoding.py`.
2. Request a drivable route, distance, duration, and geometry through `backend/trips/services/routing.py`.
3. Convert route duration/distance and cycle state into legally constrained activities with `backend/trips/services/hos_scheduler.py`.
4. Produce daily ELD duty-status log data in `backend/trips/services/log_generator.py`.
5. Optionally generate document output via `backend/trips/services/pdf_generator.py`.

This separates external geographic data from deterministic HOS and reporting calculations.

#### Persistence, Identity, and Sharing
Trip persistence is modeled in `backend/trips/models.py`; schema evolution includes trip sharing support in `backend/trips/migrations/0002_trip_share_token.py`. Accounts use Django models and migrations in `backend/accounts/models.py` and `backend/accounts/migrations/0001_initial.py`. These domains enable authenticated driver profiles, saved trips, and token-addressable shared trips while keeping generated planning results exposed through serializers/views.

#### Compliance and External Services
The HOS scheduler is the compliance-critical component: `backend/trips/services/hos_scheduler.py` applies 11-hour driving, 14-hour duty-window, 30-minute break, 10-hour rest reset, and 70-hour/8-day cycle constraints; it also accounts for pickup/delivery and periodic fuel-stop activities. Log generation in `backend/trips/services/log_generator.py` turns this schedule into 24-hour ELD records.

Geocoding uses OpenStreetMap Nominatim. Routing prefers OpenRouteService when `ORS_API_KEY` is configured and falls back to OSRM. The browser map uses React Leaflet/OpenStreetMap. Backend runtime is Python/Django/DRF; frontend runtime is React/Vite. Deployment configuration exists in `backend/render.yaml`, `backend/vercel.json`, and root `vercel.json`.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_frontend_entry["React entry<br/>React/Vite<br/>[main.jsx]"]
  node_app["Client application<br/>React app<br/>[App.jsx]"]
  node_trip_ui["Trip planning UI<br/>React components<br/>[TripForm.jsx]"]
  node_trip_results["Planning results<br/>React views<br/>[ResultsView.jsx]"]
  node_account_ui["Dashboard &amp; shared trips<br/>React views<br/>[DashboardPage.jsx]"]
  node_api_client["API client<br/>HTTP boundary<br/>[api.js]"]
end

subgraph group_api["Django API"]
  node_django_entry["Django runtime<br/>Python/Django<br/>[manage.py]"]
  node_root_routes["Root URL routing<br/>Django URLs<br/>[urls.py]"]
  node_trip_api["Trips API<br/>DRF views<br/>[views.py]"]
  node_account_api["Accounts API<br/>DRF views<br/>[views.py]"]
  node_serializers["API serializers<br/>DRF serializers<br/>[serializers.py]"]
end

subgraph group_planning["Planning Pipeline"]
  node_geocoding["Geocoding<br/>location service<br/>[geocoding.py]"]
  node_routing["Route calculation<br/>routing service<br/>[routing.py]"]
  node_hos_scheduler{{"HOS scheduler<br/>compliance engine<br/>[hos_scheduler.py]"}}
  node_log_generator["ELD log generator<br/>reporting service<br/>[log_generator.py]"]
end

subgraph group_data["Identity &amp; Persistence"]
  node_trip_store[("Trip persistence &amp; sharing<br/>Django models<br/>[models.py]")]
  node_accounts[("Driver accounts<br/>Django models<br/>[models.py]")]
end

subgraph group_external["External Services"]
  node_geo_providers(("Geographic providers"))
  node_map_provider(("Browser map<br/>React Leaflet / OpenStreetMap<br/>[MapView.jsx]"))
end

node_frontend_entry --> node_app
node_app --> node_trip_ui
node_app --> node_account_ui
node_trip_ui -->|"plan trip"| node_api_client
node_api_client -->|"REST requests"| node_root_routes
node_django_entry --> node_root_routes
node_root_routes -->|"trip routes"| node_trip_api
node_root_routes -->|"account routes"| node_account_api
node_trip_api -->|"validate / render"| node_serializers
node_account_api -->|"identity"| node_accounts
node_trip_api -->|"save / share"| node_trip_store
node_trip_api -->|"resolve locations"| node_geocoding
node_geocoding -->|"Nominatim"| node_geo_providers
node_trip_api -->|"request route"| node_routing
node_routing -->|"ORS or OSRM"| node_geo_providers
node_trip_api -->|"route + cycle state"| node_hos_scheduler
node_hos_scheduler -->|"duty schedule"| node_log_generator
node_trip_api -->|"generate logs"| node_log_generator
node_trip_api -->|"trip payload"| node_trip_results
node_trip_results -->|"route map"| node_map_provider
node_account_ui -->|"account / saved trips"| node_api_client

click node_frontend_entry "https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/App.jsx"
click node_trip_ui "https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/components/TripForm.jsx"
click node_trip_results "https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/components/ResultsView.jsx"
click node_account_ui "https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_api_client "https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/services/api.js"
click node_django_entry "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/manage.py"
click node_root_routes "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/eld_backend/urls.py"
click node_trip_api "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/views.py"
click node_account_api "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/accounts/views.py"
click node_serializers "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/serializers.py"
click node_geocoding "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/services/geocoding.py"
click node_routing "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/services/routing.py"
click node_hos_scheduler "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/services/hos_scheduler.py"
click node_log_generator "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/services/log_generator.py"
click node_trip_store "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/models.py"
click node_accounts "https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/accounts/models.py"
click node_map_provider "https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/components/MapView.jsx"

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_entry,node_app,node_trip_ui,node_trip_results,node_account_ui,node_api_client toneBlue
class node_django_entry,node_root_routes,node_trip_api,node_account_api,node_serializers toneAmber
class node_geocoding,node_routing,node_hos_scheduler,node_log_generator toneMint
class node_trip_store,node_accounts toneRose
class node_geo_providers,node_map_provider toneIndigo
```

## Components

### React Client

- [React entry](https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/main.jsx): React/Vite · `frontend/src/main.jsx`
- [Client application](https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/App.jsx): React app · `frontend/src/App.jsx`
- [Trip planning UI](https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/components/TripForm.jsx): React components · Captures inputs and renders map, schedule, results, and daily logs. · `frontend/src/components/TripForm.jsx`
- [Planning results](https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/components/ResultsView.jsx): React views · `frontend/src/components/ResultsView.jsx`
- [Dashboard & shared trips](https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/pages/DashboardPage.jsx): React views · `frontend/src/pages/DashboardPage.jsx`
- [API client](https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/services/api.js): HTTP boundary · `frontend/src/services/api.js`

### Django API

- [Django runtime](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/manage.py): Python/Django · `backend/manage.py`
- [Root URL routing](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/eld_backend/urls.py): Django URLs · `backend/eld_backend/urls.py`
- [Trips API](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/views.py): DRF views · Orchestrates planning, saved trips, and shared-trip requests. · `backend/trips/views.py`
- [Accounts API](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/accounts/views.py): DRF views · `backend/accounts/views.py`
- [API serializers](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/serializers.py): DRF serializers · Validates and represents trip and account payloads. · `backend/trips/serializers.py`

### Planning Pipeline

- [Geocoding](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/services/geocoding.py): location service · `backend/trips/services/geocoding.py`
- [Route calculation](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/services/routing.py): routing service · Returns drivable route, distance, duration, and geometry. · `backend/trips/services/routing.py`
- [HOS scheduler](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/services/hos_scheduler.py): compliance engine · Applies federal duty, break, rest, and cycle constraints. · `backend/trips/services/hos_scheduler.py`
- [ELD log generator](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/services/log_generator.py): reporting service · Converts scheduled activities into 24-hour duty records. · `backend/trips/services/log_generator.py`

### Identity & Persistence

- [Trip persistence & sharing](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/trips/models.py): Django models · Stores trips and token-addressable shared trips. · `backend/trips/models.py`
- [Driver accounts](https://github.com/meetmendapara09/eld-trip-planner/blob/main/backend/accounts/models.py): Django models · `backend/accounts/models.py`

### External Services

- **Geographic providers**: Nominatim / ORS / OSRM · Nominatim resolves locations; ORS routing falls back to OSRM.
- [Browser map](https://github.com/meetmendapara09/eld-trip-planner/blob/main/frontend/src/components/MapView.jsx): React Leaflet / OpenStreetMap · `frontend/src/components/MapView.jsx`

## Connections

- React entry → Client application
- Client application → Trip planning UI
- Client application → Dashboard & shared trips
- Trip planning UI → API client: plan trip
- API client → Root URL routing: REST requests
- Django runtime → Root URL routing
- Root URL routing → Trips API: trip routes
- Root URL routing → Accounts API: account routes
- Trips API → API serializers: validate / render
- Accounts API → Driver accounts: identity
- Trips API → Trip persistence & sharing: save / share
- Trips API → Geocoding: resolve locations
- Geocoding → Geographic providers: Nominatim
- Trips API → Route calculation: request route
- Route calculation → Geographic providers: ORS or OSRM
- Trips API → HOS scheduler: route + cycle state
- HOS scheduler → ELD log generator: duty schedule
- Trips API → ELD log generator: generate logs
- Trips API → Planning results: trip payload
- Planning results → Browser map: route map
- Dashboard & shared trips → API client: account / saved trips
