Upload 66 files

pom.xml

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="utf-8"?>

pyproject.toml

@@ -13,6 +13,10 @@ dependencies = [
     'pydantic == 2.7.3',
     'uvicorn == 0.30.1',
     'pytest == 8.2.2',
+    'osmnx >= 1.9.0',
+    'networkx >= 3.0',
+    'polyline >= 2.0.0',
+    'scikit-learn >= 1.0.0',
 ]
 
 

src/vehicle_routing/__init__.py

@@ -5,8 +5,7 @@ from .rest_api import app as app
 
 def main():
     config = uvicorn.Config("vehicle_routing:app",
-                            host="0.0.0.0",
-                            port=8080,
+                            port=8082,
                             log_config="logging.conf",
                             use_colors=True)
     server = uvicorn.Server(config)

src/vehicle_routing/demo_data.py

@@ -1,15 +1,210 @@
-from typing import Generator, TypeVar, Sequence
+from typing import Generator, TypeVar, Sequence, Optional
 from datetime import date, datetime, time, timedelta
 from enum import Enum
 from random import Random
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
-from .domain import Location, Vehicle, VehicleRoutePlan, Visit, init_driving_time_matrix, clear_driving_time_matrix
+from .domain import Location, Vehicle, VehicleRoutePlan, Visit
 
 
 FIRST_NAMES = ("Amy", "Beth", "Carl", "Dan", "Elsa", "Flo", "Gus", "Hugo", "Ivy", "Jay")
 LAST_NAMES = ("Cole", "Fox", "Green", "Jones", "King", "Li", "Poe", "Rye", "Smith", "Watt")
 
+
+# Real Philadelphia street addresses for demo data
+# These are actual locations on the road network for realistic routing
+PHILADELPHIA_REAL_LOCATIONS = {
+    "depots": [
+        {"name": "Central Depot - City Hall", "lat": 39.9526, "lng": -75.1652},
+        {"name": "South Philly Depot", "lat": 39.9256, "lng": -75.1697},
+        {"name": "University City Depot", "lat": 39.9522, "lng": -75.1932},
+        {"name": "North Philly Depot", "lat": 39.9907, "lng": -75.1556},
+        {"name": "Fishtown Depot", "lat": 39.9712, "lng": -75.1340},
+        {"name": "West Philly Depot", "lat": 39.9601, "lng": -75.2175},
+    ],
+    "visits": [
+        # Restaurants (for early morning deliveries)
+        {"name": "Reading Terminal Market", "lat": 39.9535, "lng": -75.1589, "type": "RESTAURANT"},
+        {"name": "Parc Restaurant", "lat": 39.9493, "lng": -75.1727, "type": "RESTAURANT"},
+        {"name": "Zahav", "lat": 39.9430, "lng": -75.1474, "type": "RESTAURANT"},
+        {"name": "Vetri Cucina", "lat": 39.9499, "lng": -75.1659, "type": "RESTAURANT"},
+        {"name": "Talula's Garden", "lat": 39.9470, "lng": -75.1709, "type": "RESTAURANT"},
+        {"name": "Fork", "lat": 39.9493, "lng": -75.1539, "type": "RESTAURANT"},
+        {"name": "Morimoto", "lat": 39.9488, "lng": -75.1559, "type": "RESTAURANT"},
+        {"name": "Vernick Food & Drink", "lat": 39.9508, "lng": -75.1718, "type": "RESTAURANT"},
+        {"name": "Friday Saturday Sunday", "lat": 39.9492, "lng": -75.1715, "type": "RESTAURANT"},
+        {"name": "Royal Izakaya", "lat": 39.9410, "lng": -75.1509, "type": "RESTAURANT"},
+        {"name": "Laurel", "lat": 39.9392, "lng": -75.1538, "type": "RESTAURANT"},
+        {"name": "Marigold Kitchen", "lat": 39.9533, "lng": -75.1920, "type": "RESTAURANT"},
+
+        # Businesses (for business hours deliveries)
+        {"name": "Comcast Center", "lat": 39.9543, "lng": -75.1690, "type": "BUSINESS"},
+        {"name": "Liberty Place", "lat": 39.9520, "lng": -75.1685, "type": "BUSINESS"},
+        {"name": "BNY Mellon Center", "lat": 39.9505, "lng": -75.1660, "type": "BUSINESS"},
+        {"name": "One Liberty Place", "lat": 39.9520, "lng": -75.1685, "type": "BUSINESS"},
+        {"name": "Aramark Tower", "lat": 39.9550, "lng": -75.1705, "type": "BUSINESS"},
+        {"name": "PSFS Building", "lat": 39.9510, "lng": -75.1618, "type": "BUSINESS"},
+        {"name": "Three Logan Square", "lat": 39.9567, "lng": -75.1720, "type": "BUSINESS"},
+        {"name": "Two Commerce Square", "lat": 39.9551, "lng": -75.1675, "type": "BUSINESS"},
+        {"name": "Penn Medicine", "lat": 39.9495, "lng": -75.1935, "type": "BUSINESS"},
+        {"name": "Children's Hospital", "lat": 39.9482, "lng": -75.1950, "type": "BUSINESS"},
+        {"name": "Drexel University", "lat": 39.9566, "lng": -75.1899, "type": "BUSINESS"},
+        {"name": "Temple University", "lat": 39.9812, "lng": -75.1554, "type": "BUSINESS"},
+        {"name": "Jefferson Hospital", "lat": 39.9487, "lng": -75.1577, "type": "BUSINESS"},
+        {"name": "Pennsylvania Hospital", "lat": 39.9445, "lng": -75.1545, "type": "BUSINESS"},
+        {"name": "FMC Tower", "lat": 39.9499, "lng": -75.1780, "type": "BUSINESS"},
+        {"name": "Cira Centre", "lat": 39.9560, "lng": -75.1822, "type": "BUSINESS"},
+
+        # Residential areas (for evening deliveries)
+        {"name": "Rittenhouse Square", "lat": 39.9496, "lng": -75.1718, "type": "RESIDENTIAL"},
+        {"name": "Washington Square West", "lat": 39.9468, "lng": -75.1545, "type": "RESIDENTIAL"},
+        {"name": "Society Hill", "lat": 39.9425, "lng": -75.1478, "type": "RESIDENTIAL"},
+        {"name": "Old City", "lat": 39.9510, "lng": -75.1450, "type": "RESIDENTIAL"},
+        {"name": "Northern Liberties", "lat": 39.9650, "lng": -75.1420, "type": "RESIDENTIAL"},
+        {"name": "Fishtown", "lat": 39.9712, "lng": -75.1340, "type": "RESIDENTIAL"},
+        {"name": "Queen Village", "lat": 39.9380, "lng": -75.1520, "type": "RESIDENTIAL"},
+        {"name": "Bella Vista", "lat": 39.9395, "lng": -75.1598, "type": "RESIDENTIAL"},
+        {"name": "Graduate Hospital", "lat": 39.9425, "lng": -75.1768, "type": "RESIDENTIAL"},
+        {"name": "Fairmount", "lat": 39.9680, "lng": -75.1750, "type": "RESIDENTIAL"},
+        {"name": "Spring Garden", "lat": 39.9620, "lng": -75.1620, "type": "RESIDENTIAL"},
+        {"name": "Art Museum Area", "lat": 39.9656, "lng": -75.1810, "type": "RESIDENTIAL"},
+        {"name": "Brewerytown", "lat": 39.9750, "lng": -75.1850, "type": "RESIDENTIAL"},
+        {"name": "East Passyunk", "lat": 39.9310, "lng": -75.1605, "type": "RESIDENTIAL"},
+        {"name": "Point Breeze", "lat": 39.9285, "lng": -75.1780, "type": "RESIDENTIAL"},
+        {"name": "Pennsport", "lat": 39.9320, "lng": -75.1450, "type": "RESIDENTIAL"},
+        {"name": "Powelton Village", "lat": 39.9610, "lng": -75.1950, "type": "RESIDENTIAL"},
+        {"name": "Spruce Hill", "lat": 39.9530, "lng": -75.2100, "type": "RESIDENTIAL"},
+        {"name": "Cedar Park", "lat": 39.9490, "lng": -75.2200, "type": "RESIDENTIAL"},
+        {"name": "Kensington", "lat": 39.9850, "lng": -75.1280, "type": "RESIDENTIAL"},
+        {"name": "Port Richmond", "lat": 39.9870, "lng": -75.1120, "type": "RESIDENTIAL"},
+        # Note: Removed distant locations (Manayunk, Roxborough, Chestnut Hill, Mount Airy, Germantown)
+        # to keep the bounding box compact for faster OSMnx downloads
+    ],
+}
+
+# Hartford real locations
+HARTFORD_REAL_LOCATIONS = {
+    "depots": [
+        {"name": "Downtown Hartford Depot", "lat": 41.7658, "lng": -72.6734},
+        {"name": "Asylum Hill Depot", "lat": 41.7700, "lng": -72.6900},
+        {"name": "South End Depot", "lat": 41.7400, "lng": -72.6750},
+        {"name": "West End Depot", "lat": 41.7680, "lng": -72.7100},
+        {"name": "Barry Square Depot", "lat": 41.7450, "lng": -72.6800},
+        {"name": "Clay Arsenal Depot", "lat": 41.7750, "lng": -72.6850},
+    ],
+    "visits": [
+        # Restaurants
+        {"name": "Max Downtown", "lat": 41.7670, "lng": -72.6730, "type": "RESTAURANT"},
+        {"name": "Trumbull Kitchen", "lat": 41.7650, "lng": -72.6750, "type": "RESTAURANT"},
+        {"name": "Salute", "lat": 41.7630, "lng": -72.6740, "type": "RESTAURANT"},
+        {"name": "Peppercorns Grill", "lat": 41.7690, "lng": -72.6680, "type": "RESTAURANT"},
+        {"name": "Feng Asian Bistro", "lat": 41.7640, "lng": -72.6725, "type": "RESTAURANT"},
+        {"name": "On20", "lat": 41.7655, "lng": -72.6728, "type": "RESTAURANT"},
+        {"name": "First and Last Tavern", "lat": 41.7620, "lng": -72.7050, "type": "RESTAURANT"},
+        {"name": "Agave Grill", "lat": 41.7580, "lng": -72.6820, "type": "RESTAURANT"},
+        {"name": "Bear's Smokehouse", "lat": 41.7550, "lng": -72.6780, "type": "RESTAURANT"},
+        {"name": "City Steam Brewery", "lat": 41.7630, "lng": -72.6750, "type": "RESTAURANT"},
+
+        # Businesses
+        {"name": "Travelers Tower", "lat": 41.7658, "lng": -72.6734, "type": "BUSINESS"},
+        {"name": "Hartford Steam Boiler", "lat": 41.7680, "lng": -72.6700, "type": "BUSINESS"},
+        {"name": "Aetna Building", "lat": 41.7700, "lng": -72.6900, "type": "BUSINESS"},
+        {"name": "Connecticut Convention Center", "lat": 41.7615, "lng": -72.6820, "type": "BUSINESS"},
+        {"name": "Hartford Hospital", "lat": 41.7547, "lng": -72.6858, "type": "BUSINESS"},
+        {"name": "Connecticut Children's", "lat": 41.7560, "lng": -72.6850, "type": "BUSINESS"},
+        {"name": "Trinity College", "lat": 41.7474, "lng": -72.6909, "type": "BUSINESS"},
+        {"name": "Connecticut Science Center", "lat": 41.7650, "lng": -72.6695, "type": "BUSINESS"},
+
+        # Residential
+        {"name": "West End Hartford", "lat": 41.7680, "lng": -72.7000, "type": "RESIDENTIAL"},
+        {"name": "Asylum Hill", "lat": 41.7720, "lng": -72.6850, "type": "RESIDENTIAL"},
+        {"name": "Frog Hollow", "lat": 41.7580, "lng": -72.6900, "type": "RESIDENTIAL"},
+        {"name": "Barry Square", "lat": 41.7450, "lng": -72.6800, "type": "RESIDENTIAL"},
+        {"name": "South End", "lat": 41.7400, "lng": -72.6750, "type": "RESIDENTIAL"},
+        {"name": "Blue Hills", "lat": 41.7850, "lng": -72.7050, "type": "RESIDENTIAL"},
+        {"name": "Parkville", "lat": 41.7650, "lng": -72.7100, "type": "RESIDENTIAL"},
+        {"name": "Behind the Rocks", "lat": 41.7550, "lng": -72.7050, "type": "RESIDENTIAL"},
+        {"name": "Charter Oak", "lat": 41.7495, "lng": -72.6650, "type": "RESIDENTIAL"},
+        {"name": "Sheldon Charter Oak", "lat": 41.7510, "lng": -72.6700, "type": "RESIDENTIAL"},
+        {"name": "Clay Arsenal", "lat": 41.7750, "lng": -72.6850, "type": "RESIDENTIAL"},
+        {"name": "Upper Albany", "lat": 41.7780, "lng": -72.6950, "type": "RESIDENTIAL"},
+    ],
+}
+
+# Florence real locations
+FIRENZE_REAL_LOCATIONS = {
+    "depots": [
+        {"name": "Centro Storico Depot", "lat": 43.7696, "lng": 11.2558},
+        {"name": "Santa Maria Novella Depot", "lat": 43.7745, "lng": 11.2487},
+        {"name": "Campo di Marte Depot", "lat": 43.7820, "lng": 11.2820},
+        {"name": "Rifredi Depot", "lat": 43.7950, "lng": 11.2410},
+        {"name": "Novoli Depot", "lat": 43.7880, "lng": 11.2220},
+        {"name": "Gavinana Depot", "lat": 43.7520, "lng": 11.2680},
+    ],
+    "visits": [
+        # Restaurants
+        {"name": "Trattoria Mario", "lat": 43.7750, "lng": 11.2530, "type": "RESTAURANT"},
+        {"name": "Buca Mario", "lat": 43.7698, "lng": 11.2505, "type": "RESTAURANT"},
+        {"name": "Il Latini", "lat": 43.7705, "lng": 11.2495, "type": "RESTAURANT"},
+        {"name": "Osteria dell'Enoteca", "lat": 43.7680, "lng": 11.2545, "type": "RESTAURANT"},
+        {"name": "Trattoria Sostanza", "lat": 43.7735, "lng": 11.2470, "type": "RESTAURANT"},
+        {"name": "All'Antico Vinaio", "lat": 43.7690, "lng": 11.2570, "type": "RESTAURANT"},
+        {"name": "Mercato Centrale", "lat": 43.7762, "lng": 11.2540, "type": "RESTAURANT"},
+        {"name": "Cibreo", "lat": 43.7702, "lng": 11.2670, "type": "RESTAURANT"},
+        {"name": "Ora d'Aria", "lat": 43.7710, "lng": 11.2610, "type": "RESTAURANT"},
+        {"name": "Buca Lapi", "lat": 43.7720, "lng": 11.2535, "type": "RESTAURANT"},
+        {"name": "Il Palagio", "lat": 43.7680, "lng": 11.2550, "type": "RESTAURANT"},
+        {"name": "Enoteca Pinchiorri", "lat": 43.7695, "lng": 11.2620, "type": "RESTAURANT"},
+        {"name": "La Giostra", "lat": 43.7745, "lng": 11.2650, "type": "RESTAURANT"},
+        {"name": "Fishing Lab", "lat": 43.7730, "lng": 11.2560, "type": "RESTAURANT"},
+        {"name": "Trattoria Cammillo", "lat": 43.7665, "lng": 11.2520, "type": "RESTAURANT"},
+
+        # Businesses
+        {"name": "Palazzo Vecchio", "lat": 43.7693, "lng": 11.2563, "type": "BUSINESS"},
+        {"name": "Uffizi Gallery", "lat": 43.7677, "lng": 11.2553, "type": "BUSINESS"},
+        {"name": "Gucci Garden", "lat": 43.7692, "lng": 11.2556, "type": "BUSINESS"},
+        {"name": "Ferragamo Museum", "lat": 43.7700, "lng": 11.2530, "type": "BUSINESS"},
+        {"name": "Ospedale Santa Maria", "lat": 43.7830, "lng": 11.2690, "type": "BUSINESS"},
+        {"name": "Universita degli Studi", "lat": 43.7765, "lng": 11.2555, "type": "BUSINESS"},
+        {"name": "Palazzo Strozzi", "lat": 43.7706, "lng": 11.2515, "type": "BUSINESS"},
+        {"name": "Biblioteca Nazionale", "lat": 43.7660, "lng": 11.2650, "type": "BUSINESS"},
+        {"name": "Teatro del Maggio", "lat": 43.7780, "lng": 11.2470, "type": "BUSINESS"},
+        {"name": "Palazzo Pitti", "lat": 43.7650, "lng": 11.2500, "type": "BUSINESS"},
+        {"name": "Accademia Gallery", "lat": 43.7768, "lng": 11.2590, "type": "BUSINESS"},
+        {"name": "Ospedale Meyer", "lat": 43.7910, "lng": 11.2520, "type": "BUSINESS"},
+        {"name": "Polo Universitario", "lat": 43.7920, "lng": 11.2180, "type": "BUSINESS"},
+
+        # Residential
+        {"name": "Santo Spirito", "lat": 43.7665, "lng": 11.2470, "type": "RESIDENTIAL"},
+        {"name": "San Frediano", "lat": 43.7680, "lng": 11.2420, "type": "RESIDENTIAL"},
+        {"name": "Santa Croce", "lat": 43.7688, "lng": 11.2620, "type": "RESIDENTIAL"},
+        {"name": "San Lorenzo", "lat": 43.7755, "lng": 11.2540, "type": "RESIDENTIAL"},
+        {"name": "San Marco", "lat": 43.7780, "lng": 11.2585, "type": "RESIDENTIAL"},
+        {"name": "Sant'Ambrogio", "lat": 43.7705, "lng": 11.2680, "type": "RESIDENTIAL"},
+        {"name": "Campo di Marte", "lat": 43.7820, "lng": 11.2820, "type": "RESIDENTIAL"},
+        {"name": "Novoli", "lat": 43.7880, "lng": 11.2220, "type": "RESIDENTIAL"},
+        {"name": "Rifredi", "lat": 43.7950, "lng": 11.2410, "type": "RESIDENTIAL"},
+        {"name": "Le Cure", "lat": 43.7890, "lng": 11.2580, "type": "RESIDENTIAL"},
+        {"name": "Careggi", "lat": 43.8020, "lng": 11.2530, "type": "RESIDENTIAL"},
+        {"name": "Peretola", "lat": 43.7960, "lng": 11.2050, "type": "RESIDENTIAL"},
+        {"name": "Isolotto", "lat": 43.7620, "lng": 11.2200, "type": "RESIDENTIAL"},
+        {"name": "Gavinana", "lat": 43.7520, "lng": 11.2680, "type": "RESIDENTIAL"},
+        {"name": "Galluzzo", "lat": 43.7400, "lng": 11.2480, "type": "RESIDENTIAL"},
+        {"name": "Porta Romana", "lat": 43.7610, "lng": 11.2560, "type": "RESIDENTIAL"},
+        {"name": "Bellosguardo", "lat": 43.7650, "lng": 11.2350, "type": "RESIDENTIAL"},
+        {"name": "Arcetri", "lat": 43.7500, "lng": 11.2530, "type": "RESIDENTIAL"},
+        {"name": "Fiesole", "lat": 43.8055, "lng": 11.2935, "type": "RESIDENTIAL"},
+        {"name": "Settignano", "lat": 43.7850, "lng": 11.3100, "type": "RESIDENTIAL"},
+    ],
+}
+
+# Map demo data enum names to their real location data
+REAL_LOCATION_DATA = {
+    "PHILADELPHIA": PHILADELPHIA_REAL_LOCATIONS,
+    "HARTFORT": HARTFORD_REAL_LOCATIONS,
+    "FIRENZE": FIRENZE_REAL_LOCATIONS,
+}
+
 # Vehicle names using phonetic alphabet for clear identification
 VEHICLE_NAMES = ("Alpha", "Bravo", "Charlie", "Delta", "Echo", "Foxtrot", "Golf", "Hotel", "India", "Juliet")
 
@@ -91,26 +286,32 @@ class _DemoDataProperties:
 
 
 class DemoData(Enum):
+    # Bounding boxes tightened to ~5x5 km around actual location data
+    # for faster OSMnx network downloads (smaller area = faster download)
+
+    # Philadelphia: Center City area (~39.92 to 39.99 lat, -75.22 to -75.11 lng)
     PHILADELPHIA = _DemoDataProperties(0, 55, 6, time(6, 0),
                                        15, 30,
-                                       Location(latitude=39.7656099067391,
-                                                longitude=-76.83782328143754),
-                                       Location(latitude=40.77636644354855,
-                                                longitude=-74.9300739430771))
+                                       Location(latitude=39.92,
+                                                longitude=-75.23),
+                                       Location(latitude=40.00,
+                                                longitude=-75.11))
 
+    # Hartford: Downtown area (~41.69 to 41.79 lat, -72.75 to -72.60 lng)
     HARTFORT = _DemoDataProperties(1, 50, 6, time(6, 0),
                                    20, 30,
-                                   Location(latitude=41.48366520850297,
-                                            longitude=-73.15901689943055),
-                                   Location(latitude=41.99512052869307,
-                                            longitude=-72.25114548877427))
+                                   Location(latitude=41.69,
+                                            longitude=-72.75),
+                                   Location(latitude=41.79,
+                                            longitude=-72.60))
 
+    # Firenze: Historic center area
     FIRENZE = _DemoDataProperties(2, 77, 6, time(6, 0),
                                   20, 40,
-                                  Location(latitude=43.751466,
-                                           longitude=11.177210),
-                                  Location(latitude=43.809291,
-                                           longitude=11.290195))
+                                  Location(latitude=43.73,
+                                           longitude=11.17),
+                                  Location(latitude=43.81,
+                                           longitude=11.32))
 
 
 def doubles(random: Random, start: float, end: float) -> Generator[float, None, None]:
@@ -138,74 +339,139 @@ def generate_names(random: Random) -> Generator[str, None, None]:
         yield f'{random.choice(FIRST_NAMES)} {random.choice(LAST_NAMES)}'
 
 
-def generate_demo_data(demo_data_enum: DemoData, use_precomputed_matrix: bool = False) -> VehicleRoutePlan:
+def generate_demo_data(demo_data_enum: DemoData) -> VehicleRoutePlan:
     """
-    Generate demo data for vehicle routing.
+    Generate demo data for vehicle routing using real street addresses.
 
-    Creates a realistic delivery scenario with three customer types:
+    Uses actual locations on the road network for realistic routing:
     - Residential (50%): Evening windows (17:00-20:00), small orders (1-2 units)
     - Business (30%): Business hours (09:00-17:00), medium orders (3-6 units)
     - Restaurant (20%): Early morning (06:00-10:00), large orders (5-10 units)
 
     Args:
         demo_data_enum: The demo data configuration to use
-        use_precomputed_matrix: If True, pre-compute driving time matrix for O(1) lookups.
-                               If False (default), calculate distances on-demand.
-                               Pre-computed is faster during solving but uses O(n²) memory.
     """
     name = "demo"
     demo_data = demo_data_enum.value
     random = Random(demo_data.seed)
-    latitudes = doubles(random, demo_data.south_west_corner.latitude, demo_data.north_east_corner.latitude)
-    longitudes = doubles(random, demo_data.south_west_corner.longitude, demo_data.north_east_corner.longitude)
+
+    # Get real location data for this demo
+    real_locations = REAL_LOCATION_DATA.get(demo_data_enum.name)
 
     vehicle_capacities = ints(random, demo_data.min_vehicle_capacity,
                               demo_data.max_vehicle_capacity + 1)
 
-    vehicles = [Vehicle(id=str(i),
-                        name=VEHICLE_NAMES[i % len(VEHICLE_NAMES)],
-                        capacity=next(vehicle_capacities),
-                        home_location=Location(
-                            latitude=next(latitudes),
-                            longitude=next(longitudes)),
-                        departure_time=datetime.combine(
-                            date.today() + timedelta(days=1), demo_data.vehicle_start_time)
-                        )
-                for i in range(demo_data.vehicle_count)]
-
-    names = generate_names(random)
-    tomorrow = date.today() + timedelta(days=1)
+    if real_locations:
+        # Use real depot locations
+        depot_locations = real_locations["depots"]
+        vehicles = []
+        for i in range(demo_data.vehicle_count):
+            depot = depot_locations[i % len(depot_locations)]
+            vehicles.append(
+                Vehicle(
+                    id=str(i),
+                    name=VEHICLE_NAMES[i % len(VEHICLE_NAMES)],
+                    capacity=next(vehicle_capacities),
+                    home_location=Location(latitude=depot["lat"], longitude=depot["lng"]),
+                    departure_time=datetime.combine(
+                        date.today() + timedelta(days=1), demo_data.vehicle_start_time
+                    ),
+                )
+            )
+    else:
+        # Fallback to random locations within bounding box
+        latitudes = doubles(random, demo_data.south_west_corner.latitude, demo_data.north_east_corner.latitude)
+        longitudes = doubles(random, demo_data.south_west_corner.longitude, demo_data.north_east_corner.longitude)
+        vehicles = [
+            Vehicle(
+                id=str(i),
+                name=VEHICLE_NAMES[i % len(VEHICLE_NAMES)],
+                capacity=next(vehicle_capacities),
+                home_location=Location(latitude=next(latitudes), longitude=next(longitudes)),
+                departure_time=datetime.combine(
+                    date.today() + timedelta(days=1), demo_data.vehicle_start_time
+                ),
+            )
+            for i in range(demo_data.vehicle_count)
+        ]
 
+    tomorrow = date.today() + timedelta(days=1)
     visits = []
-    for i in range(demo_data.visit_count):
-        ctype = random_customer_type(random)
-        service_minutes = random.randint(ctype.min_service_minutes, ctype.max_service_minutes)
-        visits.append(
-            Visit(
-                id=str(i),
-                name=next(names),
-                location=Location(latitude=next(latitudes), longitude=next(longitudes)),
-                demand=random.randint(ctype.min_demand, ctype.max_demand),
-                min_start_time=datetime.combine(tomorrow, ctype.window_start),
-                max_end_time=datetime.combine(tomorrow, ctype.window_end),
-                service_duration=timedelta(minutes=service_minutes),
+
+    if real_locations:
+        # Use real visit locations with their actual types
+        visit_locations = real_locations["visits"]
+        # Shuffle to get variety, but use seed for reproducibility
+        shuffled_visits = list(visit_locations)
+        random.shuffle(shuffled_visits)
+
+        for i in range(min(demo_data.visit_count, len(shuffled_visits))):
+            loc_data = shuffled_visits[i]
+            # Get customer type from location data
+            ctype_name = loc_data.get("type", "RESIDENTIAL")
+            ctype = CustomerType[ctype_name]
+            service_minutes = random.randint(ctype.min_service_minutes, ctype.max_service_minutes)
+
+            visits.append(
+                Visit(
+                    id=str(i),
+                    name=loc_data["name"],
+                    location=Location(latitude=loc_data["lat"], longitude=loc_data["lng"]),
+                    demand=random.randint(ctype.min_demand, ctype.max_demand),
+                    min_start_time=datetime.combine(tomorrow, ctype.window_start),
+                    max_end_time=datetime.combine(tomorrow, ctype.window_end),
+                    service_duration=timedelta(minutes=service_minutes),
+                )
             )
-        )
 
-    # Handle driving time calculation mode
-    if use_precomputed_matrix:
-        # Pre-compute driving time matrix for faster solving
-        all_locations = [v.home_location for v in vehicles] + [v.location for v in visits]
-        init_driving_time_matrix(all_locations)
+        # If we need more visits than we have real locations, generate additional random ones
+        if demo_data.visit_count > len(shuffled_visits):
+            names = generate_names(random)
+            latitudes = doubles(random, demo_data.south_west_corner.latitude, demo_data.north_east_corner.latitude)
+            longitudes = doubles(random, demo_data.south_west_corner.longitude, demo_data.north_east_corner.longitude)
+
+            for i in range(len(shuffled_visits), demo_data.visit_count):
+                ctype = random_customer_type(random)
+                service_minutes = random.randint(ctype.min_service_minutes, ctype.max_service_minutes)
+                visits.append(
+                    Visit(
+                        id=str(i),
+                        name=next(names),
+                        location=Location(latitude=next(latitudes), longitude=next(longitudes)),
+                        demand=random.randint(ctype.min_demand, ctype.max_demand),
+                        min_start_time=datetime.combine(tomorrow, ctype.window_start),
+                        max_end_time=datetime.combine(tomorrow, ctype.window_end),
+                        service_duration=timedelta(minutes=service_minutes),
+                    )
+                )
     else:
-        # Clear any existing pre-computed matrix to ensure on-demand calculation
-        clear_driving_time_matrix()
-
-    return VehicleRoutePlan(name=name,
-                            south_west_corner=demo_data.south_west_corner,
-                            north_east_corner=demo_data.north_east_corner,
-                            vehicles=vehicles,
-                            visits=visits)
+        # Fallback to fully random locations
+        names = generate_names(random)
+        latitudes = doubles(random, demo_data.south_west_corner.latitude, demo_data.north_east_corner.latitude)
+        longitudes = doubles(random, demo_data.south_west_corner.longitude, demo_data.north_east_corner.longitude)
+
+        for i in range(demo_data.visit_count):
+            ctype = random_customer_type(random)
+            service_minutes = random.randint(ctype.min_service_minutes, ctype.max_service_minutes)
+            visits.append(
+                Visit(
+                    id=str(i),
+                    name=next(names),
+                    location=Location(latitude=next(latitudes), longitude=next(longitudes)),
+                    demand=random.randint(ctype.min_demand, ctype.max_demand),
+                    min_start_time=datetime.combine(tomorrow, ctype.window_start),
+                    max_end_time=datetime.combine(tomorrow, ctype.window_end),
+                    service_duration=timedelta(minutes=service_minutes),
+                )
+            )
+
+    return VehicleRoutePlan(
+        name=name,
+        south_west_corner=demo_data.south_west_corner,
+        north_east_corner=demo_data.north_east_corner,
+        vehicles=vehicles,
+        visits=visits,
+    )
 
 
 def tomorrow_at(local_time: time) -> datetime:

src/vehicle_routing/domain.py

@@ -15,21 +15,13 @@ from solverforge_legacy.solver.domain import (
 )
 
 from datetime import datetime, timedelta
-from typing import Annotated, Optional, List, Union
+from typing import Annotated, Optional, List, Union, ClassVar, TYPE_CHECKING
 from dataclasses import dataclass, field
 from .json_serialization import JsonDomainBase
 from pydantic import Field
 
-
-# Global driving time matrix for pre-computed mode
-# Key: (from_lat, from_lng, to_lat, to_lng) -> driving_time_seconds
-# This is kept outside the Location class to avoid transpiler issues with mutable fields
-_DRIVING_TIME_MATRIX: dict[tuple[float, float, float, float], int] = {}
-
-
-def _get_matrix_key(from_loc: "Location", to_loc: "Location") -> tuple[float, float, float, float]:
-    """Create a hashable key for the driving time matrix lookup."""
-    return (from_loc.latitude, from_loc.longitude, to_loc.latitude, to_loc.longitude)
+if TYPE_CHECKING:
+    from .routing import DistanceMatrix
 
 
 @dataclass
@@ -37,38 +29,46 @@ class Location:
     """
     Represents a geographic location with latitude and longitude.
 
-    Driving times can be calculated in two modes:
-    1. On-demand (default): Uses Haversine formula for each calculation
-    2. Pre-computed matrix: O(1) lookup from global pre-calculated distance matrix
-
-    The pre-computed mode is faster during solving (millions of lookups)
-    but requires O(n²) memory and one-time initialization cost.
-
-    To enable pre-computed mode, call init_driving_time_matrix() with all locations
-    before solving.
+    Driving times can be computed using either:
+    1. A precomputed distance matrix (if set) - uses real road network data
+    2. The Haversine formula (fallback) - uses great-circle distance
     """
     latitude: float
     longitude: float
 
+    # Class-level distance matrix (injected at problem load time)
+    _distance_matrix: ClassVar[Optional["DistanceMatrix"]] = None
+
     # Earth radius in meters
     _EARTH_RADIUS_M = 6371000
     _TWICE_EARTH_RADIUS_M = 2 * _EARTH_RADIUS_M
     # Average driving speed assumption: 50 km/h
     _AVERAGE_SPEED_KMPH = 50
 
+    @classmethod
+    def set_distance_matrix(cls, matrix: "DistanceMatrix") -> None:
+        """Inject a precomputed distance matrix for real road routing."""
+        cls._distance_matrix = matrix
+
+    @classmethod
+    def clear_distance_matrix(cls) -> None:
+        """Clear the distance matrix (reverts to haversine fallback)."""
+        cls._distance_matrix = None
+
+    @classmethod
+    def get_distance_matrix(cls) -> Optional["DistanceMatrix"]:
+        """Get the current distance matrix, if any."""
+        return cls._distance_matrix
+
     def driving_time_to(self, other: "Location") -> int:
         """
         Get driving time in seconds to another location.
 
-        If a pre-computed matrix is available (via init_driving_time_matrix),
-        uses O(1) lookup. Otherwise, calculates on-demand using Haversine formula.
+        Uses the precomputed distance matrix if available, otherwise
+        falls back to haversine calculation.
         """
-        # Use pre-computed matrix if available
-        key = _get_matrix_key(self, other)
-        if key in _DRIVING_TIME_MATRIX:
-            return _DRIVING_TIME_MATRIX[key]
-
-        # Fall back to on-demand calculation
+        if self._distance_matrix is not None:
+            return self._distance_matrix.get_driving_time(self, other)
         return self._calculate_driving_time_haversine(other)
 
     def _calculate_driving_time_haversine(self, other: "Location") -> int:
@@ -124,35 +124,6 @@ class Location:
         return f"Location({self.latitude}, {self.longitude})"
 
 
-def init_driving_time_matrix(locations: list[Location]) -> None:
-    """
-    Pre-compute driving times between all location pairs.
-
-    This trades O(n²) memory for O(1) lookup during solving.
-    For n=77 locations (FIRENZE), this is only 5,929 entries.
-
-    Call this once after creating all locations but before solving.
-    The matrix is stored globally and persists across solver runs.
-    """
-    global _DRIVING_TIME_MATRIX
-    _DRIVING_TIME_MATRIX = {}
-    for from_loc in locations:
-        for to_loc in locations:
-            key = _get_matrix_key(from_loc, to_loc)
-            _DRIVING_TIME_MATRIX[key] = from_loc._calculate_driving_time_haversine(to_loc)
-
-
-def clear_driving_time_matrix() -> None:
-    """Clear the pre-computed driving time matrix."""
-    global _DRIVING_TIME_MATRIX
-    _DRIVING_TIME_MATRIX = {}
-
-
-def is_driving_time_matrix_initialized() -> bool:
-    """Check if the driving time matrix has been pre-computed."""
-    return len(_DRIVING_TIME_MATRIX) > 0
-
-
 @planning_entity
 @dataclass
 class Visit:

src/vehicle_routing/rest_api.py

@@ -1,17 +1,31 @@
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException, Query
 from fastapi.staticfiles import StaticFiles
+from fastapi.responses import StreamingResponse
 from uuid import uuid4
-from typing import Dict, List
+from typing import Dict, List, Optional
 from dataclasses import asdict
+from enum import Enum
+import logging
+import json
+import asyncio
 
-from .domain import VehicleRoutePlan
+from .domain import VehicleRoutePlan, Location
 from .converters import plan_to_model, model_to_plan
 from .domain import VehicleRoutePlanModel
 from .score_analysis import ConstraintAnalysisDTO, MatchAnalysisDTO
 from .demo_data import generate_demo_data, DemoData
 from .solver import solver_manager, solution_manager
+from .routing import compute_distance_matrix_with_progress, DistanceMatrix
 from pydantic import BaseModel, Field
 
+
+class RoutingMode(str, Enum):
+    """Routing mode for distance calculations."""
+    HAVERSINE = "haversine"  # Fast, straight-line estimation
+    REAL_ROADS = "real_roads"  # Slower, uses OSMnx for real road routes
+
+logger = logging.getLogger(__name__)
+
 app = FastAPI(docs_url='/q/swagger-ui')
 
 data_sets: Dict[str, VehicleRoutePlan] = {}
@@ -67,25 +81,240 @@ async def get_demo_data():
     """Get available demo data sets."""
     return [demo.name for demo in DemoData]
 
+def _extract_all_locations(plan: VehicleRoutePlan) -> list[Location]:
+    """Extract all unique locations from a route plan."""
+    locations = []
+    seen = set()
+
+    for vehicle in plan.vehicles:
+        key = (vehicle.home_location.latitude, vehicle.home_location.longitude)
+        if key not in seen:
+            locations.append(vehicle.home_location)
+            seen.add(key)
+
+    for visit in plan.visits:
+        key = (visit.location.latitude, visit.location.longitude)
+        if key not in seen:
+            locations.append(visit.location)
+            seen.add(key)
+
+    return locations
+
+
+def _extract_route_geometries(plan: VehicleRoutePlan) -> Dict[str, List[Optional[str]]]:
+    """
+    Extract route geometries from the distance matrix for all vehicles.
+    Returns empty dict if no distance matrix is available.
+    """
+    distance_matrix = Location.get_distance_matrix()
+    if distance_matrix is None:
+        return {}
+
+    geometries: Dict[str, List[Optional[str]]] = {}
+
+    for vehicle in plan.vehicles:
+        segments: List[Optional[str]] = []
+
+        if not vehicle.visits:
+            geometries[vehicle.id] = segments
+            continue
+
+        # Segment from depot to first visit
+        prev_location = vehicle.home_location
+        for visit in vehicle.visits:
+            geometry = distance_matrix.get_geometry(prev_location, visit.location)
+            segments.append(geometry)
+            prev_location = visit.location
+
+        # Segment from last visit back to depot
+        geometry = distance_matrix.get_geometry(prev_location, vehicle.home_location)
+        segments.append(geometry)
+
+        geometries[vehicle.id] = segments
+
+    return geometries
+
+
+def _initialize_distance_matrix(
+    plan: VehicleRoutePlan,
+    use_real_roads: bool = False,
+    progress_callback=None
+) -> Optional[DistanceMatrix]:
+    """
+    Initialize the distance matrix for a route plan.
+
+    Args:
+        plan: The route plan with locations
+        use_real_roads: If True, use OSMnx for real road routing (slower)
+                       If False, use haversine estimation (fast, default)
+        progress_callback: Optional callback for progress updates
+
+    Returns the computed matrix, or None if routing failed.
+    """
+    locations = _extract_all_locations(plan)
+    if not locations:
+        return None
+
+    logger.info(f"Computing distance matrix for {len(locations)} locations (mode: {'real_roads' if use_real_roads else 'haversine'})...")
+
+    # Compute bounding box from the plan
+    bbox = (
+        plan.north_east_corner.latitude,
+        plan.south_west_corner.latitude,
+        plan.north_east_corner.longitude,
+        plan.south_west_corner.longitude,
+    )
+
+    try:
+        matrix = compute_distance_matrix_with_progress(
+            locations,
+            bbox=bbox,
+            use_osm=use_real_roads,
+            progress_callback=progress_callback
+        )
+        Location.set_distance_matrix(matrix)
+        logger.info("Distance matrix computed and set successfully")
+        return matrix
+    except Exception as e:
+        logger.warning(f"Failed to compute distance matrix: {e}")
+        return None
+
+
 @app.get("/demo-data/{demo_name}", response_model=VehicleRoutePlanModel)
-async def get_demo_data_by_name(demo_name: str, distanceMode: str = "ON_DEMAND") -> VehicleRoutePlanModel:
+async def get_demo_data_by_name(
+    demo_name: str,
+    routing: RoutingMode = Query(
+        default=RoutingMode.HAVERSINE,
+        description="Routing mode: 'haversine' (fast, default) or 'real_roads' (slower, accurate)"
+    )
+) -> VehicleRoutePlanModel:
     """
     Get a specific demo data set.
 
     Args:
         demo_name: Name of the demo dataset (PHILADELPHIA, HARTFORT, FIRENZE)
-        distanceMode: Distance calculation mode:
-            - ON_DEMAND: Calculate distances using Haversine formula on each call (default)
-            - PRECOMPUTED: Pre-compute distance matrix for O(1) lookups (faster solving)
+        routing: Routing mode - 'haversine' (fast default) or 'real_roads' (slower, accurate)
+
+    When routing=real_roads, computes the distance matrix using real road network
+    data (OSMnx) for accurate routing. The first call may take 5-15 seconds
+    to download the OSM network (cached for subsequent calls).
     """
     try:
         demo_data = DemoData[demo_name]
-        use_precomputed = distanceMode == "PRECOMPUTED"
-        domain_plan = generate_demo_data(demo_data, use_precomputed_matrix=use_precomputed)
+        domain_plan = generate_demo_data(demo_data)
+
+        # Initialize distance matrix with selected routing mode
+        use_real_roads = routing == RoutingMode.REAL_ROADS
+        _initialize_distance_matrix(domain_plan, use_real_roads=use_real_roads)
+
         return plan_to_model(domain_plan)
     except KeyError:
         raise HTTPException(status_code=404, detail=f"Demo data '{demo_name}' not found")
 
+
+# Progress tracking for SSE
+_progress_queues: Dict[str, asyncio.Queue] = {}
+
+
+@app.get("/demo-data/{demo_name}/stream")
+async def get_demo_data_with_progress(
+    demo_name: str,
+    routing: RoutingMode = Query(
+        default=RoutingMode.HAVERSINE,
+        description="Routing mode: 'haversine' (fast, default) or 'real_roads' (slower, accurate)"
+    )
+):
+    """
+    Get demo data with Server-Sent Events (SSE) progress updates.
+
+    This endpoint streams progress updates while computing the distance matrix,
+    then returns the final solution. Use this when routing=real_roads and you
+    want to show progress to the user.
+
+    Events emitted:
+    - progress: {phase, message, percent, detail}
+    - complete: {solution: VehicleRoutePlanModel}
+    - error: {message}
+    """
+    async def generate():
+        try:
+            demo_data = DemoData[demo_name]
+            domain_plan = generate_demo_data(demo_data)
+
+            use_real_roads = routing == RoutingMode.REAL_ROADS
+
+            if not use_real_roads:
+                # Fast path - no progress needed for haversine
+                yield f"data: {json.dumps({'event': 'progress', 'phase': 'computing', 'message': 'Computing distances...', 'percent': 50})}\n\n"
+                _initialize_distance_matrix(domain_plan, use_real_roads=False)
+                yield f"data: {json.dumps({'event': 'progress', 'phase': 'complete', 'message': 'Ready!', 'percent': 100})}\n\n"
+                result = plan_to_model(domain_plan)
+                # Include geometries (straight lines in haversine mode)
+                geometries = _extract_route_geometries(domain_plan)
+                yield f"data: {json.dumps({'event': 'complete', 'solution': result.model_dump(by_alias=True), 'geometries': geometries})}\n\n"
+            else:
+                # Slow path - stream progress for OSMnx
+                progress_events = []
+
+                def progress_callback(phase: str, message: str, percent: int, detail: str = ""):
+                    progress_events.append({
+                        'event': 'progress',
+                        'phase': phase,
+                        'message': message,
+                        'percent': percent,
+                        'detail': detail
+                    })
+
+                # Run computation in thread pool to not block
+                import concurrent.futures
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(
+                        _initialize_distance_matrix,
+                        domain_plan,
+                        use_real_roads=True,
+                        progress_callback=progress_callback
+                    )
+
+                    # Stream progress events while waiting
+                    last_sent = 0
+                    while not future.done():
+                        await asyncio.sleep(0.1)
+                        while last_sent < len(progress_events):
+                            yield f"data: {json.dumps(progress_events[last_sent])}\n\n"
+                            last_sent += 1
+
+                    # Send any remaining progress events
+                    while last_sent < len(progress_events):
+                        yield f"data: {json.dumps(progress_events[last_sent])}\n\n"
+                        last_sent += 1
+
+                    # Get result (will raise if exception occurred)
+                    future.result()
+
+                yield f"data: {json.dumps({'event': 'progress', 'phase': 'complete', 'message': 'Ready!', 'percent': 100})}\n\n"
+                result = plan_to_model(domain_plan)
+
+                # Include geometries in response for real roads mode
+                geometries = _extract_route_geometries(domain_plan)
+                yield f"data: {json.dumps({'event': 'complete', 'solution': result.model_dump(by_alias=True), 'geometries': geometries})}\n\n"
+
+        except KeyError:
+            yield f"data: {json.dumps({'event': 'error', 'message': f'Demo data not found: {demo_name}'})}\n\n"
+        except Exception as e:
+            logger.exception(f"Error in SSE stream: {e}")
+            yield f"data: {json.dumps({'event': 'error', 'message': str(e)})}\n\n"
+
+    return StreamingResponse(
+        generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no"
+        }
+    )
+
+
 @app.get("/route-plans/{problem_id}", response_model=VehicleRoutePlanModel, response_model_exclude_none=True)
 async def get_route(problem_id: str) -> VehicleRoutePlanModel:
     route = data_sets.get(problem_id)
@@ -238,4 +467,58 @@ async def apply_recommendation(request: ApplyRecommendationRequest) -> VehicleRo
     return plan_to_model(domain_plan)
 
 
+class RouteGeometryResponse(BaseModel):
+    """Response containing encoded polyline geometries for all vehicle routes."""
+    geometries: Dict[str, List[Optional[str]]]
+
+
+@app.get("/route-plans/{problem_id}/geometry", response_model=RouteGeometryResponse)
+async def get_route_geometry(problem_id: str) -> RouteGeometryResponse:
+    """
+    Get route geometries for all vehicle routes in a problem.
+
+    Returns encoded polylines (Google polyline format) for each route segment.
+    Each vehicle's route is represented as a list of encoded polylines:
+    - First segment: depot -> first visit
+    - Middle segments: visit -> visit
+    - Last segment: last visit -> depot
+
+    These can be decoded on the frontend to display actual road routes
+    instead of straight lines.
+    """
+    route = data_sets.get(problem_id)
+    if not route:
+        raise HTTPException(status_code=404, detail="Route plan not found")
+
+    distance_matrix = Location.get_distance_matrix()
+    if distance_matrix is None:
+        # No distance matrix available - return empty geometries
+        return RouteGeometryResponse(geometries={})
+
+    geometries: Dict[str, List[Optional[str]]] = {}
+
+    for vehicle in route.vehicles:
+        segments: List[Optional[str]] = []
+
+        if not vehicle.visits:
+            # No visits assigned to this vehicle
+            geometries[vehicle.id] = segments
+            continue
+
+        # Segment from depot to first visit
+        prev_location = vehicle.home_location
+        for visit in vehicle.visits:
+            geometry = distance_matrix.get_geometry(prev_location, visit.location)
+            segments.append(geometry)
+            prev_location = visit.location
+
+        # Segment from last visit back to depot
+        geometry = distance_matrix.get_geometry(prev_location, vehicle.home_location)
+        segments.append(geometry)
+
+        geometries[vehicle.id] = segments
+
+    return RouteGeometryResponse(geometries=geometries)
+
+
 app.mount("/", StaticFiles(directory="static", html=True), name="static")

src/vehicle_routing/routing.py

@@ -0,0 +1,622 @@
+"""
+Real-world routing service using OSMnx for road network data.
+
+This module provides:
+- OSMnxRoutingService: Downloads OSM network, caches locally, computes routes
+- DistanceMatrix: Precomputes all pairwise routes with times and geometries
+- Haversine fallback when OSMnx is unavailable
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+import polyline
+
+if TYPE_CHECKING:
+    from .domain import Location
+
+logger = logging.getLogger(__name__)
+
+# Cache directory for OSM network data
+CACHE_DIR = Path(__file__).parent.parent.parent / ".osm_cache"
+
+
+@dataclass
+class RouteResult:
+    """Result from a routing query."""
+
+    duration_seconds: int
+    distance_meters: int
+    geometry: Optional[str] = None  # Encoded polyline
+
+
+@dataclass
+class DistanceMatrix:
+    """
+    Precomputed distance/time matrix for all location pairs.
+
+    Stores RouteResult for each (origin, destination) pair,
+    enabling O(1) lookup during solver execution.
+    """
+
+    _matrix: dict[tuple[tuple[float, float], tuple[float, float]], RouteResult] = field(
+        default_factory=dict
+    )
+
+    def _key(
+        self, origin: "Location", destination: "Location"
+    ) -> tuple[tuple[float, float], tuple[float, float]]:
+        """Create hashable key from two locations."""
+        return (
+            (origin.latitude, origin.longitude),
+            (destination.latitude, destination.longitude),
+        )
+
+    def set_route(
+        self, origin: "Location", destination: "Location", result: RouteResult
+    ) -> None:
+        """Store a route result in the matrix."""
+        self._matrix[self._key(origin, destination)] = result
+
+    def get_route(
+        self, origin: "Location", destination: "Location"
+    ) -> Optional[RouteResult]:
+        """Get a route result from the matrix."""
+        return self._matrix.get(self._key(origin, destination))
+
+    def get_driving_time(self, origin: "Location", destination: "Location") -> int:
+        """Get driving time in seconds between two locations."""
+        result = self.get_route(origin, destination)
+        if result is None:
+            # Fallback to haversine if not in matrix
+            return _haversine_driving_time(origin, destination)
+        return result.duration_seconds
+
+    def get_geometry(
+        self, origin: "Location", destination: "Location"
+    ) -> Optional[str]:
+        """Get encoded polyline geometry for a route segment."""
+        result = self.get_route(origin, destination)
+        return result.geometry if result else None
+
+
+def _haversine_driving_time(origin: "Location", destination: "Location") -> int:
+    """
+    Calculate driving time using haversine formula (fallback).
+
+    Uses 50 km/h average speed assumption.
+    """
+    if (
+        origin.latitude == destination.latitude
+        and origin.longitude == destination.longitude
+    ):
+        return 0
+
+    EARTH_RADIUS_M = 6371000
+    AVERAGE_SPEED_KMPH = 50
+
+    lat1 = math.radians(origin.latitude)
+    lon1 = math.radians(origin.longitude)
+    lat2 = math.radians(destination.latitude)
+    lon2 = math.radians(destination.longitude)
+
+    # Haversine formula
+    dlat = lat2 - lat1
+    dlon = lon2 - lon1
+    a = math.sin(dlat / 2) ** 2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2) ** 2
+    c = 2 * math.asin(math.sqrt(a))
+    distance_meters = EARTH_RADIUS_M * c
+
+    # Convert to driving time
+    return round(distance_meters / AVERAGE_SPEED_KMPH * 3.6)
+
+
+class OSMnxRoutingService:
+    """
+    Routing service using OSMnx for real road network data.
+
+    Downloads the OSM network for a given bounding box, caches it locally,
+    and computes shortest paths using NetworkX.
+    """
+
+    def __init__(self, cache_dir: Path = CACHE_DIR):
+        self.cache_dir = cache_dir
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self._graph = None
+        self._graph_bbox = None
+
+    def _get_cache_path(
+        self, north: float, south: float, east: float, west: float
+    ) -> Path:
+        """Generate cache file path for a bounding box."""
+        # Round to 2 decimal places for cache key
+        key = f"osm_{north:.2f}_{south:.2f}_{east:.2f}_{west:.2f}.graphml"
+        return self.cache_dir / key
+
+    def load_network(
+        self, north: float, south: float, east: float, west: float, padding: float = 0.01
+    ) -> bool:
+        """
+        Load OSM road network for the given bounding box.
+
+        Args:
+            north, south, east, west: Bounding box coordinates
+            padding: Extra padding around the bbox (in degrees)
+
+        Returns:
+            True if network loaded successfully, False otherwise
+        """
+        try:
+            import osmnx as ox
+
+            # Add padding to ensure we have roads outside the strict bbox
+            north += padding
+            south -= padding
+            east += padding
+            west -= padding
+
+            cache_path = self._get_cache_path(north, south, east, west)
+
+            if cache_path.exists() and cache_path.stat().st_size > 0:
+                logger.info(f"Loading cached OSM network from {cache_path}")
+                self._graph = ox.load_graphml(cache_path)
+
+                # Check if the cached graph already has travel_time
+                # (we now save enriched graphs)
+                sample_edge = next(iter(self._graph.edges(data=True)), None)
+                has_travel_time = sample_edge and "travel_time" in sample_edge[2]
+
+                if not has_travel_time:
+                    logger.info("Adding edge speeds and travel times to cached graph...")
+                    self._graph = ox.add_edge_speeds(self._graph)
+                    self._graph = ox.add_edge_travel_times(self._graph)
+                    # Re-save with travel times included
+                    ox.save_graphml(self._graph, cache_path)
+                    logger.info("Updated cache with travel times")
+            else:
+                logger.info(
+                    f"Downloading OSM network for bbox: N={north:.4f}, S={south:.4f}, E={east:.4f}, W={west:.4f}"
+                )
+                # OSMnx 2.x uses bbox as tuple: (left, bottom, right, top) = (west, south, east, north)
+                bbox_tuple = (west, south, east, north)
+                self._graph = ox.graph_from_bbox(
+                    bbox=bbox_tuple,
+                    network_type="drive",
+                    simplify=True,
+                )
+
+                # Add edge speeds and travel times BEFORE caching
+                logger.info("Computing edge speeds and travel times...")
+                self._graph = ox.add_edge_speeds(self._graph)
+                self._graph = ox.add_edge_travel_times(self._graph)
+
+                # Save enriched graph to cache
+                ox.save_graphml(self._graph, cache_path)
+                logger.info(f"Saved enriched OSM network to cache: {cache_path}")
+
+            self._graph_bbox = (north, south, east, west)
+            logger.info(
+                f"OSM network loaded: {self._graph.number_of_nodes()} nodes, "
+                f"{self._graph.number_of_edges()} edges"
+            )
+            return True
+
+        except ImportError:
+            logger.warning("OSMnx not installed, falling back to haversine")
+            return False
+        except Exception as e:
+            logger.warning(f"Failed to load OSM network: {e}, falling back to haversine")
+            return False
+
+    def get_nearest_node(self, location: "Location") -> Optional[int]:
+        """Get the nearest graph node for a location."""
+        if self._graph is None:
+            return None
+        try:
+            import osmnx as ox
+            return ox.nearest_nodes(self._graph, location.longitude, location.latitude)
+        except Exception:
+            return None
+
+    def compute_all_routes(
+        self,
+        locations: list["Location"],
+        progress_callback=None
+    ) -> dict[tuple[int, int], RouteResult]:
+        """
+        Compute all pairwise routes efficiently using batch shortest paths.
+
+        Returns a dict mapping (origin_idx, dest_idx) to RouteResult.
+        """
+        import networkx as nx
+
+        if self._graph is None:
+            return {}
+
+        results = {}
+        n = len(locations)
+
+        # Map locations to nearest nodes (batch operation)
+        if progress_callback:
+            progress_callback("routes", "Finding nearest road nodes...", 30, f"{n} locations")
+
+        nodes = []
+        for loc in locations:
+            node = self.get_nearest_node(loc)
+            nodes.append(node)
+
+        # Compute shortest paths from each origin to ALL destinations at once
+        # This is MUCH faster than individual shortest_path calls
+        total_origins = sum(1 for node in nodes if node is not None)
+        processed = 0
+
+        for i, origin_node in enumerate(nodes):
+            if origin_node is None:
+                continue
+
+            # Compute shortest paths from this origin to all nodes at once
+            # Using Dijkstra's algorithm with single-source
+            try:
+                lengths, paths = nx.single_source_dijkstra(
+                    self._graph, origin_node, weight="travel_time"
+                )
+            except nx.NetworkXError:
+                continue
+
+            for j, dest_node in enumerate(nodes):
+                if dest_node is None:
+                    continue
+
+                origin_loc = locations[i]
+                dest_loc = locations[j]
+
+                if i == j or origin_node == dest_node:
+                    # Same location
+                    results[(i, j)] = RouteResult(
+                        duration_seconds=0,
+                        distance_meters=0,
+                        geometry=polyline.encode(
+                            [(origin_loc.latitude, origin_loc.longitude)], precision=5
+                        ),
+                    )
+                elif dest_node in paths:
+                    path = paths[dest_node]
+                    travel_time = lengths[dest_node]
+
+                    # Calculate distance and extract geometry
+                    total_distance = 0
+                    coordinates = []
+
+                    for k in range(len(path) - 1):
+                        u, v = path[k], path[k + 1]
+                        edge_data = self._graph.get_edge_data(u, v)
+                        if edge_data:
+                            edge = edge_data[0] if isinstance(edge_data, dict) else edge_data
+                            total_distance += edge.get("length", 0)
+
+                    for node in path:
+                        node_data = self._graph.nodes[node]
+                        coordinates.append((node_data["y"], node_data["x"]))
+
+                    results[(i, j)] = RouteResult(
+                        duration_seconds=round(travel_time),
+                        distance_meters=round(total_distance),
+                        geometry=polyline.encode(coordinates, precision=5),
+                    )
+
+            processed += 1
+            if progress_callback and processed % max(1, total_origins // 10) == 0:
+                percent = 30 + int((processed / total_origins) * 65)
+                progress_callback(
+                    "routes",
+                    "Computing routes...",
+                    percent,
+                    f"{processed}/{total_origins} origins processed"
+                )
+
+        return results
+
+    def get_route(
+        self, origin: "Location", destination: "Location"
+    ) -> Optional[RouteResult]:
+        """
+        Compute route between two locations.
+
+        Returns:
+            RouteResult with duration, distance, and geometry, or None if routing fails
+        """
+        if self._graph is None:
+            return None
+
+        try:
+            import osmnx as ox
+
+            # Find nearest nodes to origin and destination
+            origin_node = ox.nearest_nodes(
+                self._graph, origin.longitude, origin.latitude
+            )
+            dest_node = ox.nearest_nodes(
+                self._graph, destination.longitude, destination.latitude
+            )
+
+            # Same node means same location (or very close)
+            if origin_node == dest_node:
+                return RouteResult(
+                    duration_seconds=0,
+                    distance_meters=0,
+                    geometry=polyline.encode(
+                        [(origin.latitude, origin.longitude)], precision=5
+                    ),
+                )
+
+            # Compute shortest path by travel time
+            route = ox.shortest_path(
+                self._graph, origin_node, dest_node, weight="travel_time"
+            )
+
+            if route is None:
+                logger.warning(
+                    f"No route found between {origin} and {destination}"
+                )
+                return None
+
+            # Extract route attributes
+            total_time = 0
+            total_distance = 0
+            coordinates = []
+
+            for i in range(len(route) - 1):
+                u, v = route[i], route[i + 1]
+                edge_data = self._graph.get_edge_data(u, v)
+                if edge_data:
+                    # Get the first edge if multiple exist
+                    edge = edge_data[0] if isinstance(edge_data, dict) else edge_data
+                    total_time += edge.get("travel_time", 0)
+                    total_distance += edge.get("length", 0)
+
+            # Get node coordinates for geometry
+            for node in route:
+                node_data = self._graph.nodes[node]
+                coordinates.append((node_data["y"], node_data["x"]))
+
+            # Encode geometry as polyline
+            encoded_geometry = polyline.encode(coordinates, precision=5)
+
+            return RouteResult(
+                duration_seconds=round(total_time),
+                distance_meters=round(total_distance),
+                geometry=encoded_geometry,
+            )
+
+        except Exception as e:
+            logger.warning(f"Routing failed: {e}")
+            return None
+
+
+def compute_distance_matrix(
+    locations: list["Location"],
+    routing_service: Optional[OSMnxRoutingService] = None,
+    bbox: Optional[tuple[float, float, float, float]] = None,
+) -> DistanceMatrix:
+    """
+    Compute distance matrix for all location pairs.
+
+    Args:
+        locations: List of Location objects
+        routing_service: Optional pre-configured routing service
+        bbox: Optional (north, south, east, west) tuple for network download
+
+    Returns:
+        DistanceMatrix with precomputed routes
+    """
+    return compute_distance_matrix_with_progress(
+        locations, routing_service, bbox, use_osm=True, progress_callback=None
+    )
+
+
+def compute_distance_matrix_with_progress(
+    locations: list["Location"],
+    bbox: Optional[tuple[float, float, float, float]] = None,
+    use_osm: bool = True,
+    progress_callback=None,
+    routing_service: Optional[OSMnxRoutingService] = None,
+) -> DistanceMatrix:
+    """
+    Compute distance matrix for all location pairs with progress reporting.
+
+    Args:
+        locations: List of Location objects
+        bbox: Optional (north, south, east, west) tuple for network download
+        use_osm: If True, try to use OSMnx for real routing. If False, use haversine.
+        progress_callback: Optional callback(phase, message, percent, detail) for progress updates
+        routing_service: Optional pre-configured routing service
+
+    Returns:
+        DistanceMatrix with precomputed routes
+    """
+    matrix = DistanceMatrix()
+
+    if not locations:
+        return matrix
+
+    def report_progress(phase: str, message: str, percent: int, detail: str = ""):
+        if progress_callback:
+            progress_callback(phase, message, percent, detail)
+        logger.info(f"[{phase}] {message} ({percent}%) {detail}")
+
+    # Compute bounding box from locations if not provided
+    if bbox is None:
+        lats = [loc.latitude for loc in locations]
+        lons = [loc.longitude for loc in locations]
+        bbox = (max(lats), min(lats), max(lons), min(lons))
+
+    osm_loaded = False
+
+    if use_osm:
+        # Create routing service if not provided
+        if routing_service is None:
+            routing_service = OSMnxRoutingService()
+
+        report_progress("network", "Checking for cached road network...", 5)
+
+        # Check if cached
+        north, south, east, west = bbox
+        north += 0.01  # padding
+        south -= 0.01
+        east += 0.01
+        west -= 0.01
+
+        cache_path = routing_service._get_cache_path(north, south, east, west)
+        is_cached = cache_path.exists()
+
+        if is_cached:
+            report_progress("network", "Loading cached road network...", 10, str(cache_path.name))
+        else:
+            report_progress(
+                "network",
+                "Downloading OpenStreetMap road network...",
+                10,
+                f"Area: {abs(north-south):.2f}° × {abs(east-west):.2f}°"
+            )
+
+        # Try to load OSM network
+        osm_loaded = routing_service.load_network(
+            north=bbox[0], south=bbox[1], east=bbox[2], west=bbox[3]
+        )
+
+        if osm_loaded:
+            node_count = routing_service._graph.number_of_nodes()
+            edge_count = routing_service._graph.number_of_edges()
+            report_progress(
+                "network",
+                "Road network loaded",
+                25,
+                f"{node_count:,} nodes, {edge_count:,} edges"
+            )
+        else:
+            report_progress("network", "OSMnx unavailable, using haversine", 25)
+    else:
+        report_progress("network", "Using fast haversine mode", 25)
+
+    # Compute all pairwise routes
+    total_pairs = len(locations) * len(locations)
+
+    if osm_loaded and routing_service:
+        # Use batch routing for OSMnx (MUCH faster than individual calls)
+        report_progress(
+            "routes",
+            f"Computing {total_pairs:,} routes (batch mode)...",
+            30,
+            f"{len(locations)} locations"
+        )
+
+        batch_results = routing_service.compute_all_routes(
+            locations,
+            progress_callback=report_progress
+        )
+
+        # Transfer batch results to matrix, with haversine fallback for missing routes
+        computed = 0
+        for i, origin in enumerate(locations):
+            for j, destination in enumerate(locations):
+                if (i, j) in batch_results:
+                    matrix.set_route(origin, destination, batch_results[(i, j)])
+                else:
+                    # Fallback to haversine for routes not found
+                    matrix.set_route(
+                        origin,
+                        destination,
+                        RouteResult(
+                            duration_seconds=_haversine_driving_time(origin, destination),
+                            distance_meters=_haversine_distance_meters(origin, destination),
+                            geometry=_straight_line_geometry(origin, destination),
+                        ),
+                    )
+                computed += 1
+
+        report_progress("complete", "Distance matrix ready", 100, f"{computed:,} routes computed")
+    else:
+        # Use haversine fallback for all routes
+        report_progress(
+            "routes",
+            f"Computing {total_pairs:,} route pairs...",
+            30,
+            f"{len(locations)} locations"
+        )
+
+        computed = 0
+        for origin in locations:
+            for destination in locations:
+                if origin is destination:
+                    matrix.set_route(
+                        origin,
+                        destination,
+                        RouteResult(
+                            duration_seconds=0,
+                            distance_meters=0,
+                            geometry=polyline.encode(
+                                [(origin.latitude, origin.longitude)], precision=5
+                            ),
+                        ),
+                    )
+                else:
+                    matrix.set_route(
+                        origin,
+                        destination,
+                        RouteResult(
+                            duration_seconds=_haversine_driving_time(origin, destination),
+                            distance_meters=_haversine_distance_meters(origin, destination),
+                            geometry=_straight_line_geometry(origin, destination),
+                        ),
+                    )
+                computed += 1
+
+                # Report progress every 5%
+                if total_pairs > 0 and computed % max(1, total_pairs // 20) == 0:
+                    percent_complete = int(30 + (computed / total_pairs) * 65)
+                    report_progress(
+                        "routes",
+                        f"Computing routes...",
+                        percent_complete,
+                        f"{computed:,}/{total_pairs:,} pairs"
+                    )
+
+        report_progress("complete", "Distance matrix ready", 100, f"{computed:,} routes computed")
+
+    return matrix
+
+
+def _haversine_distance_meters(origin: "Location", destination: "Location") -> int:
+    """Calculate haversine distance in meters."""
+    if (
+        origin.latitude == destination.latitude
+        and origin.longitude == destination.longitude
+    ):
+        return 0
+
+    EARTH_RADIUS_M = 6371000
+
+    lat1 = math.radians(origin.latitude)
+    lon1 = math.radians(origin.longitude)
+    lat2 = math.radians(destination.latitude)
+    lon2 = math.radians(destination.longitude)
+
+    dlat = lat2 - lat1
+    dlon = lon2 - lon1
+    a = math.sin(dlat / 2) ** 2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2) ** 2
+    c = 2 * math.asin(math.sqrt(a))
+
+    return round(EARTH_RADIUS_M * c)
+
+
+def _straight_line_geometry(origin: "Location", destination: "Location") -> str:
+    """Generate a straight-line encoded polyline between two points."""
+    return polyline.encode(
+        [(origin.latitude, origin.longitude), (destination.latitude, destination.longitude)],
+        precision=5,
+    )

static/app.js

@@ -6,11 +6,155 @@ let scheduleId = null;
 let loadedRoutePlan = null;
 let newVisit = null;
 let visitMarker = null;
+let routeGeometries = null;  // Cache for encoded polyline geometries
+let useRealRoads = false;    // Routing mode toggle state
 const solveButton = $("#solveButton");
 const stopSolvingButton = $("#stopSolvingButton");
 const vehiclesTable = $("#vehicles");
 const analyzeButton = $("#analyzeButton");
 
+/**
+ * Decode an encoded polyline string into an array of [lat, lng] coordinates.
+ * This is the Google polyline encoding algorithm.
+ * @param {string} encoded - The encoded polyline string
+ * @returns {Array<Array<number>>} Array of [lat, lng] coordinate pairs
+ */
+function decodePolyline(encoded) {
+  if (!encoded) return [];
+
+  const points = [];
+  let index = 0;
+  let lat = 0;
+  let lng = 0;
+
+  while (index < encoded.length) {
+    // Decode latitude
+    let shift = 0;
+    let result = 0;
+    let byte;
+    do {
+      byte = encoded.charCodeAt(index++) - 63;
+      result |= (byte & 0x1f) << shift;
+      shift += 5;
+    } while (byte >= 0x20);
+    const dlat = (result & 1) ? ~(result >> 1) : (result >> 1);
+    lat += dlat;
+
+    // Decode longitude
+    shift = 0;
+    result = 0;
+    do {
+      byte = encoded.charCodeAt(index++) - 63;
+      result |= (byte & 0x1f) << shift;
+      shift += 5;
+    } while (byte >= 0x20);
+    const dlng = (result & 1) ? ~(result >> 1) : (result >> 1);
+    lng += dlng;
+
+    // Polyline encoding uses precision of 5 decimal places
+    points.push([lat / 1e5, lng / 1e5]);
+  }
+
+  return points;
+}
+
+/**
+ * Fetch route geometries for the current schedule from the backend.
+ * @returns {Promise<Object|null>} The geometries object or null if unavailable
+ */
+async function fetchRouteGeometries() {
+  if (!scheduleId) return null;
+
+  try {
+    const response = await fetch(`/route-plans/${scheduleId}/geometry`);
+    if (response.ok) {
+      const data = await response.json();
+      return data.geometries || null;
+    }
+  } catch (e) {
+    console.warn('Could not fetch route geometries:', e);
+  }
+  return null;
+}
+
+/*************************************** Loading Overlay Functions **************************************/
+
+function showLoadingOverlay(title = "Loading Demo Data", message = "Initializing...") {
+  $("#loadingTitle").text(title);
+  $("#loadingMessage").text(message);
+  $("#loadingProgress").css("width", "0%");
+  $("#loadingDetail").text("");
+  $("#loadingOverlay").removeClass("hidden");
+}
+
+function hideLoadingOverlay() {
+  $("#loadingOverlay").addClass("hidden");
+}
+
+function updateLoadingProgress(message, percent, detail = "") {
+  $("#loadingMessage").text(message);
+  $("#loadingProgress").css("width", `${percent}%`);
+  $("#loadingDetail").text(detail);
+}
+
+/**
+ * Load demo data with progress updates via Server-Sent Events.
+ * Used when Real Roads mode is enabled.
+ */
+function loadDemoDataWithProgress(demoId) {
+  return new Promise((resolve, reject) => {
+    const routingMode = useRealRoads ? "real_roads" : "haversine";
+    const url = `/demo-data/${demoId}/stream?routing=${routingMode}`;
+
+    showLoadingOverlay(
+      useRealRoads ? "Loading Real Road Data" : "Loading Demo Data",
+      "Connecting..."
+    );
+
+    const eventSource = new EventSource(url);
+    let solution = null;
+
+    eventSource.onmessage = function(event) {
+      try {
+        const data = JSON.parse(event.data);
+
+        if (data.event === "progress") {
+          let statusIcon = "";
+          if (data.phase === "network") {
+            statusIcon = '<i class="fas fa-download me-2"></i>';
+          } else if (data.phase === "routes") {
+            statusIcon = '<i class="fas fa-route me-2"></i>';
+          } else if (data.phase === "complete") {
+            statusIcon = '<i class="fas fa-check-circle me-2 text-success"></i>';
+          }
+          updateLoadingProgress(data.message, data.percent, data.detail || "");
+        } else if (data.event === "complete") {
+          solution = data.solution;
+          // Store geometries from the response if available
+          if (data.geometries) {
+            routeGeometries = data.geometries;
+          }
+          eventSource.close();
+          hideLoadingOverlay();
+          resolve(solution);
+        } else if (data.event === "error") {
+          eventSource.close();
+          hideLoadingOverlay();
+          reject(new Error(data.message));
+        }
+      } catch (e) {
+        console.error("Error parsing SSE event:", e);
+      }
+    };
+
+    eventSource.onerror = function(error) {
+      eventSource.close();
+      hideLoadingOverlay();
+      reject(new Error("Connection lost while loading data"));
+    };
+  });
+}
+
 /*************************************** Map constants and variable definitions  **************************************/
 
 const homeLocationMarkerByIdMap = new Map();
@@ -155,6 +299,23 @@ $(document).ready(function () {
     }
   });
 
+  // Real Roads toggle handler
+  $(document).on('change', '#realRoadRouting', function() {
+    useRealRoads = $(this).is(':checked');
+
+    // If we have a demo dataset loaded, reload it with the new routing mode
+    if (demoDataId && !optimizing) {
+      scheduleId = null;
+      initialized = false;
+      homeLocationGroup.clearLayers();
+      homeLocationMarkerByIdMap.clear();
+      visitGroup.clearLayers();
+      visitMarkerByIdMap.clear();
+      routeGeometries = null;
+      refreshRoutePlan();
+    }
+  });
+
   setupAjax();
   fetchDemoData();
 });
@@ -265,7 +426,7 @@ function getNextVehicleName() {
   return `Vehicle ${loadedRoutePlan.vehicles.length + 1}`;
 }
 
-function confirmAddVehicle() {
+async function confirmAddVehicle() {
   const vehicleName = $("#vehicleName").val().trim() || getNextVehicleName();
   const capacity = parseInt($("#vehicleCapacity").val());
   const lat = parseFloat($("#vehicleHomeLat").val());
@@ -321,13 +482,13 @@ function confirmAddVehicle() {
   }
 
   // Refresh display
-  renderRoutes(loadedRoutePlan);
+  await renderRoutes(loadedRoutePlan);
   renderTimelines(loadedRoutePlan);
 
   showNotification(`Vehicle "${vehicleName}" added successfully!`, "success");
 }
 
-function removeLastVehicle() {
+async function removeLastVehicle() {
   if (optimizing) {
     alert("Cannot remove vehicles while solving. Please stop solving first.");
     return;
@@ -367,13 +528,13 @@ function removeLastVehicle() {
   }
 
   // Refresh display
-  renderRoutes(loadedRoutePlan);
+  await renderRoutes(loadedRoutePlan);
   renderTimelines(loadedRoutePlan);
 
   showNotification(`Vehicle "${lastVehicle.name || lastVehicle.id}" removed.`, "info");
 }
 
-function removeVehicle(vehicleId) {
+async function removeVehicle(vehicleId) {
   if (optimizing) {
     alert("Cannot remove vehicles while solving. Please stop solving first.");
     return;
@@ -417,7 +578,7 @@ function removeVehicle(vehicleId) {
   }
 
   // Refresh display
-  renderRoutes(loadedRoutePlan);
+  await renderRoutes(loadedRoutePlan);
   renderTimelines(loadedRoutePlan);
 
   showNotification(`Vehicle "${vehicle.name || vehicleId}" removed.`, "info");
@@ -596,11 +757,16 @@ function createRouteNumberIcon(number, color) {
   });
 }
 
-function renderRouteLines(highlightedId = null) {
+async function renderRouteLines(highlightedId = null) {
   routeGroup.clearLayers();
 
   if (!loadedRoutePlan) return;
 
+  // Fetch geometries during solving (routes change)
+  if (scheduleId) {
+    routeGeometries = await fetchRouteGeometries();
+  }
+
   const visitByIdMap = new Map(loadedRoutePlan.visits.map(visit => [visit.id, visit]));
 
   for (let vehicle of loadedRoutePlan.vehicles) {
@@ -612,7 +778,24 @@ function renderRouteLines(highlightedId = null) {
     const weight = isHighlighted && highlightedId !== null ? 5 : 3;
     const opacity = isHighlighted ? 1 : 0.2;
 
-    if (locations.length > 0) {
+    const vehicleGeometry = routeGeometries?.[vehicle.id];
+
+    if (vehicleGeometry && vehicleGeometry.length > 0) {
+      // Draw real road routes using decoded polylines
+      for (const encodedSegment of vehicleGeometry) {
+        if (encodedSegment) {
+          const points = decodePolyline(encodedSegment);
+          if (points.length > 0) {
+            L.polyline(points, {
+              color: color,
+              weight: weight,
+              opacity: opacity
+            }).addTo(routeGroup);
+          }
+        }
+      }
+    } else if (locations.length > 0) {
+      // Fallback to straight lines if no geometry available
       L.polyline([homeLocation, ...locations, homeLocation], {
         color: color,
         weight: weight,
@@ -773,7 +956,7 @@ function getVisitMarker(visit) {
   return marker;
 }
 
-function renderRoutes(solution) {
+async function renderRoutes(solution) {
   if (!initialized) {
     const bounds = [solution.southWestCorner, solution.northEastCorner];
     map.fitBounds(bounds);
@@ -827,8 +1010,8 @@ function renderRoutes(solution) {
   solution.visits.forEach(function (visit) {
     getVisitMarker(visit).setPopupContent(visitPopupContent(visit));
   });
-  // Route - use the dedicated function which handles highlighting
-  renderRouteLines(highlightedVehicleId);
+  // Route - use the dedicated function which handles highlighting (await to ensure geometries load)
+  await renderRouteLines(highlightedVehicleId);
 
   // Summary
   $("#score").text(solution.score ? `Score: ${solution.score}` : "Score: ?");
@@ -841,7 +1024,7 @@ function renderTimelines(routePlan) {
   byVehicleItemData.clear();
   byVisitItemData.clear();
 
-  // Build lookup maps for enhanced display
+  // Build lookup maps for O(1) access
   const vehicleById = new Map(routePlan.vehicles.map(v => [v.id, v]));
   const visitById = new Map(routePlan.visits.map(v => [v.id, v]));
   const visitOrderMap = new Map();
@@ -1162,9 +1345,9 @@ function applyRecommendationModal(recommendations) {
   );
 }
 
-function updateSolutionWithNewVisit(newSolution) {
+async function updateSolutionWithNewVisit(newSolution) {
   loadedRoutePlan = newSolution;
-  renderRoutes(newSolution);
+  await renderRoutes(newSolution);
   renderTimelines(newSolution);
   $('#newVisitModal').modal('hide');
 }
@@ -1199,6 +1382,9 @@ function setupAjax() {
 }
 
 function solve() {
+  // Clear geometry cache - will be refreshed when solution updates
+  routeGeometries = null;
+
   $.ajax({
     url: "/route-plans",
     type: "POST",
@@ -1240,30 +1426,52 @@ function refreshSolvingButtons(solving) {
   }
 }
 
-function refreshRoutePlan() {
+async function refreshRoutePlan() {
   let path = "/route-plans/" + scheduleId;
-  if (scheduleId === null) {
+  let isLoadingDemoData = scheduleId === null;
+
+  if (isLoadingDemoData) {
     if (demoDataId === null) {
       alert("Please select a test data set.");
       return;
     }
 
-    path = "/demo-data/" + demoDataId;
+    // Clear geometry cache when loading new demo data
+    routeGeometries = null;
+
+    // Use SSE streaming for demo data loading to show progress
+    try {
+      const routePlan = await loadDemoDataWithProgress(demoDataId);
+      loadedRoutePlan = routePlan;
+      refreshSolvingButtons(
+        routePlan.solverStatus != null &&
+          routePlan.solverStatus !== "NOT_SOLVING",
+      );
+      await renderRoutes(routePlan);
+      renderTimelines(routePlan);
+      initialized = true;
+    } catch (error) {
+      showError("Getting demo data has failed: " + error.message, {});
+      refreshSolvingButtons(false);
+    }
+    return;
   }
 
-  $.getJSON(path, function (routePlan) {
+  // Loading existing route plan (during solving)
+  try {
+    const routePlan = await $.getJSON(path);
     loadedRoutePlan = routePlan;
     refreshSolvingButtons(
       routePlan.solverStatus != null &&
         routePlan.solverStatus !== "NOT_SOLVING",
     );
-    renderRoutes(routePlan);
+    await renderRoutes(routePlan);
     renderTimelines(routePlan);
     initialized = true;
-  }).fail(function (xhr, ajaxOptions, thrownError) {
-    showError("Getting route plan has failed.", xhr);
+  } catch (error) {
+    showError("Getting route plan has failed.", error);
     refreshSolvingButtons(false);
-  });
+  }
 }
 
 function stopSolving() {
@@ -1360,6 +1568,12 @@ function replaceQuickstartSolverForgeAutoHeaderFooter() {
             </ul>
           </div>
           <div class="ms-auto d-flex align-items-center gap-3">
+              <div class="form-check form-switch d-flex align-items-center" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Enable real road routing using OpenStreetMap data. Slower initial load (~5-15s for download), but shows accurate road routes instead of straight lines.">
+                  <input class="form-check-input" type="checkbox" id="realRoadRouting" style="width: 2.5em; height: 1.25em; cursor: pointer;">
+                  <label class="form-check-label ms-2" for="realRoadRouting" style="white-space: nowrap; cursor: pointer;">
+                      <i class="fas fa-road"></i> Real Roads
+                  </label>
+              </div>
               <div class="dropdown">
                   <button class="btn dropdown-toggle" type="button" id="dropdownMenuButton" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false" style="background-color: #10b981; color: #ffffff; border-color: #10b981;">
                       Data

static/index.html

@@ -111,7 +111,7 @@
       opacity: 0;
     }
 
-    /* Timeline enhancements */
+    /* Timeline stop badges */
     .timeline-stop-badge {
       background-color: #6366f1;
       color: white;
@@ -135,6 +135,47 @@
     .vis-labelset .vis-label {
       padding: 4px 8px;
     }
+
+    /* Loading overlay */
+    .loading-overlay {
+      position: fixed;
+      top: 0;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      background: rgba(255, 255, 255, 0.95);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      z-index: 2000;
+      transition: opacity 0.3s ease;
+    }
+    .loading-overlay.hidden {
+      opacity: 0;
+      pointer-events: none;
+    }
+    .loading-content {
+      text-align: center;
+      padding: 2rem;
+    }
+    .loading-spinner {
+      width: 60px;
+      height: 60px;
+      border: 4px solid #e5e7eb;
+      border-top-color: #10b981;
+      border-radius: 50%;
+      animation: spin 1s linear infinite;
+      margin: 0 auto 1.5rem;
+    }
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    /* Real Roads toggle styling */
+    #realRoadRouting:checked {
+      background-color: #10b981;
+      border-color: #10b981;
+    }
   </style>
 </head>
 <body>
@@ -400,6 +441,19 @@
   </div>
 </div>
 
+<!-- Loading/Progress Overlay -->
+<div id="loadingOverlay" class="loading-overlay hidden">
+  <div class="loading-content">
+    <div class="loading-spinner"></div>
+    <h5 id="loadingTitle">Loading Demo Data</h5>
+    <p id="loadingMessage" class="text-muted mb-2">Initializing...</p>
+    <div class="progress" style="width: 300px; height: 8px;">
+      <div id="loadingProgress" class="progress-bar progress-bar-striped progress-bar-animated" role="progressbar" style="width: 0%"></div>
+    </div>
+    <small id="loadingDetail" class="text-muted mt-2 d-block"></small>
+  </div>
+</div>
+
 <footer id="solverforge-auto-footer"></footer>
 
 <script src="https://cdnjs.cloudflare.com/ajax/libs/flatpickr/4.6.13/flatpickr.min.js"></script>

tests/.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

tests/.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

tests/.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

tests/.pytest_cache/v/cache/lastfailed

@@ -0,0 +1,4 @@
+{
+  "test_constraints.py": true,
+  "test_feasible.py": true
+}

tests/.pytest_cache/v/cache/nodeids

@@ -0,0 +1 @@
+[]

tests/.pytest_cache/v/cache/stepwise

@@ -0,0 +1 @@
+[]

tests/test_demo_data.py

@@ -237,16 +237,16 @@ class TestHaversineIntegration:
     """Tests verifying Haversine distance is used correctly in demo data."""
 
     def test_philadelphia_diagonal_realistic(self):
-        """Philadelphia area diagonal should be ~150km with Haversine."""
+        """Philadelphia area diagonal should be ~15km with Haversine (tightened bbox)."""
         props = DemoData.PHILADELPHIA.value
         diagonal_seconds = props.south_west_corner.driving_time_to(
             props.north_east_corner
         )
         diagonal_km = (diagonal_seconds / 3600) * 50  # 50 km/h average
 
-        # Philadelphia area is roughly 100km x 170km
-        # Diagonal should be around 150-200km
-        assert 100 < diagonal_km < 250, f"Diagonal {diagonal_km}km seems wrong"
+        # Philadelphia bbox is tightened to Center City area (~8km x 12km)
+        # Diagonal should be around 10-20km
+        assert 8 < diagonal_km < 25, f"Diagonal {diagonal_km}km seems wrong"
 
     def test_firenze_diagonal_realistic(self):
         """Firenze area diagonal should be ~10km with Haversine."""

tests/test_haversine.py

@@ -4,12 +4,7 @@ Unit tests for the Haversine driving time calculator in Location class.
 These tests verify that the driving time calculations correctly implement
 the Haversine formula for great-circle distance on Earth.
 """
-from vehicle_routing.domain import (
-    Location,
-    init_driving_time_matrix,
-    clear_driving_time_matrix,
-    is_driving_time_matrix_initialized,
-)
+from vehicle_routing.domain import Location
 
 
 class TestHaversineDrivingTime:
@@ -159,97 +154,3 @@ class TestHaversineInternalMethods:
         assert seconds == 72
 
 
-class TestPrecomputedMatrix:
-    """Tests for the pre-computed driving time matrix functionality."""
-
-    def setup_method(self):
-        """Clear matrix before each test."""
-        clear_driving_time_matrix()
-
-    def teardown_method(self):
-        """Clear matrix after each test."""
-        clear_driving_time_matrix()
-
-    def test_matrix_initially_empty(self):
-        """Matrix should be empty on startup."""
-        clear_driving_time_matrix()
-        assert not is_driving_time_matrix_initialized()
-
-    def test_init_matrix_marks_as_initialized(self):
-        """Initializing matrix should mark it as initialized."""
-        locations = [
-            Location(latitude=0, longitude=0),
-            Location(latitude=1, longitude=1),
-        ]
-        init_driving_time_matrix(locations)
-        assert is_driving_time_matrix_initialized()
-
-    def test_clear_matrix_marks_as_not_initialized(self):
-        """Clearing matrix should mark it as not initialized."""
-        locations = [
-            Location(latitude=0, longitude=0),
-            Location(latitude=1, longitude=1),
-        ]
-        init_driving_time_matrix(locations)
-        clear_driving_time_matrix()
-        assert not is_driving_time_matrix_initialized()
-
-    def test_precomputed_returns_same_as_on_demand(self):
-        """Pre-computed values should match on-demand calculations."""
-        loc1 = Location(latitude=39.95, longitude=-75.17)
-        loc2 = Location(latitude=40.71, longitude=-74.01)
-        loc3 = Location(latitude=41.76, longitude=-72.68)
-
-        # Calculate on-demand first
-        on_demand_1_2 = loc1.driving_time_to(loc2)
-        on_demand_2_3 = loc2.driving_time_to(loc3)
-        on_demand_1_3 = loc1.driving_time_to(loc3)
-
-        # Initialize matrix
-        init_driving_time_matrix([loc1, loc2, loc3])
-
-        # Calculate with matrix
-        precomputed_1_2 = loc1.driving_time_to(loc2)
-        precomputed_2_3 = loc2.driving_time_to(loc3)
-        precomputed_1_3 = loc1.driving_time_to(loc3)
-
-        # Should be identical
-        assert precomputed_1_2 == on_demand_1_2
-        assert precomputed_2_3 == on_demand_2_3
-        assert precomputed_1_3 == on_demand_1_3
-
-    def test_fallback_to_on_demand_for_unknown_location(self):
-        """Locations not in matrix should calculate on-demand."""
-        loc1 = Location(latitude=0, longitude=0)
-        loc2 = Location(latitude=1, longitude=1)
-        loc3 = Location(latitude=2, longitude=2)  # Not in matrix
-
-        # Initialize matrix with only loc1 and loc2
-        init_driving_time_matrix([loc1, loc2])
-
-        # loc3 is not in matrix, should fall back to on-demand
-        driving_time = loc1.driving_time_to(loc3)
-
-        # Should still calculate correctly (on-demand)
-        expected = loc1._calculate_driving_time_haversine(loc3)
-        assert driving_time == expected
-
-    def test_matrix_size_is_n_squared(self):
-        """Matrix should contain n² entries for n locations."""
-        import vehicle_routing.domain as domain_module
-
-        locations = [
-            Location(latitude=0, longitude=0),
-            Location(latitude=1, longitude=1),
-            Location(latitude=2, longitude=2),
-        ]
-        init_driving_time_matrix(locations)
-
-        # 3 locations = 9 entries (including self-to-self)
-        assert len(domain_module._DRIVING_TIME_MATRIX) == 9
-
-    def test_self_to_self_is_zero(self):
-        """Matrix should have 0 for same location."""
-        loc = Location(latitude=40.0, longitude=-75.0)
-        init_driving_time_matrix([loc])
-        assert loc.driving_time_to(loc) == 0

tests/test_routing.py

@@ -0,0 +1,431 @@
+"""
+Unit tests for the routing module.
+
+Tests cover:
+- RouteResult dataclass
+- DistanceMatrix operations
+- Haversine fallback calculations
+- Polyline encoding/decoding roundtrip
+- Location class integration with distance matrix
+"""
+import pytest
+import polyline
+
+from vehicle_routing.domain import Location
+from vehicle_routing.routing import (
+    RouteResult,
+    DistanceMatrix,
+    _haversine_driving_time,
+    _haversine_distance_meters,
+    _straight_line_geometry,
+    compute_distance_matrix_with_progress,
+)
+
+
+class TestRouteResult:
+    """Tests for the RouteResult dataclass."""
+
+    def test_create_route_result(self):
+        """Test creating a basic RouteResult."""
+        result = RouteResult(
+            duration_seconds=3600,
+            distance_meters=50000,
+            geometry="encodedPolyline"
+        )
+        assert result.duration_seconds == 3600
+        assert result.distance_meters == 50000
+        assert result.geometry == "encodedPolyline"
+
+    def test_route_result_optional_geometry(self):
+        """Test RouteResult with no geometry."""
+        result = RouteResult(duration_seconds=100, distance_meters=1000)
+        assert result.geometry is None
+
+
+class TestDistanceMatrix:
+    """Tests for the DistanceMatrix class."""
+
+    def test_empty_matrix(self):
+        """Test empty distance matrix returns None."""
+        matrix = DistanceMatrix()
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+        assert matrix.get_route(loc1, loc2) is None
+
+    def test_set_and_get_route(self):
+        """Test setting and retrieving a route."""
+        matrix = DistanceMatrix()
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+
+        result = RouteResult(
+            duration_seconds=3600,
+            distance_meters=100000,
+            geometry="test_geometry"
+        )
+        matrix.set_route(loc1, loc2, result)
+
+        retrieved = matrix.get_route(loc1, loc2)
+        assert retrieved is not None
+        assert retrieved.duration_seconds == 3600
+        assert retrieved.distance_meters == 100000
+        assert retrieved.geometry == "test_geometry"
+
+    def test_get_route_different_direction(self):
+        """Test that routes are directional (A->B != B->A by default)."""
+        matrix = DistanceMatrix()
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+
+        result = RouteResult(duration_seconds=3600, distance_meters=100000)
+        matrix.set_route(loc1, loc2, result)
+
+        # Should find loc1 -> loc2
+        assert matrix.get_route(loc1, loc2) is not None
+        # Should NOT find loc2 -> loc1 (wasn't set)
+        assert matrix.get_route(loc2, loc1) is None
+
+    def test_get_driving_time_from_matrix(self):
+        """Test getting driving time from matrix."""
+        matrix = DistanceMatrix()
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+
+        result = RouteResult(duration_seconds=3600, distance_meters=100000)
+        matrix.set_route(loc1, loc2, result)
+
+        assert matrix.get_driving_time(loc1, loc2) == 3600
+
+    def test_get_driving_time_falls_back_to_haversine(self):
+        """Test that missing routes fall back to haversine."""
+        matrix = DistanceMatrix()
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+
+        # Don't set any route - should use haversine fallback
+        time = matrix.get_driving_time(loc1, loc2)
+        assert time > 0  # Should return some positive value from haversine
+
+    def test_get_geometry(self):
+        """Test getting geometry from matrix."""
+        matrix = DistanceMatrix()
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+
+        result = RouteResult(
+            duration_seconds=3600,
+            distance_meters=100000,
+            geometry="test_encoded_polyline"
+        )
+        matrix.set_route(loc1, loc2, result)
+
+        assert matrix.get_geometry(loc1, loc2) == "test_encoded_polyline"
+
+    def test_get_geometry_missing_returns_none(self):
+        """Test that missing routes return None for geometry."""
+        matrix = DistanceMatrix()
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+
+        assert matrix.get_geometry(loc1, loc2) is None
+
+
+class TestHaversineFunctions:
+    """Tests for standalone haversine functions."""
+
+    def test_haversine_driving_time_same_location(self):
+        """Same location should return 0 driving time."""
+        loc = Location(latitude=40.0, longitude=-75.0)
+        assert _haversine_driving_time(loc, loc) == 0
+
+    def test_haversine_driving_time_realistic(self):
+        """Test haversine driving time with realistic coordinates."""
+        philadelphia = Location(latitude=39.95, longitude=-75.17)
+        new_york = Location(latitude=40.71, longitude=-74.01)
+        time = _haversine_driving_time(philadelphia, new_york)
+        # ~130 km at 50 km/h = ~9400 seconds
+        assert 8500 < time < 10500
+
+    def test_haversine_distance_meters_same_location(self):
+        """Same location should return 0 distance."""
+        loc = Location(latitude=40.0, longitude=-75.0)
+        assert _haversine_distance_meters(loc, loc) == 0
+
+    def test_haversine_distance_meters_one_degree(self):
+        """Test one degree of latitude is approximately 111 km."""
+        loc1 = Location(latitude=0, longitude=0)
+        loc2 = Location(latitude=1, longitude=0)
+        distance = _haversine_distance_meters(loc1, loc2)
+        # 1 degree latitude = ~111.32 km
+        assert 110000 < distance < 113000
+
+    def test_straight_line_geometry(self):
+        """Test straight line geometry encoding."""
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+        encoded = _straight_line_geometry(loc1, loc2)
+
+        # Decode and verify
+        points = polyline.decode(encoded)
+        assert len(points) == 2
+        assert abs(points[0][0] - 40.0) < 0.0001
+        assert abs(points[0][1] - (-75.0)) < 0.0001
+        assert abs(points[1][0] - 41.0) < 0.0001
+        assert abs(points[1][1] - (-74.0)) < 0.0001
+
+
+class TestPolylineRoundtrip:
+    """Tests for polyline encoding/decoding."""
+
+    def test_encode_decode_roundtrip(self):
+        """Test that encoding and decoding preserves coordinates."""
+        coordinates = [(39.9526, -75.1652), (39.9535, -75.1589)]
+        encoded = polyline.encode(coordinates, precision=5)
+        decoded = polyline.decode(encoded, precision=5)
+
+        assert len(decoded) == 2
+        for orig, dec in zip(coordinates, decoded):
+            assert abs(orig[0] - dec[0]) < 0.00001
+            assert abs(orig[1] - dec[1]) < 0.00001
+
+    def test_encode_single_point(self):
+        """Test encoding a single point."""
+        coordinates = [(40.0, -75.0)]
+        encoded = polyline.encode(coordinates, precision=5)
+        decoded = polyline.decode(encoded, precision=5)
+
+        assert len(decoded) == 1
+        assert abs(decoded[0][0] - 40.0) < 0.00001
+        assert abs(decoded[0][1] - (-75.0)) < 0.00001
+
+    def test_encode_many_points(self):
+        """Test encoding many points (like a real route)."""
+        coordinates = [
+            (39.9526, -75.1652),
+            (39.9535, -75.1589),
+            (39.9543, -75.1690),
+            (39.9520, -75.1685),
+            (39.9505, -75.1660),
+        ]
+        encoded = polyline.encode(coordinates, precision=5)
+        decoded = polyline.decode(encoded, precision=5)
+
+        assert len(decoded) == len(coordinates)
+        for orig, dec in zip(coordinates, decoded):
+            assert abs(orig[0] - dec[0]) < 0.00001
+            assert abs(orig[1] - dec[1]) < 0.00001
+
+
+class TestLocationDistanceMatrixIntegration:
+    """Tests for Location class integration with DistanceMatrix."""
+
+    def setup_method(self):
+        """Clear any existing distance matrix before each test."""
+        Location.clear_distance_matrix()
+
+    def teardown_method(self):
+        """Clear distance matrix after each test."""
+        Location.clear_distance_matrix()
+
+    def test_location_uses_haversine_without_matrix(self):
+        """Without matrix, Location should use haversine."""
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+
+        # Should use haversine (no matrix set)
+        time = loc1.driving_time_to(loc2)
+        assert time > 0
+
+    def test_location_uses_matrix_when_set(self):
+        """With matrix set, Location should use matrix values."""
+        matrix = DistanceMatrix()
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+
+        # Set a specific value in matrix
+        result = RouteResult(duration_seconds=12345, distance_meters=100000)
+        matrix.set_route(loc1, loc2, result)
+
+        # Set the matrix on Location class
+        Location.set_distance_matrix(matrix)
+
+        # Should return the matrix value, not haversine
+        time = loc1.driving_time_to(loc2)
+        assert time == 12345
+
+    def test_location_falls_back_when_route_not_in_matrix(self):
+        """If route not in matrix, Location should fall back to haversine."""
+        matrix = DistanceMatrix()
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+        loc3 = Location(latitude=42.0, longitude=-73.0)
+
+        # Only set loc1 -> loc2
+        result = RouteResult(duration_seconds=12345, distance_meters=100000)
+        matrix.set_route(loc1, loc2, result)
+
+        Location.set_distance_matrix(matrix)
+
+        # loc1 -> loc2 should use matrix
+        assert loc1.driving_time_to(loc2) == 12345
+
+        # loc1 -> loc3 should fall back to haversine (not in matrix)
+        time = loc1.driving_time_to(loc3)
+        assert time != 12345  # Should be haversine calculated value
+        assert time > 0
+
+    def test_get_distance_matrix(self):
+        """Test getting the current distance matrix."""
+        assert Location.get_distance_matrix() is None
+
+        matrix = DistanceMatrix()
+        Location.set_distance_matrix(matrix)
+        assert Location.get_distance_matrix() is matrix
+
+    def test_clear_distance_matrix(self):
+        """Test clearing the distance matrix."""
+        matrix = DistanceMatrix()
+        Location.set_distance_matrix(matrix)
+        assert Location.get_distance_matrix() is not None
+
+        Location.clear_distance_matrix()
+        assert Location.get_distance_matrix() is None
+
+
+class TestDistanceMatrixSameLocation:
+    """Tests for handling same-location routes."""
+
+    def test_same_location_zero_time(self):
+        """Same location should have zero driving time."""
+        loc = Location(latitude=40.0, longitude=-75.0)
+
+        matrix = DistanceMatrix()
+        result = RouteResult(
+            duration_seconds=0,
+            distance_meters=0,
+            geometry=polyline.encode([(40.0, -75.0)], precision=5)
+        )
+        matrix.set_route(loc, loc, result)
+
+        assert matrix.get_driving_time(loc, loc) == 0
+
+
+class TestComputeDistanceMatrixWithProgress:
+    """Tests for the compute_distance_matrix_with_progress function."""
+
+    def test_empty_locations_returns_empty_matrix(self):
+        """Empty location list should return empty matrix."""
+        matrix = compute_distance_matrix_with_progress([], use_osm=False)
+        assert matrix is not None
+        # Empty matrix - no routes to check
+
+    def test_haversine_mode_computes_all_pairs(self):
+        """Haversine mode should compute all location pairs."""
+        locations = [
+            Location(latitude=40.0, longitude=-75.0),
+            Location(latitude=41.0, longitude=-74.0),
+            Location(latitude=42.0, longitude=-73.0),
+        ]
+        matrix = compute_distance_matrix_with_progress(
+            locations, use_osm=False
+        )
+
+        # Should have all 9 pairs (3x3)
+        for origin in locations:
+            for dest in locations:
+                result = matrix.get_route(origin, dest)
+                assert result is not None
+                if origin is dest:
+                    assert result.duration_seconds == 0
+                    assert result.distance_meters == 0
+                else:
+                    assert result.duration_seconds > 0
+                    assert result.distance_meters > 0
+                    assert result.geometry is not None
+
+    def test_progress_callback_is_called(self):
+        """Progress callback should be called during computation."""
+        locations = [
+            Location(latitude=40.0, longitude=-75.0),
+            Location(latitude=41.0, longitude=-74.0),
+        ]
+
+        progress_calls = []
+
+        def callback(phase, message, percent, detail=""):
+            progress_calls.append({
+                "phase": phase,
+                "message": message,
+                "percent": percent,
+                "detail": detail
+            })
+
+        compute_distance_matrix_with_progress(
+            locations, use_osm=False, progress_callback=callback
+        )
+
+        # Should have received progress callbacks
+        assert len(progress_calls) > 0
+
+        # Should have a "complete" phase at the end
+        assert any(p["phase"] == "complete" for p in progress_calls)
+
+        # All percentages should be between 0 and 100
+        for call in progress_calls:
+            assert 0 <= call["percent"] <= 100
+
+    def test_haversine_mode_skips_network_phase(self):
+        """In haversine mode, should not have network download messages."""
+        locations = [
+            Location(latitude=40.0, longitude=-75.0),
+            Location(latitude=41.0, longitude=-74.0),
+        ]
+
+        progress_calls = []
+
+        def callback(phase, message, percent, detail=""):
+            progress_calls.append({
+                "phase": phase,
+                "message": message
+            })
+
+        compute_distance_matrix_with_progress(
+            locations, use_osm=False, progress_callback=callback
+        )
+
+        # Should have a "network" phase but with haversine message
+        network_messages = [p for p in progress_calls if p["phase"] == "network"]
+        assert len(network_messages) > 0
+        assert "haversine" in network_messages[0]["message"].lower()
+
+    def test_bbox_is_used_when_provided(self):
+        """Provided bounding box should be used."""
+        locations = [
+            Location(latitude=40.0, longitude=-75.0),
+            Location(latitude=41.0, longitude=-74.0),
+        ]
+
+        bbox = (42.0, 39.0, -73.0, -76.0)  # north, south, east, west
+
+        # Should complete without error with provided bbox
+        matrix = compute_distance_matrix_with_progress(
+            locations, bbox=bbox, use_osm=False
+        )
+        assert matrix is not None
+
+    def test_geometries_are_straight_lines_in_haversine_mode(self):
+        """In haversine mode, geometries should be straight lines."""
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=41.0, longitude=-74.0)
+
+        matrix = compute_distance_matrix_with_progress(
+            [loc1, loc2], use_osm=False
+        )
+
+        result = matrix.get_route(loc1, loc2)
+        assert result is not None
+        assert result.geometry is not None
+
+        # Decode and verify it's a straight line (2 points)
+        points = polyline.decode(result.geometry)
+        assert len(points) == 2