# manuelbomi/last-mile-route-optimization architecture

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

- Interactive diagram: https://gitdiagram.com/manuelbomi/last-mile-route-optimization
- Repository: https://github.com/manuelbomi/last-mile-route-optimization

## Overview

This repository is a last-mile delivery optimization demo. Its workflow generates or loads a daily stop manifest, solves it through both a full OR-Tools routing model and a separate exact Pyomo assignment model, then visualizes the OR-Tools routes as a static plot and GeoJSON for the dispatcher dashboard. Distance and travel-time calculations support both solvers. The README documents the dashboard and solver-backend portability; frontend implementation details were not sampled, so those links are limited to documented data flow.

Main entry points: [`scripts/run_route_optimization.py`](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/scripts/run_route_optimization.py) (Optimization Runner), [`src/routing/visualize.py`](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/visualize.py) (Route Visualizer), [`data/generate_delivery_stops.py`](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/data/generate_delivery_stops.py) (Stop Generator), [`src/routing/or_tools_solver.py`](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/or_tools_solver.py) (CVRP Solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Stop Planning"]
  node_generator["Stop Generator"]
  node_manifest["Stop Manifest<br/>[delivery_stops.csv]"]
  node_runner["Optimization Runner"]
end

subgraph group_solving["Optimization Solvers"]
  node_distance["Distance Utilities<br/>[distance.py]"]
  node_ortools["CVRP Solver<br/>[or_tools_solver.py]"]
  node_milp["Assignment MILP"]
end

subgraph group_outputs["Route Outputs"]
  node_visualize["Route Visualizer<br/>[visualize.py]"]
  node_routeplot["Static Route Plot"]
  node_geojson["Route GeoJSON<br/>[routes.geojson]"]
  node_summary["Optimization Summary"]
end

subgraph group_dashboard["Dispatch Dashboard"]
  node_dashboard["Map Dashboard"]
end

node_dispatcher(("Dispatcher"))

node_runner -->|"generates if missing"| node_generator
node_generator -->|"writes stops"| node_manifest
node_runner -->|"loads stops"| node_manifest
node_runner -->|"solves routes"| node_ortools
node_runner -->|"solves assignments"| node_milp
node_ortools -->|"builds matrices"| node_distance
node_milp -->|"computes distances"| node_distance
node_runner -->|"plots and exports"| node_visualize
node_visualize -->|"writes plot"| node_routeplot
node_visualize -->|"exports routes"| node_geojson
node_runner -->|"writes metrics"| node_summary
node_geojson -->|"renders map data"| node_dashboard
node_dispatcher -->|"reviews routes"| node_dashboard

click node_generator "https://github.com/manuelbomi/last-mile-route-optimization/blob/main/data/generate_delivery_stops.py"
click node_manifest "https://github.com/manuelbomi/last-mile-route-optimization/blob/main/data/delivery_stops.csv"
click node_runner "https://github.com/manuelbomi/last-mile-route-optimization/blob/main/scripts/run_route_optimization.py"
click node_distance "https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/distance.py"
click node_ortools "https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/or_tools_solver.py"
click node_milp "https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/pyomo_milp_solver.py"
click node_visualize "https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/visualize.py"
click node_routeplot "https://github.com/manuelbomi/last-mile-route-optimization/tree/main/reports/figures"
click node_geojson "https://github.com/manuelbomi/last-mile-route-optimization/blob/main/frontend/routes.geojson"
click node_summary "https://github.com/manuelbomi/last-mile-route-optimization/blob/main/reports/figures/optimization_summary.json"
click node_dashboard "https://github.com/manuelbomi/last-mile-route-optimization/tree/main/frontend"

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_generator,node_manifest,node_runner toneBlue
class node_distance,node_ortools,node_milp toneAmber
class node_visualize,node_routeplot,node_geojson,node_summary toneMint
class node_dashboard toneRose
class node_dispatcher toneIndigo
```

## Components

### Stop Planning

- [Stop Generator](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/data/generate_delivery_stops.py): `data/generate_delivery_stops.py`
- [Stop Manifest](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/data/delivery_stops.csv): `data/delivery_stops.csv`
- [Optimization Runner](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/scripts/run_route_optimization.py): `scripts/run_route_optimization.py`

### Optimization Solvers

- [Distance Utilities](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/distance.py): `src/routing/distance.py`
- [CVRP Solver](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/or_tools_solver.py): `src/routing/or_tools_solver.py`
- [Assignment MILP](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/pyomo_milp_solver.py): `src/routing/pyomo_milp_solver.py`

### Route Outputs

- [Route Visualizer](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/src/routing/visualize.py): `src/routing/visualize.py`
- [Static Route Plot](https://github.com/manuelbomi/last-mile-route-optimization/tree/main/reports/figures): `reports/figures`
- [Route GeoJSON](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/frontend/routes.geojson): `frontend/routes.geojson`
- [Optimization Summary](https://github.com/manuelbomi/last-mile-route-optimization/blob/main/reports/figures/optimization_summary.json): `reports/figures/optimization_summary.json`

### Dispatch Dashboard

- [Map Dashboard](https://github.com/manuelbomi/last-mile-route-optimization/tree/main/frontend): `frontend`

### Other components

- **Dispatcher**

## Connections

- Optimization Runner → Stop Generator: generates if missing (evidence: `scripts/run_route_optimization.py`)
- Stop Generator → Stop Manifest: writes stops (evidence: `data/generate_delivery_stops.py`)
- Optimization Runner → Stop Manifest: loads stops (evidence: `scripts/run_route_optimization.py`)
- Optimization Runner → CVRP Solver: solves routes (evidence: `scripts/run_route_optimization.py`)
- Optimization Runner → Assignment MILP: solves assignments (evidence: `scripts/run_route_optimization.py`)
- CVRP Solver → Distance Utilities: builds matrices (evidence: `src/routing/or_tools_solver.py`)
- Assignment MILP → Distance Utilities: computes distances (evidence: `src/routing/pyomo_milp_solver.py`)
- Optimization Runner → Route Visualizer: plots and exports (evidence: `scripts/run_route_optimization.py`)
- Route Visualizer → Static Route Plot: writes plot (evidence: `README.md`)
- Route Visualizer → Route GeoJSON: exports routes (evidence: `src/routing/visualize.py`)
- Optimization Runner → Optimization Summary: writes metrics (evidence: `scripts/run_route_optimization.py`)
- Route GeoJSON → Map Dashboard: renders map data (evidence: `README.md`)
- Dispatcher → Map Dashboard: reviews routes (evidence: `README.md`)
