# argon573/optimization-urban-delivery-routes architecture

> Architecture diagram of the GitHub repository argon573/optimization-urban-delivery-routes, 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/argon573/optimization-urban-delivery-routes
- Repository: https://github.com/argon573/optimization-urban-delivery-routes

## Overview

This is a delivery-route optimization product: users enter a start location and delivery points, choose transport preferences, request an optimized route, and inspect it on a Leaflet map. The backend exposes geocoding, route optimization, matrix and point-generation APIs; the README also documents saved history/favorites and local OSRM routing. Traffic-pattern CSV generation is a separate backend capability. Some frontend and backend internals were not sampled, so edges to them are limited to explicit README or index evidence.

Main entry points: [`frontend/src/components/RouteScreen/RouteScreen.jsx`](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/RouteScreen.jsx) (Route editor), [`backend/routes.py`](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/routes.py) (Route and address endpoints), [`frontend/src/context/RouteContext.jsx`](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/context/RouteContext.jsx) (Route state and build), [`backend/traffic/traffic_generator.py`](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/traffic/traffic_generator.py) (Traffic CSV generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Route planning UI"]
  node_app["Application shell<br/>[App.jsx]"]
  node_router["Page routing<br/>[AppRouter.jsx]"]
  node_route_screen["Route editor<br/>[RouteScreen.jsx]"]
  node_point_entry["Point entry<br/>[WaypointInput.jsx]"]
  node_point_settings["Waypoint settings"]
  node_point_list["Waypoint list<br/>[WaypointList.jsx]"]
  node_start_form["Start location<br/>[StartPointForm.jsx]"]
  node_address_search["Address suggestions<br/>[usePhotonSearch.js]"]
  node_geocode_api["Geocoding client<br/>[geocodeAddress.js]"]
  node_route_state["Route state and build<br/>[RouteContext.jsx]"]
  node_route_actions["Route actions<br/>[RouteActions.jsx]"]
  node_map_view["Route map<br/>[RouteMapView.jsx]"]
  node_route_client["Route API client"]
  node_settings["History and generation<br/>[Settings.jsx]"]
end

subgraph group_backend["Routing API"]
  node_api_app["FastAPI application<br/>[app.py]"]
  node_api_routes["Route and address endpoints<br/>[routes.py]"]
  node_route_models["Request models<br/>[models.py]"]
  node_route_services["Routing algorithms<br/>[services.py]"]
  node_point_generator["Synthetic point generation<br/>[routes.py]"]
end

subgraph group_traffic["Traffic data"]
  node_traffic_updater["Traffic updater<br/>[traffic_updater.py]"]
  node_traffic_generator["Traffic CSV generation"]
  node_traffic_patterns["Traffic patterns"]
  node_traffic_csv[("OSRM traffic CSV")]
end

subgraph group_storage["Saved routes"]
  node_storage_hook["Saved-route access<br/>[useRouteStorage.js]"]
  node_route_storage[("History and favorites<br/>[routeStorage.js]")]
end

node_user(("Delivery planner"))
node_osrm["OSRM road routing"]
node_photon["Photon geocoder"]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_router
node_router -->|"routes to"| node_route_screen
node_route_screen -->|"renders"| node_point_entry
node_route_screen -->|"renders"| node_point_settings
node_route_screen -->|"renders"| node_point_list
node_route_screen -->|"renders"| node_start_form
node_point_entry -->|"queries"| node_address_search
node_point_entry -->|"geocodes"| node_geocode_api
node_start_form -->|"queries"| node_address_search
node_start_form -->|"geocodes"| node_geocode_api
node_address_search -->|"requests suggestions"| node_photon
node_route_screen -->|"reads and updates"| node_route_state
node_route_actions -->|"requests build"| node_route_state
node_route_state -->|"fetches route"| node_route_client
node_route_client -.->|"posts route request"| node_api_routes
node_api_app -->|"mounts router"| node_api_routes
node_api_routes -->|"uses request models"| node_route_models
node_api_routes -->|"calls routing logic"| node_route_services
node_route_services -.->|"gets road data"| node_osrm
node_route_state -.->|"supplies route state"| node_map_view
node_route_state -->|"saves history"| node_route_storage
node_settings -->|"uses saved routes"| node_storage_hook
node_storage_hook -->|"reads and writes"| node_route_storage
node_api_routes -->|"requests geocoding"| node_photon
node_api_routes -->|"generates points"| node_point_generator
node_api_app -->|"generates on startup"| node_traffic_generator
node_api_app -->|"starts updater"| node_traffic_updater
node_traffic_updater -->|"refreshes CSV"| node_traffic_generator
node_traffic_generator -->|"uses patterns"| node_traffic_patterns
node_traffic_generator -->|"writes"| node_traffic_csv

click node_app "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/App.jsx"
click node_router "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/router/AppRouter.jsx"
click node_route_screen "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/RouteScreen.jsx"
click node_point_entry "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/waypoints/WaypointInput.jsx"
click node_point_settings "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/waypoints/WaypointSettings.jsx"
click node_point_list "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/waypoints/WaypointList.jsx"
click node_start_form "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/StartPointForm/StartPointForm.jsx"
click node_address_search "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/hooks/usePhotonSearch.js"
click node_geocode_api "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/api/geocodeAddress.js"
click node_route_state "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/context/RouteContext.jsx"
click node_route_actions "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/RouteActions/RouteActions.jsx"
click node_map_view "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/map/RouteMapView.jsx"
click node_route_client "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/api/fetchRouteGeoJson.js"
click node_settings "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/settings/Settings.jsx"
click node_storage_hook "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/hooks/useRouteStorage.js"
click node_route_storage "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/services/routeStorage.js"
click node_api_app "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/app.py"
click node_api_routes "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/routes.py"
click node_route_models "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/models.py"
click node_route_services "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/services.py"
click node_point_generator "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/routes.py"
click node_traffic_updater "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/traffic/traffic_updater.py"
click node_traffic_generator "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/traffic/traffic_generator.py"
click node_traffic_patterns "https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/traffic/traffic_patterns.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_app,node_router,node_route_screen,node_point_entry,node_point_settings,node_point_list,node_start_form,node_address_search,node_geocode_api,node_route_state,node_route_actions,node_map_view,node_route_client,node_settings toneBlue
class node_api_app,node_api_routes,node_route_models,node_route_services,node_point_generator toneAmber
class node_traffic_updater,node_traffic_generator,node_traffic_patterns,node_traffic_csv toneMint
class node_storage_hook,node_route_storage toneRose
class node_user,node_osrm,node_photon toneIndigo
```

## Components

### Route planning UI

- [Application shell](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Page routing](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/router/AppRouter.jsx): `frontend/src/router/AppRouter.jsx`
- [Route editor](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/RouteScreen.jsx): `frontend/src/components/RouteScreen/RouteScreen.jsx`
- [Point entry](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/waypoints/WaypointInput.jsx): `frontend/src/components/RouteScreen/waypoints/WaypointInput.jsx`
- [Waypoint settings](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/waypoints/WaypointSettings.jsx): `frontend/src/components/RouteScreen/waypoints/WaypointSettings.jsx`
- [Waypoint list](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/waypoints/WaypointList.jsx): `frontend/src/components/RouteScreen/waypoints/WaypointList.jsx`
- [Start location](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/StartPointForm/StartPointForm.jsx): `frontend/src/components/RouteScreen/StartPointForm/StartPointForm.jsx`
- [Address suggestions](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/hooks/usePhotonSearch.js): `frontend/src/hooks/usePhotonSearch.js`
- [Geocoding client](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/api/geocodeAddress.js): `frontend/src/api/geocodeAddress.js`
- [Route state and build](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/context/RouteContext.jsx): `frontend/src/context/RouteContext.jsx`
- [Route actions](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/RouteScreen/RouteActions/RouteActions.jsx): `frontend/src/components/RouteScreen/RouteActions/RouteActions.jsx`
- [Route map](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/map/RouteMapView.jsx): `frontend/src/components/map/RouteMapView.jsx`
- [Route API client](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/api/fetchRouteGeoJson.js): `frontend/src/api/fetchRouteGeoJson.js`
- [History and generation](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/components/settings/Settings.jsx): `frontend/src/components/settings/Settings.jsx`

### Routing API

- [FastAPI application](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/app.py): `backend/app.py`
- [Route and address endpoints](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/routes.py): `backend/routes.py`
- [Request models](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/models.py): `backend/models.py`
- [Routing algorithms](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/services.py): `backend/services.py`
- [Synthetic point generation](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/routes.py): `backend/routes.py`

### Traffic data

- [Traffic updater](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/traffic/traffic_updater.py): `backend/traffic/traffic_updater.py`
- [Traffic CSV generation](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/traffic/traffic_generator.py): `backend/traffic/traffic_generator.py`
- [Traffic patterns](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/backend/traffic/traffic_patterns.py): `backend/traffic/traffic_patterns.py`
- **OSRM traffic CSV**

### Saved routes

- [Saved-route access](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/hooks/useRouteStorage.js): `frontend/src/hooks/useRouteStorage.js`
- [History and favorites](https://github.com/argon573/optimization-urban-delivery-routes/blob/master/frontend/src/services/routeStorage.js): `frontend/src/services/routeStorage.js`

### Other components

- **Delivery planner**
- **OSRM road routing**
- **Photon geocoder**

## Connections

- Delivery planner → Application shell: uses (evidence: `frontend/src/App.jsx`)
- Application shell → Page routing: renders (evidence: `frontend/src/App.jsx`)
- Page routing → Route editor: routes to (evidence: `frontend/src/router/AppRouter.jsx`)
- Route editor → Point entry: renders (evidence: `frontend/src/components/RouteScreen/RouteScreen.jsx`)
- Route editor → Waypoint settings: renders (evidence: `frontend/src/components/RouteScreen/RouteScreen.jsx`)
- Route editor → Waypoint list: renders (evidence: `frontend/src/components/RouteScreen/RouteScreen.jsx`)
- Route editor → Start location: renders (evidence: `frontend/src/components/RouteScreen/RouteScreen.jsx`)
- Point entry → Address suggestions: queries (evidence: `frontend/src/components/RouteScreen/waypoints/WaypointInput.jsx`)
- Point entry → Geocoding client: geocodes (evidence: `frontend/src/components/RouteScreen/waypoints/WaypointInput.jsx`)
- Start location → Address suggestions: queries (evidence: `frontend/src/components/RouteScreen/StartPointForm/StartPointForm.jsx`)
- Start location → Geocoding client: geocodes (evidence: `frontend/src/components/RouteScreen/StartPointForm/StartPointForm.jsx`)
- Address suggestions → Photon geocoder: requests suggestions (evidence: `frontend/src/hooks/usePhotonSearch.js`)
- Route editor → Route state and build: reads and updates (evidence: `frontend/src/components/RouteScreen/RouteScreen.jsx`)
- Route actions → Route state and build: requests build (evidence: `frontend/src/components/RouteScreen/RouteActions/RouteActions.jsx`)
- Route state and build → Route API client: fetches route (evidence: `frontend/src/context/RouteContext.jsx`)
- Route API client → Route and address endpoints: posts route request (evidence: `README.md`)
- FastAPI application → Route and address endpoints: mounts router (evidence: `backend/app.py`)
- Route and address endpoints → Request models: uses request models (evidence: `backend/routes.py`)
- Route and address endpoints → Routing algorithms: calls routing logic (evidence: `backend/routes.py`)
- Routing algorithms → OSRM road routing: gets road data (evidence: `README.md`)
- Route state and build → Route map: supplies route state
- Route state and build → History and favorites: saves history (evidence: `frontend/src/context/RouteContext.jsx`)
- History and generation → Saved-route access: uses saved routes (evidence: `frontend/src/components/settings/Settings.jsx`)
- Saved-route access → History and favorites: reads and writes (evidence: `frontend/src/hooks/useRouteStorage.js`)
- Route and address endpoints → Photon geocoder: requests geocoding (evidence: `backend/routes.py`)
- Route and address endpoints → Synthetic point generation: generates points (evidence: `backend/routes.py`)
- FastAPI application → Traffic CSV generation: generates on startup (evidence: `backend/app.py`)
- FastAPI application → Traffic updater: starts updater (evidence: `backend/app.py`)
- Traffic updater → Traffic CSV generation: refreshes CSV (evidence: `backend/traffic/traffic_updater.py`)
- Traffic CSV generation → Traffic patterns: uses patterns (evidence: `backend/traffic/traffic_generator.py`)
- Traffic CSV generation → OSRM traffic CSV: writes (evidence: `backend/traffic/traffic_generator.py`)
