# eccureuil/fuel-route-optimizer architecture

> Architecture diagram of the GitHub repository eccureuil/fuel-route-optimizer, 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/eccureuil/fuel-route-optimizer
- Repository: https://github.com/eccureuil/fuel-route-optimizer

## Overview

Fuel Route Optimizer is a Django service and map UI that turns origin/destination addresses into a truck-feasible, low-cost fuel-stop plan. The primary request path geocodes both endpoints, fetches route geometry, filters nearby stations, validates range feasibility, and selects stops; results include route and station data for visualization. A separate import command loads and deduplicates station pricing data, while a cached endpoint reuses successful route responses. The excerpts show these principal connections; some implementation details are omitted, so uncertain wiring is not represented.

Main entry points: [`routing/urls.py`](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/urls.py) (API routes), [`routing/services/fuel_optimizer.py`](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/fuel_optimizer.py) (Optimization planner), [`routing/views.py`](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/views.py) (Route handler), [`routing/management/commands/import_stations.py`](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/management/commands/import_stations.py) (Station importer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and UI"]
  node_route_urls["API routes<br/>[urls.py]"]
  node_route_view["Route handler<br/>[views.py]"]
  node_cached_view["Cached route<br/>[views.py]"]
  node_map_view["Map page handler<br/>[views.py]"]
  node_map_template["Interactive map<br/>[route_map.html]"]
  node_cache_store[("Route cache")]
end

subgraph group_routing["Route planning"]
  node_optimizer["Optimization planner<br/>[fuel_optimizer.py]"]
  node_station_filter["Corridor filtering<br/>[fuel_optimizer.py]"]
  node_feasibility["Range validation<br/>[fuel_optimizer.py]"]
  node_stop_selector["Greedy stop selection<br/>[fuel_optimizer.py]"]
end

subgraph group_data["Station data"]
  node_station_store[("Station records<br/>[models.py]")]
  node_import_command["Station importer<br/>[import_stations.py]"]
  node_station_workbook["Station workbook"]
end

subgraph group_integrations["External services"]
  node_mapbox_service["Mapbox adapter<br/>[mapbox_service.py]"]
  node_mapbox{{"Mapbox APIs"}}
end

node_driver(("Route requester"))

node_driver -->|"requests route"| node_route_urls
node_route_urls -->|"dispatches"| node_route_view
node_route_urls -->|"dispatches"| node_cached_view
node_route_urls -->|"dispatches"| node_map_view
node_map_view -->|"renders"| node_map_template
node_cached_view -->|"checks and stores"| node_cache_store
node_cached_view -->|"computes cache miss"| node_route_view
node_route_view -->|"geocodes and routes"| node_mapbox_service
node_mapbox_service -->|"requests APIs"| node_mapbox
node_route_view -->|"plans fuel stops"| node_optimizer
node_optimizer -->|"filters stations"| node_station_filter
node_station_filter -->|"queries candidates"| node_station_store
node_optimizer -->|"validates range"| node_feasibility
node_optimizer -->|"selects stops"| node_stop_selector
node_import_command -->|"loads data"| node_station_workbook
node_import_command -->|"deduplicates and inserts"| node_station_store

click node_route_urls "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/urls.py"
click node_route_view "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/views.py"
click node_cached_view "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/views.py"
click node_map_view "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/views.py"
click node_map_template "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/templates/routing/route_map.html"
click node_mapbox_service "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/mapbox_service.py"
click node_optimizer "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/fuel_optimizer.py"
click node_station_filter "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/fuel_optimizer.py"
click node_feasibility "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/fuel_optimizer.py"
click node_stop_selector "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/fuel_optimizer.py"
click node_station_store "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/models.py"
click node_import_command "https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/management/commands/import_stations.py"
click node_station_workbook "https://github.com/eccureuil/fuel-route-optimizer/blob/main/fuel-prices-enriched-with-coordinates.xlsx"

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_route_urls,node_route_view,node_cached_view,node_map_view,node_map_template,node_cache_store toneBlue
class node_optimizer,node_station_filter,node_feasibility,node_stop_selector toneAmber
class node_station_store,node_import_command,node_station_workbook,node_driver toneMint
class node_mapbox_service,node_mapbox toneRose
```

## Components

### API and UI

- [API routes](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/urls.py): `routing/urls.py`
- [Route handler](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/views.py): `routing/views.py`
- [Cached route](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/views.py): `routing/views.py`
- [Map page handler](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/views.py): `routing/views.py`
- [Interactive map](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/templates/routing/route_map.html): `routing/templates/routing/route_map.html`
- **Route cache**

### Route planning

- [Optimization planner](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/fuel_optimizer.py): `routing/services/fuel_optimizer.py`
- [Corridor filtering](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/fuel_optimizer.py): `routing/services/fuel_optimizer.py`
- [Range validation](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/fuel_optimizer.py): `routing/services/fuel_optimizer.py`
- [Greedy stop selection](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/fuel_optimizer.py): `routing/services/fuel_optimizer.py`

### Station data

- [Station records](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/models.py): `routing/models.py`
- [Station importer](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/management/commands/import_stations.py): `routing/management/commands/import_stations.py`
- [Station workbook](https://github.com/eccureuil/fuel-route-optimizer/blob/main/fuel-prices-enriched-with-coordinates.xlsx): `fuel-prices-enriched-with-coordinates.xlsx`

### External services

- [Mapbox adapter](https://github.com/eccureuil/fuel-route-optimizer/blob/main/routing/services/mapbox_service.py): `routing/services/mapbox_service.py`
- **Mapbox APIs**

### Other components

- **Route requester**

## Connections

- Route requester → API routes: requests route
- API routes → Route handler: dispatches
- API routes → Cached route: dispatches
- API routes → Map page handler: dispatches
- Map page handler → Interactive map: renders
- Cached route → Route cache: checks and stores
- Cached route → Route handler: computes cache miss
- Route handler → Mapbox adapter: geocodes and routes
- Mapbox adapter → Mapbox APIs: requests APIs
- Route handler → Optimization planner: plans fuel stops
- Optimization planner → Corridor filtering: filters stations
- Corridor filtering → Station records: queries candidates
- Optimization planner → Range validation: validates range
- Optimization planner → Greedy stop selection: selects stops
- Station importer → Station workbook: loads data
- Station importer → Station records: deduplicates and inserts