# esha-05/fuel-route-project architecture

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

## Overview

Fuel Route Planner is a Django REST API that accepts US origin and destination locations and returns a driving route, fuel-stop recommendations, and trip fuel totals. The principal workflow validates the request, geocodes both endpoints, obtains route geometry and distance, then plans stops using nearby station prices. Fuel data uses the provided station-price CSV and US city coordinates. The README also describes station geocoding as disk-cached, but the sampled implementation shows in-memory station caching; the cache mechanism is therefore not represented as a separate component.

Main entry points: [`fuel_route_project/route_planner/views.py`](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/views.py) (Route endpoint), [`fuel_route_project/route_planner/geocoder.py`](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/geocoder.py) (Location geocoder), [`fuel_route_project/route_planner/fuel_data.py`](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/fuel_data.py) (Station lookup), [`fuel_route_project/route_planner/osrm_client.py`](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/osrm_client.py) (OSRM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_route_view["Route endpoint<br/>[views.py]"]
  node_request_validation["Request validation<br/>[serializers.py]"]
end

subgraph group_location["Location lookup"]
  node_geocoder["Location geocoder<br/>[geocoder.py]"]
  node_city_coordinates["City coordinates<br/>[uscities.csv]"]
end

subgraph group_routing["Route lookup"]
  node_route_client["OSRM client<br/>[osrm_client.py]"]
end

subgraph group_fuel["Fuel planning"]
  node_stop_optimizer["Stop optimizer<br/>[route_optimizer.py]"]
  node_station_lookup["Station lookup<br/>[fuel_data.py]"]
  node_fuel_prices["Fuel prices<br/>[fuel_prices.csv]"]
end

node_caller(("API client"))
node_photon["Photon API"]
node_nominatim["Nominatim API"]
node_osrm["OSRM routing"]

node_caller -->|"requests route"| node_route_view
node_route_view -->|"validates input"| node_request_validation
node_route_view -->|"geocodes endpoints"| node_geocoder
node_geocoder -->|"queries first"| node_photon
node_geocoder -->|"falls back to"| node_nominatim
node_route_view -->|"requests route"| node_route_client
node_route_client -->|"fetches geometry"| node_osrm
node_route_view -->|"plans fuel stops"| node_stop_optimizer
node_stop_optimizer -->|"searches nearby"| node_station_lookup
node_station_lookup -->|"resolves city coordinates"| node_city_coordinates
node_station_lookup -->|"loads station prices"| node_fuel_prices

click node_route_view "https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/views.py"
click node_request_validation "https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/serializers.py"
click node_geocoder "https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/geocoder.py"
click node_city_coordinates "https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/uscities.csv"
click node_route_client "https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/osrm_client.py"
click node_stop_optimizer "https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/route_optimizer.py"
click node_station_lookup "https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/fuel_data.py"
click node_fuel_prices "https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/fuel_prices.csv"

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_view,node_request_validation,node_caller toneBlue
class node_geocoder,node_city_coordinates toneAmber
class node_route_client,node_photon,node_nominatim toneMint
class node_stop_optimizer,node_station_lookup,node_fuel_prices toneRose
class node_osrm toneIndigo
```

## Components

### API

- [Route endpoint](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/views.py): `fuel_route_project/route_planner/views.py`
- [Request validation](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/serializers.py): `fuel_route_project/route_planner/serializers.py`

### Location lookup

- [Location geocoder](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/geocoder.py): `fuel_route_project/route_planner/geocoder.py`
- [City coordinates](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/uscities.csv): `fuel_route_project/uscities.csv`

### Route lookup

- [OSRM client](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/osrm_client.py): `fuel_route_project/route_planner/osrm_client.py`

### Fuel planning

- [Stop optimizer](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/route_optimizer.py): `fuel_route_project/route_planner/route_optimizer.py`
- [Station lookup](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/route_planner/fuel_data.py): `fuel_route_project/route_planner/fuel_data.py`
- [Fuel prices](https://github.com/esha-05/fuel-route-project/blob/main/fuel_route_project/fuel_prices.csv): `fuel_route_project/fuel_prices.csv`

### Other components

- **API client**
- **Photon API**
- **Nominatim API**
- **OSRM routing**

## Connections

- API client → Route endpoint: requests route (evidence: `README.md`)
- Route endpoint → Request validation: validates input (evidence: `fuel_route_project/route_planner/views.py`)
- Route endpoint → Location geocoder: geocodes endpoints (evidence: `fuel_route_project/route_planner/views.py`)
- Location geocoder → Photon API: queries first (evidence: `fuel_route_project/route_planner/geocoder.py`)
- Location geocoder → Nominatim API: falls back to (evidence: `fuel_route_project/route_planner/geocoder.py`)
- Route endpoint → OSRM client: requests route (evidence: `fuel_route_project/route_planner/views.py`)
- OSRM client → OSRM routing: fetches geometry (evidence: `fuel_route_project/route_planner/osrm_client.py`)
- Route endpoint → Stop optimizer: plans fuel stops (evidence: `fuel_route_project/route_planner/views.py`)
- Stop optimizer → Station lookup: searches nearby (evidence: `fuel_route_project/route_planner/route_optimizer.py`)
- Station lookup → City coordinates: resolves city coordinates (evidence: `fuel_route_project/route_planner/fuel_data.py`)
- Station lookup → Fuel prices: loads station prices (evidence: `fuel_route_project/route_planner/fuel_data.py`)
