Upload 36 files

src/vehicle_routing/__init__.py

@@ -0,0 +1,16 @@
+import uvicorn
+
+from .rest_api import app as app
+
+
+def main():
+    config = uvicorn.Config("vehicle_routing:app",
+                            port=8082,
+                            log_config="logging.conf",
+                            use_colors=True)
+    server = uvicorn.Server(config)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

src/vehicle_routing/constraints.py

@@ -0,0 +1,105 @@
+from solverforge_legacy.solver.score import (
+    ConstraintFactory,
+    HardSoftScore,
+    constraint_provider,
+)
+
+from .domain import Vehicle, Visit
+
+VEHICLE_CAPACITY = "vehicleCapacity"
+MINIMIZE_TRAVEL_TIME = "minimizeTravelTime"
+SERVICE_FINISHED_AFTER_MAX_END_TIME = "serviceFinishedAfterMaxEndTime"
+MAX_ROUTE_DURATION = "maxRouteDuration"
+
+
+@constraint_provider
+def define_constraints(factory: ConstraintFactory):
+    return [
+        # Hard constraints
+        vehicle_capacity(factory),
+        service_finished_after_max_end_time(factory),
+        # max_route_duration(factory),  # Optional extension - disabled by default
+        # Soft constraints
+        minimize_travel_time(factory),
+    ]
+
+
+##############################################
+# Hard constraints
+##############################################
+
+
+def vehicle_capacity(factory: ConstraintFactory):
+    return (
+        factory.for_each(Vehicle)
+        .filter(lambda vehicle: vehicle.calculate_total_demand() > vehicle.capacity)
+        .penalize(
+            HardSoftScore.ONE_HARD,
+            lambda vehicle: vehicle.calculate_total_demand() - vehicle.capacity,
+        )
+        .as_constraint(VEHICLE_CAPACITY)
+    )
+
+
+def service_finished_after_max_end_time(factory: ConstraintFactory):
+    return (
+        factory.for_each(Visit)
+        .filter(lambda visit: visit.is_service_finished_after_max_end_time())
+        .penalize(
+            HardSoftScore.ONE_HARD,
+            lambda visit: visit.service_finished_delay_in_minutes(),
+        )
+        .as_constraint(SERVICE_FINISHED_AFTER_MAX_END_TIME)
+    )
+
+
+##############################################
+# Soft constraints
+##############################################
+
+
+def minimize_travel_time(factory: ConstraintFactory):
+    return (
+        factory.for_each(Vehicle)
+        .penalize(
+            HardSoftScore.ONE_SOFT,
+            lambda vehicle: vehicle.calculate_total_driving_time_seconds(),
+        )
+        .as_constraint(MINIMIZE_TRAVEL_TIME)
+    )
+
+
+##############################################
+# Optional constraints (disabled by default)
+##############################################
+
+
+def max_route_duration(factory: ConstraintFactory):
+    """
+    Hard constraint: Vehicle routes cannot exceed 8 hours total duration.
+
+    The limit of 8 hours is chosen based on typical driver shift limits:
+    - PHILADELPHIA: 55 visits across 6 vehicles, routes typically 4-6 hours
+    - FIRENZE: 77 visits across 6 vehicles, routes can approach 8 hours
+
+    Note: A limit that's too low may make the problem infeasible.
+    Always ensure your constraints are compatible with your data dimensions.
+    """
+    MAX_DURATION_SECONDS = 8 * 60 * 60  # 8 hours
+
+    return (
+        factory.for_each(Vehicle)
+        .filter(lambda vehicle: len(vehicle.visits) > 0)
+        .filter(lambda vehicle:
+            (vehicle.arrival_time - vehicle.departure_time).total_seconds()
+            > MAX_DURATION_SECONDS
+        )
+        .penalize(
+            HardSoftScore.ONE_HARD,
+            lambda vehicle: int(
+                ((vehicle.arrival_time - vehicle.departure_time).total_seconds()
+                 - MAX_DURATION_SECONDS) / 60
+            ),
+        )
+        .as_constraint(MAX_ROUTE_DURATION)
+    )

src/vehicle_routing/converters.py

@@ -0,0 +1,228 @@
+from typing import List
+from datetime import datetime, timedelta
+from . import domain
+
+
+# Conversion functions from domain to API models
+def location_to_model(location: domain.Location) -> List[float]:
+    return [location.latitude, location.longitude]
+
+
+def visit_to_model(visit: domain.Visit) -> domain.VisitModel:
+    return domain.VisitModel(
+        id=visit.id,
+        name=visit.name,
+        location=location_to_model(visit.location),
+        demand=visit.demand,
+        min_start_time=visit.min_start_time.isoformat(),
+        max_end_time=visit.max_end_time.isoformat(),
+        service_duration=int(visit.service_duration.total_seconds()),
+        vehicle=visit.vehicle.id if visit.vehicle else None,
+        previous_visit=visit.previous_visit.id if visit.previous_visit else None,
+        next_visit=visit.next_visit.id if visit.next_visit else None,
+        arrival_time=visit.arrival_time.isoformat() if visit.arrival_time else None,
+        start_service_time=visit.start_service_time.isoformat()
+        if visit.start_service_time
+        else None,
+        departure_time=visit.departure_time.isoformat()
+        if visit.departure_time
+        else None,
+        driving_time_seconds_from_previous_standstill=visit.driving_time_seconds_from_previous_standstill,
+    )
+
+
+def vehicle_to_model(vehicle: domain.Vehicle) -> domain.VehicleModel:
+    return domain.VehicleModel(
+        id=vehicle.id,
+        name=vehicle.name,
+        capacity=vehicle.capacity,
+        home_location=location_to_model(vehicle.home_location),
+        departure_time=vehicle.departure_time.isoformat(),
+        visits=[visit.id for visit in vehicle.visits],
+        total_demand=vehicle.total_demand,
+        total_driving_time_seconds=vehicle.total_driving_time_seconds,
+        arrival_time=vehicle.arrival_time.isoformat(),
+    )
+
+
+def plan_to_model(plan: domain.VehicleRoutePlan) -> domain.VehicleRoutePlanModel:
+    return domain.VehicleRoutePlanModel(
+        name=plan.name,
+        south_west_corner=location_to_model(plan.south_west_corner),
+        north_east_corner=location_to_model(plan.north_east_corner),
+        vehicles=[vehicle_to_model(v) for v in plan.vehicles],
+        visits=[visit_to_model(v) for v in plan.visits],
+        score=str(plan.score) if plan.score else None,
+        solver_status=plan.solver_status.name if plan.solver_status else None,
+        total_driving_time_seconds=plan.total_driving_time_seconds,
+        start_date_time=plan.start_date_time.isoformat()
+        if plan.start_date_time
+        else None,
+        end_date_time=plan.end_date_time.isoformat() if plan.end_date_time else None,
+    )
+
+
+# Conversion functions from API models to domain
+def model_to_location(model: List[float]) -> domain.Location:
+    return domain.Location(latitude=model[0], longitude=model[1])
+
+
+def model_to_visit(
+    model: domain.VisitModel, vehicle_lookup: dict, visit_lookup: dict
+) -> domain.Visit:
+    # Handle vehicle reference
+    vehicle = None
+    if model.vehicle:
+        if isinstance(model.vehicle, str):
+            vehicle = vehicle_lookup[model.vehicle]
+        else:
+            # This shouldn't happen in practice, but handle it for completeness
+            vehicle = vehicle_lookup[model.vehicle.id]
+
+    # Handle previous visit reference
+    previous_visit = None
+    if model.previous_visit:
+        if isinstance(model.previous_visit, str):
+            previous_visit = visit_lookup[model.previous_visit]
+        else:
+            previous_visit = visit_lookup[model.previous_visit.id]
+
+    # Handle next visit reference
+    next_visit = None
+    if model.next_visit:
+        if isinstance(model.next_visit, str):
+            next_visit = visit_lookup[model.next_visit]
+        else:
+            next_visit = visit_lookup[model.next_visit.id]
+
+    return domain.Visit(
+        id=model.id,
+        name=model.name,
+        location=model_to_location(model.location),
+        demand=model.demand,
+        min_start_time=datetime.fromisoformat(model.min_start_time),
+        max_end_time=datetime.fromisoformat(model.max_end_time),
+        service_duration=timedelta(seconds=model.service_duration),
+        vehicle=vehicle,
+        previous_visit=previous_visit,
+        next_visit=next_visit,
+        arrival_time=datetime.fromisoformat(model.arrival_time)
+        if model.arrival_time
+        else None,
+    )
+
+
+def model_to_vehicle(model: domain.VehicleModel, visit_lookup: dict) -> domain.Vehicle:
+    # Handle visits references
+    visits = []
+    for visit_ref in model.visits:
+        if isinstance(visit_ref, str):
+            visits.append(visit_lookup[visit_ref])
+        else:
+            visits.append(visit_lookup[visit_ref.id])
+
+    return domain.Vehicle(
+        id=model.id,
+        capacity=model.capacity,
+        home_location=model_to_location(model.home_location),
+        departure_time=datetime.fromisoformat(model.departure_time),
+        visits=visits,
+    )
+
+
+def model_to_plan(model: domain.VehicleRoutePlanModel) -> domain.VehicleRoutePlan:
+    # Convert basic collections first
+    vehicles = []
+    visits = []
+
+    # Convert visits first (they don't depend on vehicles)
+    for visit_model in model.visits:
+        visit = domain.Visit(
+            id=visit_model.id,
+            name=visit_model.name,
+            location=model_to_location(visit_model.location),
+            demand=visit_model.demand,
+            min_start_time=datetime.fromisoformat(visit_model.min_start_time),
+            max_end_time=datetime.fromisoformat(visit_model.max_end_time),
+            service_duration=timedelta(seconds=visit_model.service_duration),
+            vehicle=None,  # Will be set later
+            previous_visit=None,  # Will be set later
+            next_visit=None,  # Will be set later
+            arrival_time=datetime.fromisoformat(visit_model.arrival_time)
+            if visit_model.arrival_time
+            else None,
+        )
+        visits.append(visit)
+
+    # Create lookup dictionaries
+    visit_lookup = {v.id: v for v in visits}
+
+    # Convert vehicles
+    for vehicle_model in model.vehicles:
+        vehicle = domain.Vehicle(
+            id=vehicle_model.id,
+            name=vehicle_model.name,
+            capacity=vehicle_model.capacity,
+            home_location=model_to_location(vehicle_model.home_location),
+            departure_time=datetime.fromisoformat(vehicle_model.departure_time),
+            visits=[],
+        )
+        vehicles.append(vehicle)
+
+    # Create vehicle lookup
+    vehicle_lookup = {v.id: v for v in vehicles}
+
+    # Now set up the relationships
+    for i, visit_model in enumerate(model.visits):
+        visit = visits[i]
+
+        # Set vehicle reference
+        if visit_model.vehicle:
+            if isinstance(visit_model.vehicle, str):
+                visit.vehicle = vehicle_lookup[visit_model.vehicle]
+            else:
+                visit.vehicle = vehicle_lookup[visit_model.vehicle.id]
+
+        # Set previous/next visit references
+        if visit_model.previous_visit:
+            if isinstance(visit_model.previous_visit, str):
+                visit.previous_visit = visit_lookup[visit_model.previous_visit]
+            else:
+                visit.previous_visit = visit_lookup[visit_model.previous_visit.id]
+
+        if visit_model.next_visit:
+            if isinstance(visit_model.next_visit, str):
+                visit.next_visit = visit_lookup[visit_model.next_visit]
+            else:
+                visit.next_visit = visit_lookup[visit_model.next_visit.id]
+
+    # Set up vehicle visits lists
+    for vehicle_model in model.vehicles:
+        vehicle = vehicle_lookup[vehicle_model.id]
+        for visit_ref in vehicle_model.visits:
+            if isinstance(visit_ref, str):
+                vehicle.visits.append(visit_lookup[visit_ref])
+            else:
+                vehicle.visits.append(visit_lookup[visit_ref.id])
+
+    # Handle score
+    score = None
+    if model.score:
+        from solverforge_legacy.solver.score import HardSoftScore
+
+        score = HardSoftScore.parse(model.score)
+
+    # Handle solver status
+    solver_status = domain.SolverStatus.NOT_SOLVING
+    if model.solver_status:
+        solver_status = domain.SolverStatus[model.solver_status]
+
+    return domain.VehicleRoutePlan(
+        name=model.name,
+        south_west_corner=model_to_location(model.south_west_corner),
+        north_east_corner=model_to_location(model.north_east_corner),
+        vehicles=vehicles,
+        visits=visits,
+        score=score,
+        solver_status=solver_status,
+    )

src/vehicle_routing/demo_data.py

@@ -0,0 +1,478 @@
+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, field
+
+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")
+
+
+class CustomerType(Enum):
+    """
+    Customer types with realistic time windows, demand patterns, and service durations.
+
+    Each customer type reflects real-world delivery scenarios:
+    - RESIDENTIAL: Evening deliveries when people are home from work (5-10 min unload)
+    - BUSINESS: Standard business hours with larger orders (15-30 min unload, paperwork)
+    - RESTAURANT: Early morning before lunch prep rush (20-40 min for bulk unload, inspection)
+    """
+    # (label, window_start, window_end, min_demand, max_demand, min_service_min, max_service_min)
+    RESIDENTIAL = ("residential", time(17, 0), time(20, 0), 1, 2, 5, 10)
+    BUSINESS = ("business", time(9, 0), time(17, 0), 3, 6, 15, 30)
+    RESTAURANT = ("restaurant", time(6, 0), time(10, 0), 5, 10, 20, 40)
+
+    def __init__(self, label: str, window_start: time, window_end: time,
+                 min_demand: int, max_demand: int, min_service_minutes: int, max_service_minutes: int):
+        self.label = label
+        self.window_start = window_start
+        self.window_end = window_end
+        self.min_demand = min_demand
+        self.max_demand = max_demand
+        self.min_service_minutes = min_service_minutes
+        self.max_service_minutes = max_service_minutes
+
+
+# Weighted distribution: 50% residential, 30% business, 20% restaurant
+CUSTOMER_TYPE_WEIGHTS = [
+    (CustomerType.RESIDENTIAL, 50),
+    (CustomerType.BUSINESS, 30),
+    (CustomerType.RESTAURANT, 20),
+]
+
+
+def random_customer_type(random: Random) -> CustomerType:
+    """Weighted random selection of customer type."""
+    total = sum(w for _, w in CUSTOMER_TYPE_WEIGHTS)
+    r = random.randint(1, total)
+    cumulative = 0
+    for ctype, weight in CUSTOMER_TYPE_WEIGHTS:
+        cumulative += weight
+        if r <= cumulative:
+            return ctype
+    return CustomerType.RESIDENTIAL  # fallback
+
+
+@dataclass
+class _DemoDataProperties:
+    seed: int
+    visit_count: int
+    vehicle_count: int
+    vehicle_start_time: time
+    min_vehicle_capacity: int
+    max_vehicle_capacity: int
+    south_west_corner: Location
+    north_east_corner: Location
+
+    def __post_init__(self):
+        if self.min_vehicle_capacity < 1:
+            raise ValueError(f"Number of minVehicleCapacity ({self.min_vehicle_capacity}) must be greater than zero.")
+        if self.max_vehicle_capacity < 1:
+            raise ValueError(f"Number of maxVehicleCapacity ({self.max_vehicle_capacity}) must be greater than zero.")
+        if self.min_vehicle_capacity >= self.max_vehicle_capacity:
+            raise ValueError(f"maxVehicleCapacity ({self.max_vehicle_capacity}) must be greater than "
+                             f"minVehicleCapacity ({self.min_vehicle_capacity}).")
+        if self.visit_count < 1:
+            raise ValueError(f"Number of visitCount ({self.visit_count}) must be greater than zero.")
+        if self.vehicle_count < 1:
+            raise ValueError(f"Number of vehicleCount ({self.vehicle_count}) must be greater than zero.")
+        if self.north_east_corner.latitude <= self.south_west_corner.latitude:
+            raise ValueError(f"northEastCorner.getLatitude ({self.north_east_corner.latitude}) must be greater than "
+                             f"southWestCorner.getLatitude({self.south_west_corner.latitude}).")
+        if self.north_east_corner.longitude <= self.south_west_corner.longitude:
+            raise ValueError(f"northEastCorner.getLongitude ({self.north_east_corner.longitude}) must be greater than "
+                             f"southWestCorner.getLongitude({self.south_west_corner.longitude}).")
+
+
+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.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.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.73,
+                                           longitude=11.17),
+                                  Location(latitude=43.81,
+                                           longitude=11.32))
+
+
+def doubles(random: Random, start: float, end: float) -> Generator[float, None, None]:
+    while True:
+        yield random.uniform(start, end)
+
+
+def ints(random: Random, start: int, end: int) -> Generator[int, None, None]:
+    while True:
+        yield random.randrange(start, end)
+
+
+T = TypeVar('T')
+
+
+def values(random: Random, sequence: Sequence[T]) -> Generator[T, None, None]:
+    start = 0
+    end = len(sequence) - 1
+    while True:
+        yield sequence[random.randint(start, end)]
+
+
+def generate_names(random: Random) -> Generator[str, None, None]:
+    while True:
+        yield f'{random.choice(FIRST_NAMES)} {random.choice(LAST_NAMES)}'
+
+
+def generate_demo_data(demo_data_enum: DemoData) -> VehicleRoutePlan:
+    """
+    Generate demo data for vehicle routing using real street addresses.
+
+    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
+    """
+    name = "demo"
+    demo_data = demo_data_enum.value
+    random = Random(demo_data.seed)
+
+    # 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)
+
+    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 = []
+
+    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),
+                )
+            )
+
+        # 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:
+        # 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:
+    return datetime.combine(date.today(), local_time)

src/vehicle_routing/domain.py

@@ -0,0 +1,371 @@
+from solverforge_legacy.solver import SolverStatus
+from solverforge_legacy.solver.score import HardSoftScore
+from solverforge_legacy.solver.domain import (
+    planning_entity,
+    planning_solution,
+    PlanningId,
+    PlanningScore,
+    PlanningListVariable,
+    PlanningEntityCollectionProperty,
+    ValueRangeProvider,
+    InverseRelationShadowVariable,
+    PreviousElementShadowVariable,
+    NextElementShadowVariable,
+    CascadingUpdateShadowVariable,
+)
+
+from datetime import datetime, timedelta
+from typing import Annotated, Optional, List, Union, ClassVar, TYPE_CHECKING
+from dataclasses import dataclass, field
+from .json_serialization import JsonDomainBase
+from pydantic import Field
+
+if TYPE_CHECKING:
+    from .routing import DistanceMatrix
+
+
+@dataclass
+class Location:
+    """
+    Represents a geographic location with latitude and longitude.
+
+    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.
+
+        Uses the precomputed distance matrix if available, otherwise
+        falls back to haversine 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:
+        """
+        Calculate driving time in seconds using Haversine distance.
+
+        Algorithm:
+        1. Convert lat/long to 3D Cartesian coordinates on a unit sphere
+        2. Calculate Euclidean distance between the two points
+        3. Use the arc sine formula to get the great-circle distance
+        4. Convert meters to driving seconds assuming average speed
+        """
+        if self.latitude == other.latitude and self.longitude == other.longitude:
+            return 0
+
+        from_cartesian = self._to_cartesian()
+        to_cartesian = other._to_cartesian()
+        distance_meters = self._calculate_distance(from_cartesian, to_cartesian)
+        return self._meters_to_driving_seconds(distance_meters)
+
+    def _to_cartesian(self) -> tuple[float, float, float, float]:
+        """Convert latitude/longitude to 3D Cartesian coordinates on a unit sphere."""
+        import math
+        lat_rad = math.radians(self.latitude)
+        lon_rad = math.radians(self.longitude)
+        # Cartesian coordinates, normalized for a sphere of diameter 1.0
+        x = 0.5 * math.cos(lat_rad) * math.sin(lon_rad)
+        y = 0.5 * math.cos(lat_rad) * math.cos(lon_rad)
+        z = 0.5 * math.sin(lat_rad)
+        return (x, y, z)
+
+    def _calculate_distance(self, from_c: tuple[float, float, float, float], to_c: tuple[float, float, float, float]) -> int:
+        """Calculate great-circle distance in meters between two Cartesian points."""
+        import math
+        dx = from_c[0] - to_c[0]
+        dy = from_c[1] - to_c[1]
+        dz = from_c[2] - to_c[2]
+        r = math.sqrt(dx * dx + dy * dy + dz * dz)
+        return round(self._TWICE_EARTH_RADIUS_M * math.asin(r))
+
+    @classmethod
+    def _meters_to_driving_seconds(cls, meters: int) -> int:
+        """Convert distance in meters to driving time in seconds."""
+        # Formula: seconds = meters / (km/h) * 3.6
+        # This is equivalent to: seconds = meters / (speed_m_per_s)
+        # where speed_m_per_s = km/h / 3.6
+        return round(meters / cls._AVERAGE_SPEED_KMPH * 3.6)
+
+    def __str__(self):
+        return f"[{self.latitude}, {self.longitude}]"
+
+    def __repr__(self):
+        return f"Location({self.latitude}, {self.longitude})"
+
+
+@planning_entity
+@dataclass
+class Visit:
+    id: Annotated[str, PlanningId]
+    name: str
+    location: Location
+    demand: int
+    min_start_time: datetime
+    max_end_time: datetime
+    service_duration: timedelta
+    vehicle: Annotated[
+        Optional["Vehicle"],
+        InverseRelationShadowVariable(source_variable_name="visits"),
+    ] = None
+    previous_visit: Annotated[
+        Optional["Visit"], PreviousElementShadowVariable(source_variable_name="visits")
+    ] = None
+    next_visit: Annotated[
+        Optional["Visit"], NextElementShadowVariable(source_variable_name="visits")
+    ] = None
+    arrival_time: Annotated[
+        Optional[datetime],
+        CascadingUpdateShadowVariable(target_method_name="update_arrival_time"),
+    ] = None
+
+    def update_arrival_time(self):
+        if self.vehicle is None or (
+            self.previous_visit is not None and self.previous_visit.arrival_time is None
+        ):
+            self.arrival_time = None
+        elif self.previous_visit is None:
+            self.arrival_time = self.vehicle.departure_time + timedelta(
+                seconds=self.vehicle.home_location.driving_time_to(self.location)
+            )
+        else:
+            self.arrival_time = (
+                self.previous_visit.calculate_departure_time()
+                + timedelta(
+                    seconds=self.previous_visit.location.driving_time_to(self.location)
+                )
+            )
+
+    def calculate_departure_time(self):
+        if self.arrival_time is None:
+            return None
+
+        return max(self.arrival_time, self.min_start_time) + self.service_duration
+
+    @property
+    def departure_time(self) -> Optional[datetime]:
+        return self.calculate_departure_time()
+
+    @property
+    def start_service_time(self) -> Optional[datetime]:
+        if self.arrival_time is None:
+            return None
+        return max(self.arrival_time, self.min_start_time)
+
+    def is_service_finished_after_max_end_time(self) -> bool:
+        return (
+            self.arrival_time is not None
+            and self.calculate_departure_time() > self.max_end_time
+        )
+
+    def service_finished_delay_in_minutes(self) -> int:
+        if self.arrival_time is None:
+            return 0
+        # Round up to next minute using the negative division trick:
+        # ex: 30 seconds / -1 minute = -0.5,
+        # so 30 seconds // -1 minute = -1,
+        # and negating that gives 1
+        return -(
+            (self.calculate_departure_time() - self.max_end_time)
+            // timedelta(minutes=-1)
+        )
+
+    @property
+    def driving_time_seconds_from_previous_standstill(self) -> Optional[int]:
+        if self.vehicle is None:
+            return None
+
+        if self.previous_visit is None:
+            return self.vehicle.home_location.driving_time_to(self.location)
+        else:
+            return self.previous_visit.location.driving_time_to(self.location)
+
+    def __str__(self):
+        return self.id
+
+    def __repr__(self):
+        return f"Visit({self.id})"
+
+
+@planning_entity
+@dataclass
+class Vehicle:
+    id: Annotated[str, PlanningId]
+    name: str
+    capacity: int
+    home_location: Location
+    departure_time: datetime
+    visits: Annotated[list[Visit], PlanningListVariable] = field(default_factory=list)
+
+    @property
+    def arrival_time(self) -> datetime:
+        if len(self.visits) == 0:
+            return self.departure_time
+        return self.visits[-1].departure_time + timedelta(
+            seconds=self.visits[-1].location.driving_time_to(self.home_location)
+        )
+
+    @property
+    def total_demand(self) -> int:
+        return self.calculate_total_demand()
+
+    @property
+    def total_driving_time_seconds(self) -> int:
+        return self.calculate_total_driving_time_seconds()
+
+    def calculate_total_demand(self) -> int:
+        total_demand = 0
+        for visit in self.visits:
+            total_demand += visit.demand
+        return total_demand
+
+    def calculate_total_driving_time_seconds(self) -> int:
+        if len(self.visits) == 0:
+            return 0
+        total_driving_time_seconds = 0
+        previous_location = self.home_location
+
+        for visit in self.visits:
+            total_driving_time_seconds += previous_location.driving_time_to(
+                visit.location
+            )
+            previous_location = visit.location
+
+        total_driving_time_seconds += previous_location.driving_time_to(
+            self.home_location
+        )
+        return total_driving_time_seconds
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return f"Vehicle({self.id}, {self.name})"
+
+
+@planning_solution
+@dataclass
+class VehicleRoutePlan:
+    name: str
+    south_west_corner: Location
+    north_east_corner: Location
+    vehicles: Annotated[list[Vehicle], PlanningEntityCollectionProperty]
+    visits: Annotated[list[Visit], PlanningEntityCollectionProperty, ValueRangeProvider]
+    score: Annotated[Optional[HardSoftScore], PlanningScore] = None
+    solver_status: SolverStatus = SolverStatus.NOT_SOLVING
+
+    @property
+    def total_driving_time_seconds(self) -> int:
+        out = 0
+        for vehicle in self.vehicles:
+            out += vehicle.total_driving_time_seconds
+        return out
+
+    @property
+    def start_date_time(self) -> Optional[datetime]:
+        """Earliest vehicle departure time - for timeline window."""
+        if not self.vehicles:
+            return None
+        return min(v.departure_time for v in self.vehicles)
+
+    @property
+    def end_date_time(self) -> Optional[datetime]:
+        """Latest vehicle arrival time - for timeline window."""
+        if not self.vehicles:
+            return None
+        return max(v.arrival_time for v in self.vehicles)
+
+    def __str__(self):
+        return f"VehicleRoutePlan(name={self.name}, vehicles={self.vehicles}, visits={self.visits})"
+
+
+# Pydantic REST models for API (used for deserialization and context)
+class LocationModel(JsonDomainBase):
+    latitude: float
+    longitude: float
+
+
+class VisitModel(JsonDomainBase):
+    id: str
+    name: str
+    location: List[float]  # [lat, lng] array
+    demand: int
+    min_start_time: str = Field(..., alias="minStartTime")  # ISO datetime string
+    max_end_time: str = Field(..., alias="maxEndTime")  # ISO datetime string
+    service_duration: int = Field(..., alias="serviceDuration")  # Duration in seconds
+    vehicle: Union[str, "VehicleModel", None] = None
+    previous_visit: Union[str, "VisitModel", None] = Field(None, alias="previousVisit")
+    next_visit: Union[str, "VisitModel", None] = Field(None, alias="nextVisit")
+    arrival_time: Optional[str] = Field(
+        None, alias="arrivalTime"
+    )  # ISO datetime string
+    start_service_time: Optional[str] = Field(
+        None, alias="startServiceTime"
+    )  # ISO datetime string
+    departure_time: Optional[str] = Field(
+        None, alias="departureTime"
+    )  # ISO datetime string
+    driving_time_seconds_from_previous_standstill: Optional[int] = Field(
+        None, alias="drivingTimeSecondsFromPreviousStandstill"
+    )
+
+
+class VehicleModel(JsonDomainBase):
+    id: str
+    name: str
+    capacity: int
+    home_location: List[float] = Field(..., alias="homeLocation")  # [lat, lng] array
+    departure_time: str = Field(..., alias="departureTime")  # ISO datetime string
+    visits: List[Union[str, VisitModel]] = Field(default_factory=list)
+    total_demand: int = Field(0, alias="totalDemand")
+    total_driving_time_seconds: int = Field(0, alias="totalDrivingTimeSeconds")
+    arrival_time: Optional[str] = Field(
+        None, alias="arrivalTime"
+    )  # ISO datetime string
+
+
+class VehicleRoutePlanModel(JsonDomainBase):
+    name: str
+    south_west_corner: List[float] = Field(
+        ..., alias="southWestCorner"
+    )  # [lat, lng] array
+    north_east_corner: List[float] = Field(
+        ..., alias="northEastCorner"
+    )  # [lat, lng] array
+    vehicles: List[VehicleModel]
+    visits: List[VisitModel]
+    score: Optional[str] = None
+    solver_status: Optional[str] = None
+    total_driving_time_seconds: int = Field(0, alias="totalDrivingTimeSeconds")
+    start_date_time: Optional[str] = Field(None, alias="startDateTime")
+    end_date_time: Optional[str] = Field(None, alias="endDateTime")

src/vehicle_routing/json_serialization.py

@@ -0,0 +1,85 @@
+from solverforge_legacy.solver.score import HardSoftScore
+
+from typing import Any
+from datetime import timedelta
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    PlainSerializer,
+    BeforeValidator,
+    ValidationInfo,
+)
+from pydantic.alias_generators import to_camel
+
+
+class JsonDomainBase(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+
+def make_id_item_validator(key: str):
+    def validator(v: Any, info: ValidationInfo) -> Any:
+        if v is None:
+            return None
+
+        if not isinstance(v, str) or not info.context:
+            return v
+
+        return info.context.get(key)[v]
+
+    return BeforeValidator(validator)
+
+
+def make_id_list_item_validator(key: str):
+    def validator(v: Any, info: ValidationInfo) -> Any:
+        if v is None:
+            return None
+
+        if isinstance(v, (list, tuple)):
+            out = []
+            for item in v:
+                if not isinstance(v, str) or not info.context:
+                    return v
+                out.append(info.context.get(key)[item])
+            return out
+
+        return v
+
+    return BeforeValidator(validator)
+
+
+LocationSerializer = PlainSerializer(
+    lambda location: [
+        location.latitude,
+        location.longitude,
+    ],
+    return_type=list[float],
+)
+ScoreSerializer = PlainSerializer(lambda score: str(score), return_type=str)
+IdSerializer = PlainSerializer(
+    lambda item: item.id if item is not None else None, return_type=str | None
+)
+IdListSerializer = PlainSerializer(
+    lambda items: [item.id for item in items], return_type=list
+)
+DurationSerializer = PlainSerializer(
+    lambda duration: duration // timedelta(seconds=1), return_type=int
+)
+
+VisitListValidator = make_id_list_item_validator("visits")
+VisitValidator = make_id_item_validator("visits")
+VehicleValidator = make_id_item_validator("vehicles")
+
+
+def validate_score(v: Any, info: ValidationInfo) -> Any:
+    if isinstance(v, HardSoftScore) or v is None:
+        return v
+    if isinstance(v, str):
+        return HardSoftScore.parse(v)
+    raise ValueError('"score" should be a string')
+
+
+ScoreValidator = BeforeValidator(validate_score)

src/vehicle_routing/rest_api.py

@@ -0,0 +1,524 @@
+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, Optional
+from dataclasses import asdict
+from enum import Enum
+import logging
+import json
+import asyncio
+
+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] = {}
+
+
+# Request/Response models for recommendation endpoints
+class VehicleRecommendation(BaseModel):
+    """Recommendation for assigning a visit to a vehicle at a specific index."""
+    vehicle_id: str = Field(..., alias="vehicleId")
+    index: int
+
+    class Config:
+        populate_by_name = True
+
+
+class RecommendedAssignmentResponse(BaseModel):
+    """Response from the recommendation API."""
+    proposition: VehicleRecommendation
+    score_diff: str = Field(..., alias="scoreDiff")
+
+    class Config:
+        populate_by_name = True
+
+
+class RecommendationRequest(BaseModel):
+    """Request for visit assignment recommendations."""
+    solution: VehicleRoutePlanModel
+    visit_id: str = Field(..., alias="visitId")
+
+    class Config:
+        populate_by_name = True
+
+
+class ApplyRecommendationRequest(BaseModel):
+    """Request to apply a recommendation."""
+    solution: VehicleRoutePlanModel
+    visit_id: str = Field(..., alias="visitId")
+    vehicle_id: str = Field(..., alias="vehicleId")
+    index: int
+
+    class Config:
+        populate_by_name = True
+
+
+def json_to_vehicle_route_plan(json_data: dict) -> VehicleRoutePlan:
+    """Convert JSON data to VehicleRoutePlan using the model converters."""
+    plan_model = VehicleRoutePlanModel.model_validate(json_data)
+    return model_to_plan(plan_model)
+
+
+@app.get("/demo-data")
+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,
+    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)
+        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]
+        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)
+    if not route:
+        raise HTTPException(status_code=404, detail="Route plan not found")
+    route.solver_status = solver_manager.get_solver_status(problem_id)
+    return plan_to_model(route)
+
+@app.post("/route-plans")
+async def solve_route(plan_model: VehicleRoutePlanModel) -> str:
+    job_id = str(uuid4())
+    # Convert to domain model for solver
+    domain_plan = model_to_plan(plan_model)
+    data_sets[job_id] = domain_plan
+    solver_manager.solve_and_listen(
+        job_id,
+        domain_plan,
+        lambda solution: data_sets.update({job_id: solution})
+    )
+    return job_id
+
+@app.put("/route-plans/analyze")
+async def analyze_route(plan_model: VehicleRoutePlanModel) -> dict:
+    domain_plan = model_to_plan(plan_model)
+    analysis = solution_manager.analyze(domain_plan)
+    constraints = []
+    for constraint in getattr(analysis, 'constraint_analyses', []) or []:
+        matches = [
+            MatchAnalysisDTO(
+                name=str(getattr(getattr(match, 'constraint_ref', None), 'constraint_name', "")),
+                score=str(getattr(match, 'score', "0hard/0soft")),
+                justification=str(getattr(match, 'justification', ""))
+            )
+            for match in getattr(constraint, 'matches', []) or []
+        ]
+        constraints.append(ConstraintAnalysisDTO(
+            name=str(getattr(constraint, 'constraint_name', "")),
+            weight=str(getattr(constraint, 'weight', "0hard/0soft")),
+            score=str(getattr(constraint, 'score', "0hard/0soft")),
+            matches=matches
+        ))
+    return {"constraints": [asdict(constraint) for constraint in constraints]}
+
+@app.get("/route-plans")
+async def list_route_plans() -> List[str]:
+    """List the job IDs of all submitted route plans."""
+    return list(data_sets.keys())
+
+
+@app.get("/route-plans/{problem_id}/status")
+async def get_route_status(problem_id: str) -> dict:
+    """Get the route plan status and score for a given job ID."""
+    route = data_sets.get(problem_id)
+    if not route:
+        raise HTTPException(status_code=404, detail="Route plan not found")
+    solver_status = solver_manager.get_solver_status(problem_id)
+    return {
+        "name": route.name,
+        "score": str(route.score) if route.score else None,
+        "solverStatus": solver_status.name if solver_status else None,
+    }
+
+
+@app.delete("/route-plans/{problem_id}")
+async def stop_solving(problem_id: str) -> VehicleRoutePlanModel:
+    """Terminate solving for a given job ID. Returns the best solution so far."""
+    solver_manager.terminate_early(problem_id)
+    route = data_sets.get(problem_id)
+    if not route:
+        raise HTTPException(status_code=404, detail="Route plan not found")
+    route.solver_status = solver_manager.get_solver_status(problem_id)
+    return plan_to_model(route)
+
+
+@app.post("/route-plans/recommendation")
+async def recommend_assignment(request: RecommendationRequest) -> List[RecommendedAssignmentResponse]:
+    """
+    Request recommendations for assigning a visit to vehicles.
+
+    Returns a list of recommended assignments sorted by score impact.
+    """
+    domain_plan = model_to_plan(request.solution)
+
+    # Find the visit by ID
+    visit = None
+    for v in domain_plan.visits:
+        if v.id == request.visit_id:
+            visit = v
+            break
+
+    if visit is None:
+        raise HTTPException(status_code=404, detail=f"Visit {request.visit_id} not found")
+
+    # Get recommendations using solution_manager
+    try:
+        recommendations = solution_manager.recommend_assignment(
+            domain_plan,
+            visit,
+            lambda v: VehicleRecommendation(vehicle_id=v.vehicle.id, index=v.vehicle.visits.index(v))
+        )
+
+        # Convert to response format (limit to top 5)
+        result = []
+        for rec in recommendations[:5]:
+            result.append(RecommendedAssignmentResponse(
+                proposition=rec.proposition,
+                score_diff=str(rec.score_diff) if hasattr(rec, 'score_diff') else "0hard/0soft"
+            ))
+        return result
+    except Exception:
+        # If recommend_assignment is not available, return empty list
+        return []
+
+
+@app.post("/route-plans/recommendation/apply")
+async def apply_recommendation(request: ApplyRecommendationRequest) -> VehicleRoutePlanModel:
+    """
+    Apply a recommendation to assign a visit to a vehicle at a specific index.
+
+    Returns the updated solution.
+    """
+    domain_plan = model_to_plan(request.solution)
+
+    # Find the vehicle by ID
+    vehicle = None
+    for v in domain_plan.vehicles:
+        if v.id == request.vehicle_id:
+            vehicle = v
+            break
+
+    if vehicle is None:
+        raise HTTPException(status_code=404, detail=f"Vehicle {request.vehicle_id} not found")
+
+    # Find the visit by ID
+    visit = None
+    for v in domain_plan.visits:
+        if v.id == request.visit_id:
+            visit = v
+            break
+
+    if visit is None:
+        raise HTTPException(status_code=404, detail=f"Visit {request.visit_id} not found")
+
+    # Insert visit at the specified index
+    vehicle.visits.insert(request.index, visit)
+
+    # Update the solution to recalculate shadow variables
+    solution_manager.update(domain_plan)
+
+    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,
+    )

src/vehicle_routing/score_analysis.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from typing import Annotated
+
+from solverforge_legacy.solver.score import HardSoftScore
+from .json_serialization import ScoreSerializer
+
+
+@dataclass
+class MatchAnalysisDTO:
+    name: str
+    score: Annotated[HardSoftScore, ScoreSerializer]
+    justification: object
+
+
+@dataclass
+class ConstraintAnalysisDTO:
+    name: str
+    weight: Annotated[HardSoftScore, ScoreSerializer]
+    matches: list[MatchAnalysisDTO]
+    score: Annotated[HardSoftScore, ScoreSerializer]

src/vehicle_routing/solver.py

@@ -0,0 +1,23 @@
+from solverforge_legacy.solver import SolverManager, SolutionManager
+from solverforge_legacy.solver.config import (
+    SolverConfig,
+    ScoreDirectorFactoryConfig,
+    TerminationConfig,
+    Duration,
+)
+
+from .domain import Vehicle, VehicleRoutePlan, Visit
+from .constraints import define_constraints
+
+
+solver_config = SolverConfig(
+    solution_class=VehicleRoutePlan,
+    entity_class_list=[Vehicle, Visit],
+    score_director_factory_config=ScoreDirectorFactoryConfig(
+        constraint_provider_function=define_constraints
+    ),
+    termination_config=TerminationConfig(spent_limit=Duration(seconds=30)),
+)
+
+solver_manager = SolverManager.create(solver_config)
+solution_manager = SolutionManager.create(solver_manager)

static/app.js

@@ -0,0 +1,1607 @@
+let autoRefreshIntervalId = null;
+let initialized = false;
+let optimizing = false;
+let demoDataId = null;
+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();
+const visitMarkerByIdMap = new Map();
+
+const map = L.map("map", { doubleClickZoom: false }).setView(
+  [51.505, -0.09],
+  13,
+);
+const visitGroup = L.layerGroup().addTo(map);
+const homeLocationGroup = L.layerGroup().addTo(map);
+const routeGroup = L.layerGroup().addTo(map);
+
+/************************************ Time line constants and variable definitions ************************************/
+
+let byVehicleTimeline;
+let byVisitTimeline;
+const byVehicleGroupData = new vis.DataSet();
+const byVehicleItemData = new vis.DataSet();
+const byVisitGroupData = new vis.DataSet();
+const byVisitItemData = new vis.DataSet();
+
+const byVehicleTimelineOptions = {
+  timeAxis: { scale: "hour" },
+  orientation: { axis: "top" },
+  xss: { disabled: true }, // Items are XSS safe through JQuery
+  stack: false,
+  stackSubgroups: false,
+  zoomMin: 1000 * 60 * 60, // A single hour in milliseconds
+  zoomMax: 1000 * 60 * 60 * 24, // A single day in milliseconds
+};
+
+const byVisitTimelineOptions = {
+  timeAxis: { scale: "hour" },
+  orientation: { axis: "top" },
+  verticalScroll: true,
+  xss: { disabled: true }, // Items are XSS safe through JQuery
+  stack: false,
+  stackSubgroups: false,
+  zoomMin: 1000 * 60 * 60, // A single hour in milliseconds
+  zoomMax: 1000 * 60 * 60 * 24, // A single day in milliseconds
+};
+
+/************************************ Initialize ************************************/
+
+// Vehicle management state
+let addingVehicleMode = false;
+let pickingVehicleLocation = false;
+let tempVehicleMarker = null;
+let vehicleDeparturePicker = null;
+
+// Route highlighting state
+let highlightedVehicleId = null;
+let routeNumberMarkers = [];  // Markers showing 1, 2, 3... on route stops
+
+
+$(document).ready(function () {
+  replaceQuickstartSolverForgeAutoHeaderFooter();
+
+  // Initialize timelines after DOM is ready with a small delay to ensure Bootstrap tabs are rendered
+  setTimeout(function () {
+    const byVehiclePanel = document.getElementById("byVehiclePanel");
+    const byVisitPanel = document.getElementById("byVisitPanel");
+
+    if (byVehiclePanel) {
+      byVehicleTimeline = new vis.Timeline(
+        byVehiclePanel,
+        byVehicleItemData,
+        byVehicleGroupData,
+        byVehicleTimelineOptions,
+      );
+    }
+
+    if (byVisitPanel) {
+      byVisitTimeline = new vis.Timeline(
+        byVisitPanel,
+        byVisitItemData,
+        byVisitGroupData,
+        byVisitTimelineOptions,
+      );
+    }
+  }, 100);
+
+  L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", {
+    maxZoom: 19,
+    attribution:
+      '&copy; <a href="https://www.openstreetmap.org/">OpenStreetMap</a> contributors',
+  }).addTo(map);
+
+  solveButton.click(solve);
+  stopSolvingButton.click(stopSolving);
+  analyzeButton.click(analyze);
+  refreshSolvingButtons(false);
+
+  // HACK to allow vis-timeline to work within Bootstrap tabs
+  $("#byVehicleTab").on("shown.bs.tab", function (event) {
+    if (byVehicleTimeline) {
+      byVehicleTimeline.redraw();
+    }
+  });
+  $("#byVisitTab").on("shown.bs.tab", function (event) {
+    if (byVisitTimeline) {
+      byVisitTimeline.redraw();
+    }
+  });
+
+  // Map click handler - context aware
+  map.on("click", function (e) {
+    if (addingVehicleMode) {
+      // Set vehicle home location
+      setVehicleHomeLocation(e.latlng.lat, e.latlng.lng);
+    } else if (!optimizing) {
+      // Add new visit
+      visitMarker = L.circleMarker(e.latlng);
+      visitMarker.setStyle({ color: "green" });
+      visitMarker.addTo(map);
+      openRecommendationModal(e.latlng.lat, e.latlng.lng);
+    }
+  });
+
+  // Remove visit marker when modal closes
+  $("#newVisitModal").on("hidden.bs.modal", function () {
+    if (visitMarker) {
+      map.removeLayer(visitMarker);
+    }
+  });
+
+  // Vehicle management
+  $("#addVehicleBtn").click(openAddVehicleModal);
+  $("#removeVehicleBtn").click(removeLastVehicle);
+  $("#confirmAddVehicle").click(confirmAddVehicle);
+  $("#pickLocationBtn").click(pickVehicleLocationOnMap);
+
+  // Clean up when add vehicle modal closes (only if not picking location)
+  $("#addVehicleModal").on("hidden.bs.modal", function () {
+    if (!pickingVehicleLocation) {
+      addingVehicleMode = false;
+      if (tempVehicleMarker) {
+        map.removeLayer(tempVehicleMarker);
+        tempVehicleMarker = null;
+      }
+    }
+  });
+
+  // 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();
+});
+
+/*************************************** Vehicle Management **************************************/
+
+function openAddVehicleModal() {
+  if (optimizing) {
+    alert("Cannot add vehicles while solving. Please stop solving first.");
+    return;
+  }
+  if (!loadedRoutePlan) {
+    alert("Please load a dataset first.");
+    return;
+  }
+
+  addingVehicleMode = true;
+
+  // Suggest next vehicle name
+  $("#vehicleName").val("").attr("placeholder", `e.g., ${getNextVehicleName()}`);
+
+  // Set default values based on existing vehicles
+  const existingVehicle = loadedRoutePlan.vehicles[0];
+  if (existingVehicle) {
+    $("#vehicleCapacity").val(existingVehicle.capacity || 25);
+    const defaultLat = existingVehicle.homeLocation[0];
+    const defaultLng = existingVehicle.homeLocation[1];
+    $("#vehicleHomeLat").val(defaultLat.toFixed(6));
+    $("#vehicleHomeLng").val(defaultLng.toFixed(6));
+  }
+
+  // Initialize departure time picker
+  const tomorrow = JSJoda.LocalDate.now().plusDays(1);
+  const defaultDeparture = tomorrow.atTime(JSJoda.LocalTime.of(6, 0));
+
+  if (vehicleDeparturePicker) {
+    vehicleDeparturePicker.destroy();
+  }
+  vehicleDeparturePicker = flatpickr("#vehicleDepartureTime", {
+    enableTime: true,
+    dateFormat: "Y-m-d H:i",
+    defaultDate: defaultDeparture.format(JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm'))
+  });
+
+  $("#addVehicleModal").modal("show");
+}
+
+function pickVehicleLocationOnMap() {
+  // Hide modal temporarily while user picks location
+  pickingVehicleLocation = true;
+  addingVehicleMode = true;
+  $("#addVehicleModal").modal("hide");
+
+  // Show hint on map
+  $("#mapHint").html('<i class="fas fa-crosshairs"></i> Click on the map to set vehicle depot location').removeClass("hidden");
+}
+
+function setVehicleHomeLocation(lat, lng) {
+  $("#vehicleHomeLat").val(lat.toFixed(6));
+  $("#vehicleHomeLng").val(lng.toFixed(6));
+  $("#vehicleLocationPreview").html(`<i class="fas fa-check text-success"></i> Location set: ${lat.toFixed(4)}, ${lng.toFixed(4)}`);
+
+  // Show temporary marker
+  if (tempVehicleMarker) {
+    map.removeLayer(tempVehicleMarker);
+  }
+  tempVehicleMarker = L.marker([lat, lng], {
+    icon: L.divIcon({
+      className: 'temp-vehicle-marker',
+      html: `<div style="
+        background-color: #6366f1;
+        border: 3px solid white;
+        border-radius: 4px;
+        width: 28px;
+        height: 28px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        box-shadow: 0 2px 4px rgba(0,0,0,0.4);
+        animation: pulse 1s infinite;
+      "><i class="fas fa-warehouse" style="color: white; font-size: 12px;"></i></div>`,
+      iconSize: [28, 28],
+      iconAnchor: [14, 14]
+    })
+  });
+  tempVehicleMarker.addTo(map);
+
+  // If we were picking location, re-open the modal
+  if (pickingVehicleLocation) {
+    pickingVehicleLocation = false;
+    addingVehicleMode = false;
+    $("#addVehicleModal").modal("show");
+    // Restore normal map hint
+    $("#mapHint").html('<i class="fas fa-mouse-pointer"></i> Click on the map to add a new visit');
+  }
+}
+
+// Extended phonetic alphabet for generating vehicle names
+const PHONETIC_NAMES = ["Alpha", "Bravo", "Charlie", "Delta", "Echo", "Foxtrot", "Golf", "Hotel", "India", "Juliet", "Kilo", "Lima", "Mike", "November", "Oscar", "Papa", "Quebec", "Romeo", "Sierra", "Tango", "Uniform", "Victor", "Whiskey", "X-ray", "Yankee", "Zulu"];
+
+function getNextVehicleName() {
+  if (!loadedRoutePlan) return "Alpha";
+  const usedNames = new Set(loadedRoutePlan.vehicles.map(v => v.name));
+  for (const name of PHONETIC_NAMES) {
+    if (!usedNames.has(name)) return name;
+  }
+  // Fallback if all names used
+  return `Vehicle ${loadedRoutePlan.vehicles.length + 1}`;
+}
+
+async function confirmAddVehicle() {
+  const vehicleName = $("#vehicleName").val().trim() || getNextVehicleName();
+  const capacity = parseInt($("#vehicleCapacity").val());
+  const lat = parseFloat($("#vehicleHomeLat").val());
+  const lng = parseFloat($("#vehicleHomeLng").val());
+  const departureTime = $("#vehicleDepartureTime").val();
+
+  if (!capacity || capacity < 1) {
+    alert("Please enter a valid capacity (minimum 1).");
+    return;
+  }
+  if (isNaN(lat) || isNaN(lng)) {
+    alert("Please set a valid home location by clicking on the map or entering coordinates.");
+    return;
+  }
+  if (!departureTime) {
+    alert("Please set a departure time.");
+    return;
+  }
+
+  // Generate new vehicle ID
+  const maxId = Math.max(...loadedRoutePlan.vehicles.map(v => parseInt(v.id)), 0);
+  const newId = String(maxId + 1);
+
+  // Format departure time
+  const formattedDeparture = JSJoda.LocalDateTime.parse(
+    departureTime,
+    JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm')
+  ).format(JSJoda.DateTimeFormatter.ISO_LOCAL_DATE_TIME);
+
+  // Create new vehicle
+  const newVehicle = {
+    id: newId,
+    name: vehicleName,
+    capacity: capacity,
+    homeLocation: [lat, lng],
+    departureTime: formattedDeparture,
+    visits: [],
+    totalDemand: 0,
+    totalDrivingTimeSeconds: 0,
+    arrivalTime: formattedDeparture
+  };
+
+  // Add to solution
+  loadedRoutePlan.vehicles.push(newVehicle);
+
+  // Close modal and refresh
+  $("#addVehicleModal").modal("hide");
+  addingVehicleMode = false;
+
+  if (tempVehicleMarker) {
+    map.removeLayer(tempVehicleMarker);
+    tempVehicleMarker = null;
+  }
+
+  // Refresh display
+  await renderRoutes(loadedRoutePlan);
+  renderTimelines(loadedRoutePlan);
+
+  showNotification(`Vehicle "${vehicleName}" added successfully!`, "success");
+}
+
+async function removeLastVehicle() {
+  if (optimizing) {
+    alert("Cannot remove vehicles while solving. Please stop solving first.");
+    return;
+  }
+  if (!loadedRoutePlan || loadedRoutePlan.vehicles.length <= 1) {
+    alert("Cannot remove the last vehicle. At least one vehicle is required.");
+    return;
+  }
+
+  const lastVehicle = loadedRoutePlan.vehicles[loadedRoutePlan.vehicles.length - 1];
+
+  if (lastVehicle.visits && lastVehicle.visits.length > 0) {
+    if (!confirm(`Vehicle ${lastVehicle.id} has ${lastVehicle.visits.length} assigned visits. These will become unassigned. Continue?`)) {
+      return;
+    }
+    // Unassign visits from the vehicle
+    lastVehicle.visits.forEach(visitId => {
+      const visit = loadedRoutePlan.visits.find(v => v.id === visitId);
+      if (visit) {
+        visit.vehicle = null;
+        visit.previousVisit = null;
+        visit.nextVisit = null;
+        visit.arrivalTime = null;
+        visit.departureTime = null;
+      }
+    });
+  }
+
+  // Remove vehicle
+  loadedRoutePlan.vehicles.pop();
+
+  // Remove marker
+  const marker = homeLocationMarkerByIdMap.get(lastVehicle.id);
+  if (marker) {
+    homeLocationGroup.removeLayer(marker);
+    homeLocationMarkerByIdMap.delete(lastVehicle.id);
+  }
+
+  // Refresh display
+  await renderRoutes(loadedRoutePlan);
+  renderTimelines(loadedRoutePlan);
+
+  showNotification(`Vehicle "${lastVehicle.name || lastVehicle.id}" removed.`, "info");
+}
+
+async function removeVehicle(vehicleId) {
+  if (optimizing) {
+    alert("Cannot remove vehicles while solving. Please stop solving first.");
+    return;
+  }
+
+  const vehicleIndex = loadedRoutePlan.vehicles.findIndex(v => v.id === vehicleId);
+  if (vehicleIndex === -1) return;
+
+  if (loadedRoutePlan.vehicles.length <= 1) {
+    alert("Cannot remove the last vehicle. At least one vehicle is required.");
+    return;
+  }
+
+  const vehicle = loadedRoutePlan.vehicles[vehicleIndex];
+
+  if (vehicle.visits && vehicle.visits.length > 0) {
+    if (!confirm(`Vehicle ${vehicle.id} has ${vehicle.visits.length} assigned visits. These will become unassigned. Continue?`)) {
+      return;
+    }
+    // Unassign visits
+    vehicle.visits.forEach(visitId => {
+      const visit = loadedRoutePlan.visits.find(v => v.id === visitId);
+      if (visit) {
+        visit.vehicle = null;
+        visit.previousVisit = null;
+        visit.nextVisit = null;
+        visit.arrivalTime = null;
+        visit.departureTime = null;
+      }
+    });
+  }
+
+  // Remove vehicle
+  loadedRoutePlan.vehicles.splice(vehicleIndex, 1);
+
+  // Remove marker
+  const marker = homeLocationMarkerByIdMap.get(vehicleId);
+  if (marker) {
+    homeLocationGroup.removeLayer(marker);
+    homeLocationMarkerByIdMap.delete(vehicleId);
+  }
+
+  // Refresh display
+  await renderRoutes(loadedRoutePlan);
+  renderTimelines(loadedRoutePlan);
+
+  showNotification(`Vehicle "${vehicle.name || vehicleId}" removed.`, "info");
+}
+
+function showNotification(message, type = "info") {
+  const alertClass = type === "success" ? "alert-success" : type === "error" ? "alert-danger" : "alert-info";
+  const icon = type === "success" ? "fa-check-circle" : type === "error" ? "fa-exclamation-circle" : "fa-info-circle";
+
+  const notification = $(`
+    <div class="alert ${alertClass} alert-dismissible fade show" role="alert" style="min-width: 300px;">
+      <i class="fas ${icon} me-2"></i>${message}
+      <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
+    </div>
+  `);
+
+  $("#notificationPanel").append(notification);
+
+  // Auto-dismiss after 3 seconds
+  setTimeout(() => {
+    notification.alert('close');
+  }, 3000);
+}
+
+/*************************************** Route Highlighting **************************************/
+
+function toggleVehicleHighlight(vehicleId) {
+  if (highlightedVehicleId === vehicleId) {
+    // Already highlighted - clear it
+    clearRouteHighlight();
+  } else {
+    // Highlight this vehicle's route
+    highlightVehicleRoute(vehicleId);
+  }
+}
+
+function clearRouteHighlight() {
+  // Remove number markers
+  routeNumberMarkers.forEach(marker => map.removeLayer(marker));
+  routeNumberMarkers = [];
+
+  // Reset all vehicle icons to normal and restore opacity
+  if (loadedRoutePlan) {
+    loadedRoutePlan.vehicles.forEach(vehicle => {
+      const marker = homeLocationMarkerByIdMap.get(vehicle.id);
+      if (marker) {
+        marker.setIcon(createVehicleHomeIcon(vehicle, false));
+        marker.setOpacity(1);
+      }
+    });
+
+    // Reset all visit markers to normal and restore opacity
+    loadedRoutePlan.visits.forEach(visit => {
+      const marker = visitMarkerByIdMap.get(visit.id);
+      if (marker) {
+        const customerType = getCustomerType(visit);
+        const isAssigned = visit.vehicle != null;
+        marker.setIcon(createCustomerTypeIcon(customerType, isAssigned, false));
+        marker.setOpacity(1);
+      }
+    });
+  }
+
+  // Reset route lines
+  renderRouteLines();
+
+  // Update vehicle table highlighting
+  $("#vehicles tr").removeClass("table-active");
+
+  highlightedVehicleId = null;
+}
+
+function highlightVehicleRoute(vehicleId) {
+  // Clear any existing highlight first
+  clearRouteHighlight();
+
+  highlightedVehicleId = vehicleId;
+
+  if (!loadedRoutePlan) return;
+
+  const vehicle = loadedRoutePlan.vehicles.find(v => v.id === vehicleId);
+  if (!vehicle) return;
+
+  const vehicleColor = colorByVehicle(vehicle);
+
+  // Highlight the vehicle's home marker
+  const homeMarker = homeLocationMarkerByIdMap.get(vehicleId);
+  if (homeMarker) {
+    homeMarker.setIcon(createVehicleHomeIcon(vehicle, true));
+  }
+
+  // Dim other vehicles
+  loadedRoutePlan.vehicles.forEach(v => {
+    if (v.id !== vehicleId) {
+      const marker = homeLocationMarkerByIdMap.get(v.id);
+      if (marker) {
+        marker.setIcon(createVehicleHomeIcon(v, false));
+        marker.setOpacity(0.3);
+      }
+    }
+  });
+
+  // Get visit order for this vehicle
+  const visitByIdMap = new Map(loadedRoutePlan.visits.map(v => [v.id, v]));
+  const vehicleVisits = vehicle.visits.map(visitId => visitByIdMap.get(visitId)).filter(v => v);
+
+  // Highlight and number the visits on this route
+  let stopNumber = 1;
+  vehicleVisits.forEach(visit => {
+    const marker = visitMarkerByIdMap.get(visit.id);
+    if (marker) {
+      const customerType = getCustomerType(visit);
+      marker.setIcon(createCustomerTypeIcon(customerType, true, true, vehicleColor));
+      marker.setOpacity(1);
+
+      // Add number marker
+      const numberMarker = L.marker(visit.location, {
+        icon: createRouteNumberIcon(stopNumber, vehicleColor),
+        interactive: false,
+        zIndexOffset: 1000
+      });
+      numberMarker.addTo(map);
+      routeNumberMarkers.push(numberMarker);
+      stopNumber++;
+    }
+  });
+
+  // Dim visits not on this route
+  loadedRoutePlan.visits.forEach(visit => {
+    if (!vehicle.visits.includes(visit.id)) {
+      const marker = visitMarkerByIdMap.get(visit.id);
+      if (marker) {
+        marker.setOpacity(0.25);
+      }
+    }
+  });
+
+  // Highlight just this route, dim others
+  renderRouteLines(vehicleId);
+
+  // Highlight the row in the vehicle table
+  $("#vehicles tr").removeClass("table-active");
+  $(`#vehicle-row-${vehicleId}`).addClass("table-active");
+
+  // Add start marker (S) at depot
+  const startMarker = L.marker(vehicle.homeLocation, {
+    icon: createRouteNumberIcon("S", vehicleColor),
+    interactive: false,
+    zIndexOffset: 1000
+  });
+  startMarker.addTo(map);
+  routeNumberMarkers.push(startMarker);
+}
+
+function createRouteNumberIcon(number, color) {
+  return L.divIcon({
+    className: 'route-number-marker',
+    html: `<div style="
+      background-color: ${color};
+      color: white;
+      font-weight: bold;
+      font-size: 12px;
+      width: 22px;
+      height: 22px;
+      border-radius: 50%;
+      border: 2px solid white;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.4);
+      margin-left: 16px;
+      margin-top: -28px;
+    ">${number}</div>`,
+    iconSize: [22, 22],
+    iconAnchor: [0, 0]
+  });
+}
+
+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) {
+    const homeLocation = vehicle.homeLocation;
+    const locations = vehicle.visits.map(visitId => visitByIdMap.get(visitId)?.location).filter(l => l);
+
+    const isHighlighted = highlightedId === null || vehicle.id === highlightedId;
+    const color = colorByVehicle(vehicle);
+    const weight = isHighlighted && highlightedId !== null ? 5 : 3;
+    const opacity = isHighlighted ? 1 : 0.2;
+
+    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,
+        opacity: opacity
+      }).addTo(routeGroup);
+    }
+  }
+}
+
+function colorByVehicle(vehicle) {
+  return vehicle === null ? null : pickColor("vehicle" + vehicle.id);
+}
+
+// Customer type definitions matching demo_data.py
+const CUSTOMER_TYPES = {
+  RESTAURANT: { label: "Restaurant", icon: "fa-utensils", color: "#f59e0b", windowStart: "06:00", windowEnd: "10:00", minService: 20, maxService: 40 },
+  BUSINESS: { label: "Business", icon: "fa-building", color: "#3b82f6", windowStart: "09:00", windowEnd: "17:00", minService: 15, maxService: 30 },
+  RESIDENTIAL: { label: "Residential", icon: "fa-home", color: "#10b981", windowStart: "17:00", windowEnd: "20:00", minService: 5, maxService: 10 },
+};
+
+function getCustomerType(visit) {
+  const startTime = showTimeOnly(visit.minStartTime).toString();
+  const endTime = showTimeOnly(visit.maxEndTime).toString();
+
+  for (const [type, config] of Object.entries(CUSTOMER_TYPES)) {
+    if (startTime === config.windowStart && endTime === config.windowEnd) {
+      return { type, ...config };
+    }
+  }
+  return { type: "UNKNOWN", label: "Custom", icon: "fa-question", color: "#6b7280", windowStart: startTime, windowEnd: endTime };
+}
+
+function formatDrivingTime(drivingTimeInSeconds) {
+  return `${Math.floor(drivingTimeInSeconds / 3600)}h ${Math.round((drivingTimeInSeconds % 3600) / 60)}m`;
+}
+
+function homeLocationPopupContent(vehicle) {
+  const color = colorByVehicle(vehicle);
+  const visitCount = vehicle.visits ? vehicle.visits.length : 0;
+  const vehicleName = vehicle.name || `Vehicle ${vehicle.id}`;
+  return `<div style="min-width: 150px;">
+    <h5 style="color: ${color};"><i class="fas fa-truck"></i> ${vehicleName}</h5>
+    <p class="mb-1"><strong>Depot Location</strong></p>
+    <p class="mb-1"><i class="fas fa-box"></i> Capacity: ${vehicle.capacity}</p>
+    <p class="mb-1"><i class="fas fa-route"></i> Visits: ${visitCount}</p>
+    <p class="mb-0"><i class="fas fa-clock"></i> Departs: ${showTimeOnly(vehicle.departureTime)}</p>
+  </div>`;
+}
+
+function visitPopupContent(visit) {
+  const customerType = getCustomerType(visit);
+  const serviceDurationMinutes = Math.round(visit.serviceDuration / 60);
+  const arrival = visit.arrivalTime
+    ? `<h6>Arrival at ${showTimeOnly(visit.arrivalTime)}.</h6>`
+    : "";
+  return `<h5><i class="fas ${customerType.icon}" style="color: ${customerType.color}"></i> ${visit.name}</h5>
+    <h6><span class="badge" style="background-color: ${customerType.color}">${customerType.label}</span></h6>
+    <h6>Cargo: ${visit.demand} units</h6>
+    <h6>Service time: ${serviceDurationMinutes} min</h6>
+    <h6>Window: ${showTimeOnly(visit.minStartTime)} - ${showTimeOnly(visit.maxEndTime)}</h6>
+    ${arrival}`;
+}
+
+function showTimeOnly(localDateTimeString) {
+  return JSJoda.LocalDateTime.parse(localDateTimeString).toLocalTime();
+}
+
+function createVehicleHomeIcon(vehicle, isHighlighted = false) {
+  const color = colorByVehicle(vehicle);
+  const size = isHighlighted ? 36 : 28;
+  const fontSize = isHighlighted ? 14 : 11;
+  const borderWidth = isHighlighted ? 4 : 3;
+  const shadow = isHighlighted
+    ? `0 0 0 4px ${color}40, 0 4px 8px rgba(0,0,0,0.5)`
+    : '0 2px 4px rgba(0,0,0,0.4)';
+
+  return L.divIcon({
+    className: 'vehicle-home-marker',
+    html: `<div style="
+      background-color: ${color};
+      border: ${borderWidth}px solid white;
+      border-radius: 50%;
+      width: ${size}px;
+      height: ${size}px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      box-shadow: ${shadow};
+      transition: all 0.2s ease;
+    "><i class="fas fa-truck" style="color: white; font-size: ${fontSize}px;"></i></div>`,
+    iconSize: [size, size],
+    iconAnchor: [size/2, size/2],
+    popupAnchor: [0, -size/2]
+  });
+}
+
+function getHomeLocationMarker(vehicle) {
+  let marker = homeLocationMarkerByIdMap.get(vehicle.id);
+  if (marker) {
+    marker.setIcon(createVehicleHomeIcon(vehicle));
+    return marker;
+  }
+  marker = L.marker(vehicle.homeLocation, {
+    icon: createVehicleHomeIcon(vehicle)
+  });
+  marker.addTo(homeLocationGroup).bindPopup();
+  homeLocationMarkerByIdMap.set(vehicle.id, marker);
+  return marker;
+}
+
+function createCustomerTypeIcon(customerType, isAssigned = false, isHighlighted = false, highlightColor = null) {
+  const borderColor = isHighlighted && highlightColor
+    ? highlightColor
+    : (isAssigned ? customerType.color : '#6b7280');
+  const size = isHighlighted ? 38 : 32;
+  const fontSize = isHighlighted ? 16 : 14;
+  const borderWidth = isHighlighted ? 4 : 3;
+  const shadow = isHighlighted
+    ? `0 0 0 4px ${highlightColor}40, 0 4px 8px rgba(0,0,0,0.4)`
+    : '0 2px 4px rgba(0,0,0,0.3)';
+
+  return L.divIcon({
+    className: 'customer-marker',
+    html: `<div style="
+      background-color: white;
+      border: ${borderWidth}px solid ${borderColor};
+      border-radius: 50%;
+      width: ${size}px;
+      height: ${size}px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      box-shadow: ${shadow};
+      transition: all 0.2s ease;
+    "><i class="fas ${customerType.icon}" style="color: ${customerType.color}; font-size: ${fontSize}px;"></i></div>`,
+    iconSize: [size, size],
+    iconAnchor: [size/2, size/2],
+    popupAnchor: [0, -size/2]
+  });
+}
+
+function getVisitMarker(visit) {
+  let marker = visitMarkerByIdMap.get(visit.id);
+  const customerType = getCustomerType(visit);
+  const isAssigned = visit.vehicle != null;
+
+  if (marker) {
+    // Update icon if assignment status changed
+    marker.setIcon(createCustomerTypeIcon(customerType, isAssigned));
+    return marker;
+  }
+
+  marker = L.marker(visit.location, {
+    icon: createCustomerTypeIcon(customerType, isAssigned)
+  });
+  marker.addTo(visitGroup).bindPopup();
+  visitMarkerByIdMap.set(visit.id, marker);
+  return marker;
+}
+
+async function renderRoutes(solution) {
+  if (!initialized) {
+    const bounds = [solution.southWestCorner, solution.northEastCorner];
+    map.fitBounds(bounds);
+  }
+  // Vehicles
+  vehiclesTable.children().remove();
+  const canRemove = solution.vehicles.length > 1;
+  solution.vehicles.forEach(function (vehicle) {
+    getHomeLocationMarker(vehicle).setPopupContent(
+      homeLocationPopupContent(vehicle),
+    );
+    const { id, capacity, totalDemand, totalDrivingTimeSeconds } = vehicle;
+    const percentage = Math.min((totalDemand / capacity) * 100, 100);
+    const overCapacity = totalDemand > capacity;
+    const color = colorByVehicle(vehicle);
+    const progressBarColor = overCapacity ? 'bg-danger' : '';
+    const isHighlighted = highlightedVehicleId === id;
+    const visitCount = vehicle.visits ? vehicle.visits.length : 0;
+    const vehicleName = vehicle.name || `Vehicle ${id}`;
+
+    vehiclesTable.append(`
+      <tr id="vehicle-row-${id}" class="vehicle-row ${isHighlighted ? 'table-active' : ''}" style="cursor: pointer;">
+        <td onclick="toggleVehicleHighlight('${id}')">
+          <div style="background-color: ${color}; width: 1.5rem; height: 1.5rem; border-radius: 50%; display: flex; align-items: center; justify-content: center; ${isHighlighted ? 'box-shadow: 0 0 0 3px ' + color + '40;' : ''}">
+            <i class="fas fa-truck" style="color: white; font-size: 0.65rem;"></i>
+          </div>
+        </td>
+        <td onclick="toggleVehicleHighlight('${id}')">
+          <strong>${vehicleName}</strong>
+          <br><small class="text-muted">${visitCount} stops</small>
+        </td>
+        <td onclick="toggleVehicleHighlight('${id}')">
+          <div class="progress" style="height: 18px;" data-bs-toggle="tooltip" data-bs-placement="left"
+            title="Cargo: ${totalDemand} / Capacity: ${capacity}${overCapacity ? ' (OVER CAPACITY!)' : ''}">
+            <div class="progress-bar ${progressBarColor}" role="progressbar" style="width: ${percentage}%; font-size: 0.7rem; transition: width 0.3s ease;">
+              ${totalDemand}/${capacity}
+            </div>
+          </div>
+        </td>
+        <td onclick="toggleVehicleHighlight('${id}')" style="font-size: 0.85rem;">
+          ${formatDrivingTime(totalDrivingTimeSeconds)}
+        </td>
+        <td>
+          ${canRemove ? `<button class="btn btn-sm btn-outline-danger p-0 px-1" onclick="event.stopPropagation(); removeVehicle('${id}')" title="Remove vehicle ${vehicleName}">
+            <i class="fas fa-times" style="font-size: 0.7rem;"></i>
+          </button>` : ''}
+        </td>
+      </tr>`);
+  });
+  // Visits
+  solution.visits.forEach(function (visit) {
+    getVisitMarker(visit).setPopupContent(visitPopupContent(visit));
+  });
+  // 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: ?");
+  $("#drivingTime").text(formatDrivingTime(solution.totalDrivingTimeSeconds));
+}
+
+function renderTimelines(routePlan) {
+  byVehicleGroupData.clear();
+  byVisitGroupData.clear();
+  byVehicleItemData.clear();
+  byVisitItemData.clear();
+
+  // 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();
+
+  // Build stop order for each visit
+  routePlan.vehicles.forEach(vehicle => {
+    vehicle.visits.forEach((visitId, index) => {
+      visitOrderMap.set(visitId, index + 1);
+    });
+  });
+
+  // Vehicle groups with names and status summary
+  $.each(routePlan.vehicles, function (index, vehicle) {
+    const vehicleName = vehicle.name || `Vehicle ${vehicle.id}`;
+    const { totalDemand, capacity } = vehicle;
+    const percentage = Math.min((totalDemand / capacity) * 100, 100);
+    const overCapacity = totalDemand > capacity;
+
+    // Count late visits for this vehicle
+    const vehicleVisits = vehicle.visits.map(id => visitById.get(id)).filter(v => v);
+    const lateCount = vehicleVisits.filter(v => {
+      if (!v.departureTime) return false;
+      const departure = JSJoda.LocalDateTime.parse(v.departureTime);
+      const maxEnd = JSJoda.LocalDateTime.parse(v.maxEndTime);
+      return departure.isAfter(maxEnd);
+    }).length;
+
+    const statusIcon = lateCount > 0
+      ? `<i class="fas fa-exclamation-triangle timeline-status-late timeline-status-icon" title="${lateCount} late"></i>`
+      : vehicle.visits.length > 0
+        ? `<i class="fas fa-check-circle timeline-status-ontime timeline-status-icon" title="All on-time"></i>`
+        : '';
+
+    const progressBarClass = overCapacity ? 'bg-danger' : '';
+
+    const vehicleWithLoad = `
+      <h5 class="card-title mb-1">${vehicleName}${statusIcon}</h5>
+      <div class="progress" style="height: 16px;" title="Cargo: ${totalDemand} / ${capacity}">
+        <div class="progress-bar ${progressBarClass}" role="progressbar" style="width: ${percentage}%">
+          ${totalDemand}/${capacity}
+        </div>
+      </div>`;
+    byVehicleGroupData.add({ id: vehicle.id, content: vehicleWithLoad });
+  });
+
+  $.each(routePlan.visits, function (index, visit) {
+    const minStartTime = JSJoda.LocalDateTime.parse(visit.minStartTime);
+    const maxEndTime = JSJoda.LocalDateTime.parse(visit.maxEndTime);
+    const serviceDuration = JSJoda.Duration.ofSeconds(visit.serviceDuration);
+    const customerType = getCustomerType(visit);
+    const stopNumber = visitOrderMap.get(visit.id);
+
+    const visitGroupElement = $(`<div/>`).append(
+      $(`<h5 class="card-title mb-1"/>`).html(
+        `<i class="fas ${customerType.icon}" style="color: ${customerType.color}"></i> ${visit.name}`
+      ),
+    ).append(
+      $(`<small class="text-muted"/>`).text(customerType.label)
+    );
+    byVisitGroupData.add({
+      id: visit.id,
+      content: visitGroupElement.html(),
+    });
+
+    // Time window per visit.
+    byVisitItemData.add({
+      id: visit.id + "_readyToDue",
+      group: visit.id,
+      start: visit.minStartTime,
+      end: visit.maxEndTime,
+      type: "background",
+      style: "background-color: #8AE23433",
+    });
+
+    if (visit.vehicle == null) {
+      const byJobJobElement = $(`<div/>`).append(
+        $(`<span/>`).html(`<i class="fas fa-exclamation-circle text-danger me-1"></i>Unassigned`),
+      );
+
+      // Unassigned are shown at the beginning of the visit's time window; the length is the service duration.
+      byVisitItemData.add({
+        id: visit.id + "_unassigned",
+        group: visit.id,
+        content: byJobJobElement.html(),
+        start: minStartTime.toString(),
+        end: minStartTime.plus(serviceDuration).toString(),
+        style: "background-color: #EF292999",
+      });
+    } else {
+      const arrivalTime = JSJoda.LocalDateTime.parse(visit.arrivalTime);
+      const beforeReady = arrivalTime.isBefore(minStartTime);
+      const departureTime = JSJoda.LocalDateTime.parse(visit.departureTime);
+      const afterDue = departureTime.isAfter(maxEndTime);
+
+      // Get vehicle info for display
+      const vehicleInfo = vehicleById.get(visit.vehicle);
+      const vehicleName = vehicleInfo ? (vehicleInfo.name || `Vehicle ${visit.vehicle}`) : `Vehicle ${visit.vehicle}`;
+
+      // Stop badge for service segment
+      const stopBadge = stopNumber ? `<span class="timeline-stop-badge">${stopNumber}</span>` : '';
+
+      // Status icon based on timing
+      const statusIcon = afterDue
+        ? `<i class="fas fa-exclamation-triangle timeline-status-late timeline-status-icon" title="Late"></i>`
+        : `<i class="fas fa-check timeline-status-ontime timeline-status-icon" title="On-time"></i>`;
+
+      const byVehicleElement = $(`<div/>`)
+        .append($(`<span/>`).html(
+          `${stopBadge}<i class="fas ${customerType.icon}" style="color: ${customerType.color}"></i> ${visit.name}${statusIcon}`
+        ));
+
+      const byVisitElement = $(`<div/>`)
+        .append(
+          $(`<span/>`).html(
+            `${stopBadge}${vehicleName}${statusIcon}`
+          ),
+        );
+
+      const byVehicleTravelElement = $(`<div/>`).append(
+        $(`<span/>`).html(`<i class="fas fa-route text-warning me-1"></i>Travel`),
+      );
+
+      const previousDeparture = arrivalTime.minusSeconds(
+        visit.drivingTimeSecondsFromPreviousStandstill,
+      );
+      byVehicleItemData.add({
+        id: visit.id + "_travel",
+        group: visit.vehicle,
+        subgroup: visit.vehicle,
+        content: byVehicleTravelElement.html(),
+        start: previousDeparture.toString(),
+        end: visit.arrivalTime,
+        style: "background-color: #f7dd8f90",
+      });
+
+      if (beforeReady) {
+        const byVehicleWaitElement = $(`<div/>`).append(
+          $(`<span/>`).html(`<i class="fas fa-clock timeline-status-early me-1"></i>Wait`),
+        );
+
+        byVehicleItemData.add({
+          id: visit.id + "_wait",
+          group: visit.vehicle,
+          subgroup: visit.vehicle,
+          content: byVehicleWaitElement.html(),
+          start: visit.arrivalTime,
+          end: visit.minStartTime,
+          style: "background-color: #93c5fd80",
+        });
+      }
+
+      let serviceElementBackground = afterDue ? "#EF292999" : "#83C15955";
+
+      byVehicleItemData.add({
+        id: visit.id + "_service",
+        group: visit.vehicle,
+        subgroup: visit.vehicle,
+        content: byVehicleElement.html(),
+        start: visit.startServiceTime,
+        end: visit.departureTime,
+        style: "background-color: " + serviceElementBackground,
+      });
+      byVisitItemData.add({
+        id: visit.id,
+        group: visit.id,
+        content: byVisitElement.html(),
+        start: visit.startServiceTime,
+        end: visit.departureTime,
+        style: "background-color: " + serviceElementBackground,
+      });
+    }
+  });
+
+  $.each(routePlan.vehicles, function (index, vehicle) {
+    if (vehicle.visits.length > 0) {
+      let lastVisit = routePlan.visits
+        .filter(
+          (visit) => visit.id == vehicle.visits[vehicle.visits.length - 1],
+        )
+        .pop();
+      if (lastVisit) {
+        byVehicleItemData.add({
+          id: vehicle.id + "_travelBackToHomeLocation",
+          group: vehicle.id,
+          subgroup: vehicle.id,
+          content: $(`<div/>`)
+            .append($(`<span/>`).html(`<i class="fas fa-home text-secondary me-1"></i>Return`))
+            .html(),
+          start: lastVisit.departureTime,
+          end: vehicle.arrivalTime,
+          style: "background-color: #f7dd8f90",
+        });
+      }
+    }
+  });
+
+  if (!initialized) {
+    if (byVehicleTimeline) {
+      byVehicleTimeline.setWindow(
+        routePlan.startDateTime,
+        routePlan.endDateTime,
+      );
+    }
+    if (byVisitTimeline) {
+      byVisitTimeline.setWindow(routePlan.startDateTime, routePlan.endDateTime);
+    }
+  }
+}
+
+function analyze() {
+  // see score-analysis.js
+  analyzeScore(loadedRoutePlan, "/route-plans/analyze");
+}
+
+function openRecommendationModal(lat, lng) {
+  if (!('score' in loadedRoutePlan) || optimizing) {
+    map.removeLayer(visitMarker);
+    visitMarker = null;
+    let message = "Please click the Solve button before adding new visits.";
+    if (optimizing) {
+      message = "Please wait for the solving process to finish.";
+    }
+    alert(message);
+    return;
+  }
+  // see recommended-fit.js
+  const visitId = Math.max(...loadedRoutePlan.visits.map(c => parseInt(c.id))) + 1;
+  newVisit = {id: visitId, location: [lat, lng]};
+  addNewVisit(visitId, lat, lng, map, visitMarker);
+}
+
+function getRecommendationsModal() {
+  let formValid = true;
+  formValid = validateFormField(newVisit, 'name', '#inputName') && formValid;
+  formValid = validateFormField(newVisit, 'demand', '#inputDemand') && formValid;
+  formValid = validateFormField(newVisit, 'minStartTime', '#inputMinStartTime') && formValid;
+  formValid = validateFormField(newVisit, 'maxEndTime', '#inputMaxStartTime') && formValid;
+  formValid = validateFormField(newVisit, 'serviceDuration', '#inputDuration') && formValid;
+
+  if (formValid) {
+    const updatedMinStartTime = JSJoda.LocalDateTime.parse(
+      newVisit['minStartTime'],
+      JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm')
+    ).format(JSJoda.DateTimeFormatter.ISO_LOCAL_DATE_TIME);
+
+    const updatedMaxEndTime = JSJoda.LocalDateTime.parse(
+      newVisit['maxEndTime'],
+      JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm')
+    ).format(JSJoda.DateTimeFormatter.ISO_LOCAL_DATE_TIME);
+
+    const updatedVisit = {
+      ...newVisit,
+      serviceDuration: parseInt(newVisit['serviceDuration']) * 60, // Convert minutes to seconds
+      minStartTime: updatedMinStartTime,
+      maxEndTime: updatedMaxEndTime
+    };
+
+    let updatedVisitList = [...loadedRoutePlan['visits']];
+    updatedVisitList.push(updatedVisit);
+    let updatedSolution = {...loadedRoutePlan, visits: updatedVisitList};
+
+    // see recommended-fit.js
+    requestRecommendations(updatedVisit.id, updatedSolution, "/route-plans/recommendation");
+  }
+}
+
+function validateFormField(target, fieldName, inputName) {
+  target[fieldName] = $(inputName).val();
+  if ($(inputName).val() == "") {
+    $(inputName).addClass("is-invalid");
+  } else {
+    $(inputName).removeClass("is-invalid");
+  }
+  return $(inputName).val() != "";
+}
+
+function applyRecommendationModal(recommendations) {
+  let checkedRecommendation = null;
+  recommendations.forEach((recommendation, index) => {
+    if ($('#option' + index).is(":checked")) {
+      checkedRecommendation = recommendations[index];
+    }
+  });
+
+  if (!checkedRecommendation) {
+    alert("Please select a recommendation.");
+    return;
+  }
+
+  const updatedMinStartTime = JSJoda.LocalDateTime.parse(
+    newVisit['minStartTime'],
+    JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm')
+  ).format(JSJoda.DateTimeFormatter.ISO_LOCAL_DATE_TIME);
+
+  const updatedMaxEndTime = JSJoda.LocalDateTime.parse(
+    newVisit['maxEndTime'],
+    JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm')
+  ).format(JSJoda.DateTimeFormatter.ISO_LOCAL_DATE_TIME);
+
+  const updatedVisit = {
+    ...newVisit,
+    serviceDuration: parseInt(newVisit['serviceDuration']) * 60, // Convert minutes to seconds
+    minStartTime: updatedMinStartTime,
+    maxEndTime: updatedMaxEndTime
+  };
+
+  let updatedVisitList = [...loadedRoutePlan['visits']];
+  updatedVisitList.push(updatedVisit);
+  let updatedSolution = {...loadedRoutePlan, visits: updatedVisitList};
+
+  // see recommended-fit.js
+  applyRecommendation(
+    updatedSolution,
+    newVisit.id,
+    checkedRecommendation.proposition.vehicleId,
+    checkedRecommendation.proposition.index,
+    "/route-plans/recommendation/apply"
+  );
+}
+
+async function updateSolutionWithNewVisit(newSolution) {
+  loadedRoutePlan = newSolution;
+  await renderRoutes(newSolution);
+  renderTimelines(newSolution);
+  $('#newVisitModal').modal('hide');
+}
+
+// TODO: move the general functionality to the webjar.
+
+function setupAjax() {
+  $.ajaxSetup({
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json,text/plain", // plain text is required by solve() returning UUID of the solver job
+    },
+  });
+
+  // Extend jQuery to support $.put() and $.delete()
+  jQuery.each(["put", "delete"], function (i, method) {
+    jQuery[method] = function (url, data, callback, type) {
+      if (jQuery.isFunction(data)) {
+        type = type || callback;
+        callback = data;
+        data = undefined;
+      }
+      return jQuery.ajax({
+        url: url,
+        type: method,
+        dataType: type,
+        data: data,
+        success: callback,
+      });
+    };
+  });
+}
+
+function solve() {
+  // Clear geometry cache - will be refreshed when solution updates
+  routeGeometries = null;
+
+  $.ajax({
+    url: "/route-plans",
+    type: "POST",
+    data: JSON.stringify(loadedRoutePlan),
+    contentType: "application/json",
+    dataType: "text",
+    success: function (data) {
+      scheduleId = data.replace(/"/g, ""); // Remove quotes from UUID
+      refreshSolvingButtons(true);
+    },
+    error: function (xhr, ajaxOptions, thrownError) {
+      showError("Start solving failed.", xhr);
+      refreshSolvingButtons(false);
+    },
+  });
+}
+
+function refreshSolvingButtons(solving) {
+  optimizing = solving;
+  if (solving) {
+    $("#solveButton").hide();
+    $("#visitButton").hide();
+    $("#stopSolvingButton").show();
+    $("#solvingSpinner").addClass("active");
+    $("#mapHint").addClass("hidden");
+    if (autoRefreshIntervalId == null) {
+      autoRefreshIntervalId = setInterval(refreshRoutePlan, 2000);
+    }
+  } else {
+    $("#solveButton").show();
+    $("#visitButton").show();
+    $("#stopSolvingButton").hide();
+    $("#solvingSpinner").removeClass("active");
+    $("#mapHint").removeClass("hidden");
+    if (autoRefreshIntervalId != null) {
+      clearInterval(autoRefreshIntervalId);
+      autoRefreshIntervalId = null;
+    }
+  }
+}
+
+async function refreshRoutePlan() {
+  let path = "/route-plans/" + scheduleId;
+  let isLoadingDemoData = scheduleId === null;
+
+  if (isLoadingDemoData) {
+    if (demoDataId === null) {
+      alert("Please select a test data set.");
+      return;
+    }
+
+    // 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;
+  }
+
+  // Loading existing route plan (during solving)
+  try {
+    const routePlan = await $.getJSON(path);
+    loadedRoutePlan = routePlan;
+    refreshSolvingButtons(
+      routePlan.solverStatus != null &&
+        routePlan.solverStatus !== "NOT_SOLVING",
+    );
+    await renderRoutes(routePlan);
+    renderTimelines(routePlan);
+    initialized = true;
+  } catch (error) {
+    showError("Getting route plan has failed.", error);
+    refreshSolvingButtons(false);
+  }
+}
+
+function stopSolving() {
+  $.delete("/route-plans/" + scheduleId, function () {
+    refreshSolvingButtons(false);
+    refreshRoutePlan();
+  }).fail(function (xhr, ajaxOptions, thrownError) {
+    showError("Stop solving failed.", xhr);
+  });
+}
+
+function fetchDemoData() {
+  $.get("/demo-data", function (data) {
+    data.forEach(function (item) {
+      $("#testDataButton").append(
+        $(
+          '<a id="' +
+            item +
+            'TestData" class="dropdown-item" href="#">' +
+            item +
+            "</a>",
+        ),
+      );
+
+      $("#" + item + "TestData").click(function () {
+        switchDataDropDownItemActive(item);
+        scheduleId = null;
+        demoDataId = item;
+        initialized = false;
+        homeLocationGroup.clearLayers();
+        homeLocationMarkerByIdMap.clear();
+        visitGroup.clearLayers();
+        visitMarkerByIdMap.clear();
+        refreshRoutePlan();
+      });
+    });
+
+    demoDataId = data[0];
+    switchDataDropDownItemActive(demoDataId);
+
+    refreshRoutePlan();
+  }).fail(function (xhr, ajaxOptions, thrownError) {
+    // disable this page as there is no data
+    $("#demo").empty();
+    $("#demo").html(
+      '<h1><p style="justify-content: center">No test data available</p></h1>',
+    );
+  });
+}
+
+function switchDataDropDownItemActive(newItem) {
+  activeCssClass = "active";
+  $("#testDataButton > a." + activeCssClass).removeClass(activeCssClass);
+  $("#" + newItem + "TestData").addClass(activeCssClass);
+}
+
+function copyTextToClipboard(id) {
+  var text = $("#" + id)
+    .text()
+    .trim();
+
+  var dummy = document.createElement("textarea");
+  document.body.appendChild(dummy);
+  dummy.value = text;
+  dummy.select();
+  document.execCommand("copy");
+  document.body.removeChild(dummy);
+}
+
+function replaceQuickstartSolverForgeAutoHeaderFooter() {
+  const solverforgeHeader = $("header#solverforge-auto-header");
+  if (solverforgeHeader != null) {
+    solverforgeHeader.css("background-color", "#ffffff");
+    solverforgeHeader.append(
+      $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg shadow-sm mb-3" style="background-color: #ffffff;">
+          <a class="navbar-brand" href="https://www.solverforge.org">
+            <img src="/webjars/solverforge/img/solverforge-horizontal.svg" alt="SolverForge logo" width="400">
+          </a>
+          <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
+            <span class="navbar-toggler-icon"></span>
+          </button>
+          <div class="collapse navbar-collapse" id="navbarNav">
+            <ul class="nav nav-pills">
+              <li class="nav-item active" id="navUIItem">
+                <button class="nav-link active" id="navUI" data-bs-toggle="pill" data-bs-target="#demo" type="button" style="color: #1f2937;">Demo UI</button>
+              </li>
+              <li class="nav-item" id="navRestItem">
+                <button class="nav-link" id="navRest" data-bs-toggle="pill" data-bs-target="#rest" type="button" style="color: #1f2937;">Guide</button>
+              </li>
+              <li class="nav-item" id="navOpenApiItem">
+                <button class="nav-link" id="navOpenApi" data-bs-toggle="pill" data-bs-target="#openapi" type="button" style="color: #1f2937;">REST API</button>
+              </li>
+            </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
+                  </button>
+                  <div id="testDataButton" class="dropdown-menu" aria-labelledby="dropdownMenuButton"></div>
+              </div>
+          </div>
+        </nav>
+      </div>`),
+    );
+  }
+
+  const solverforgeFooter = $("footer#solverforge-auto-footer");
+  if (solverforgeFooter != null) {
+    solverforgeFooter.append(
+      $(`<footer class="bg-black text-white-50">
+               <div class="container">
+                 <div class="hstack gap-3 p-4">
+                   <div class="ms-auto"><a class="text-white" href="https://www.solverforge.org">SolverForge</a></div>
+                   <div class="vr"></div>
+                   <div><a class="text-white" href="https://www.solverforge.org/docs">Documentation</a></div>
+                   <div class="vr"></div>
+                   <div><a class="text-white" href="https://github.com/SolverForge/solverforge-legacy">Code</a></div>
+                   <div class="vr"></div>
+                   <div class="me-auto"><a class="text-white" href="mailto:info@solverforge.org">Support</a></div>
+                 </div>
+               </div>
+             </footer>`),
+    );
+  }
+}

static/index.html

@@ -0,0 +1,473 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+  <title>Vehicle Routing - SolverForge for Python</title>
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.3/css/bootstrap.min.css">
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/leaflet.css">
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vis-timeline@7.7.2/styles/vis-timeline-graph2d.min.css"
+        integrity="sha256-svzNasPg1yR5gvEaRei2jg+n4Pc3sVyMUWeS6xRAh6U=" crossorigin="anonymous">
+  <link rel="stylesheet" href="/webjars/solverforge/css/solverforge-webui.css"/>
+  <link rel="icon" href="/webjars/solverforge/img/solverforge-favicon.svg" type="image/svg+xml">
+  <style>
+    /* Customer marker icons */
+    .customer-marker, .vehicle-home-marker, .temp-vehicle-marker {
+      background: transparent !important;
+      border: none !important;
+    }
+
+    /* Pulse animation for new vehicle placement */
+    @keyframes pulse {
+      0% { transform: scale(1); box-shadow: 0 2px 4px rgba(0,0,0,0.4); }
+      50% { transform: scale(1.1); box-shadow: 0 4px 8px rgba(99, 102, 241, 0.6); }
+      100% { transform: scale(1); box-shadow: 0 2px 4px rgba(0,0,0,0.4); }
+    }
+
+    /* Customer type buttons in modal */
+    .customer-type-btn {
+      transition: all 0.2s ease;
+      padding: 0.75rem 0.5rem;
+    }
+    .customer-type-btn:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 4px 8px rgba(0,0,0,0.15);
+    }
+
+    /* Vehicle table styling */
+    #vehicles tr.vehicle-row {
+      transition: background-color 0.2s ease;
+    }
+    #vehicles tr.vehicle-row:hover {
+      background-color: rgba(99, 102, 241, 0.1);
+    }
+    #vehicles tr.vehicle-row.table-active {
+      background-color: rgba(99, 102, 241, 0.15) !important;
+    }
+
+    /* Route number markers */
+    .route-number-marker {
+      background: transparent !important;
+      border: none !important;
+    }
+
+    /* Notification panel */
+    #notificationPanel {
+      z-index: 1050;
+    }
+
+    /* Click hint for vehicle rows */
+    #vehicles tr.vehicle-row td:not(:last-child) {
+      cursor: pointer;
+    }
+
+    /* Solving spinner */
+    #solvingSpinner {
+      display: none;
+      width: 1.25rem;
+      height: 1.25rem;
+      border: 2px solid #10b981;
+      border-top-color: transparent;
+      border-radius: 50%;
+      animation: spin 0.75s linear infinite;
+      vertical-align: middle;
+    }
+    #solvingSpinner.active {
+      display: inline-block;
+    }
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    /* Progress bar text should stay horizontal and inside */
+    .progress-bar {
+      overflow: visible;
+      white-space: nowrap;
+    }
+
+    /* Map hint overlay */
+    .map-hint {
+      position: absolute;
+      bottom: 20px;
+      left: 50%;
+      transform: translateX(-50%);
+      background-color: rgba(255, 255, 255, 0.95);
+      padding: 8px 16px;
+      border-radius: 20px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+      font-size: 0.9rem;
+      color: #374151;
+      z-index: 1000;
+      pointer-events: none;
+      transition: opacity 0.3s ease;
+    }
+    .map-hint i {
+      color: #10b981;
+      margin-right: 6px;
+    }
+    .map-hint.hidden {
+      opacity: 0;
+    }
+
+    /* Timeline stop badges */
+    .timeline-stop-badge {
+      background-color: #6366f1;
+      color: white;
+      padding: 1px 6px;
+      border-radius: 10px;
+      font-size: 0.7rem;
+      font-weight: bold;
+      margin-right: 4px;
+    }
+    .timeline-status-icon {
+      margin-left: 4px;
+      font-size: 0.85rem;
+    }
+    .timeline-status-ontime { color: #10b981; }
+    .timeline-status-late { color: #ef4444; }
+    .timeline-status-early { color: #3b82f6; }
+    .vis-item .vis-item-content {
+      font-size: 0.85rem;
+      padding: 2px 4px;
+    }
+    .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>
+
+<header id="solverforge-auto-header">
+  <!-- Filled in by app.js -->
+</header>
+<div class="tab-content">
+  <div id="demo" class="tab-pane fade show active container-fluid">
+    <div class="sticky-top d-flex justify-content-center align-items-center">
+      <div id="notificationPanel" style="position: absolute; top: .5rem;"></div>
+    </div>
+    <h1>Vehicle routing with capacity and time windows</h1>
+    <p>Generate optimal route plan of a vehicle fleet with limited vehicle capacity and time windows.</p>
+    <div class="container-fluid mb-2">
+      <div class="row justify-content-start">
+        <div class="col-9">
+          <ul class="nav nav-pills col" role="tablist">
+            <li class="nav-item" role="presentation">
+              <button class="nav-link active" id="mapTab" data-bs-toggle="tab" data-bs-target="#mapPanel"
+                      type="button"
+                      role="tab" aria-controls="mapPanel" aria-selected="false">Map
+              </button>
+            </li>
+            <li class="nav-item" role="presentation">
+              <button class="nav-link" id="byVehicleTab" data-bs-toggle="tab" data-bs-target="#byVehiclePanel"
+                      type="button" role="tab" aria-controls="byVehiclePanel" aria-selected="false">By vehicle
+              </button>
+            </li>
+            <li class="nav-item" role="presentation">
+              <button class="nav-link" id="byVisitTab" data-bs-toggle="tab" data-bs-target="#byVisitPanel"
+                      type="button" role="tab" aria-controls="byVisitPanel" aria-selected="false">By visit
+              </button>
+            </li>
+          </ul>
+        </div>
+        <div class="col-3">
+          <button id="solveButton" type="button" class="btn btn-success">
+            <i class="fas fa-play"></i> Solve
+          </button>
+          <button id="stopSolvingButton" type="button" class="btn btn-danger p-2">
+            <i class="fas fa-stop"></i> Stop solving
+          </button>
+          <span id="solvingSpinner" class="ms-2"></span>
+          <span id="score" class="score ms-2 align-middle fw-bold">Score: ?</span>
+          <button id="analyzeButton" type="button" class="ms-2 btn btn-secondary">
+            <span class="fas fa-question"></span>
+          </button>
+        </div>
+      </div>
+    </div>
+
+    <div class="tab-content">
+
+      <div class="tab-pane fade show active" id="mapPanel" role="tabpanel" aria-labelledby="mapTab">
+        <div class="row">
+          <div class="col-7 col-lg-8 col-xl-9 position-relative">
+            <div id="map" style="width: 100%; height: 100vh;"></div>
+            <div id="mapHint" class="map-hint">
+              <i class="fas fa-mouse-pointer"></i> Click on the map to add a new visit
+            </div>
+          </div>
+          <div class="col-5 col-lg-4 col-xl-3" style="height: 100vh; overflow-y: scroll;">
+            <div class="row pt-2 row-cols-1">
+              <div class="col">
+                <h5>
+                  Solution summary
+                </h5>
+                <table class="table">
+                  <tr>
+                    <td>Total driving time:</td>
+                    <td><span id="drivingTime">unknown</span></td>
+                  </tr>
+                </table>
+              </div>
+              <div class="col mb-3">
+                <h5>Time Windows</h5>
+                <div class="d-flex flex-column gap-1">
+                  <div><i class="fas fa-utensils" style="color: #f59e0b; width: 20px;"></i> <strong>Restaurant</strong> <small class="text-muted">06:00-10:00 · 20-40 min</small></div>
+                  <div><i class="fas fa-building" style="color: #3b82f6; width: 20px;"></i> <strong>Business</strong> <small class="text-muted">09:00-17:00 · 15-30 min</small></div>
+                  <div><i class="fas fa-home" style="color: #10b981; width: 20px;"></i> <strong>Residential</strong> <small class="text-muted">17:00-20:00 · 5-10 min</small></div>
+                </div>
+              </div>
+              <div class="col">
+                <div class="d-flex justify-content-between align-items-center mb-2">
+                  <div>
+                    <h5 class="mb-0">Vehicles</h5>
+                    <small class="text-muted"><i class="fas fa-hand-pointer"></i> Click to highlight route</small>
+                  </div>
+                  <div class="btn-group btn-group-sm" role="group" aria-label="Vehicle management">
+                    <button type="button" class="btn btn-outline-danger" id="removeVehicleBtn" title="Remove last vehicle">
+                      <i class="fas fa-minus"></i>
+                    </button>
+                    <button type="button" class="btn btn-outline-success" id="addVehicleBtn" title="Add new vehicle">
+                      <i class="fas fa-plus"></i>
+                    </button>
+                  </div>
+                </div>
+                <table class="table-sm w-100">
+                  <thead>
+                  <tr>
+                    <th class="col-1"></th>
+                    <th class="col-3">Name</th>
+                    <th class="col-3">
+                      Cargo
+                      <i class="fas fa-info-circle" data-bs-toggle="tooltip" data-bs-placement="top"
+                         data-html="true"
+                         title="Units to deliver on this route. Each customer requires cargo units (e.g., packages, crates). Bar shows current load vs. vehicle capacity."></i>
+                    </th>
+                    <th class="col-2">Drive</th>
+                    <th class="col-1"></th>
+                  </tr>
+                  </thead>
+                  <tbody id="vehicles"></tbody>
+                </table>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+
+      <div class="tab-pane fade" id="byVehiclePanel" role="tabpanel" aria-labelledby="byVehicleTab">
+      </div>
+      <div class="tab-pane fade" id="byVisitPanel" role="tabpanel" aria-labelledby="byVisitTab">
+      </div>
+    </div>
+  </div>
+
+  <div id="rest" class="tab-pane fade container-fluid">
+    <h1>REST API Guide</h1>
+
+    <h2>Vehicle routing with vehicle capacity and time windows - integration via cURL</h2>
+
+    <h3>1. Download demo data</h3>
+    <pre>
+              <button class="btn btn-outline-dark btn-sm float-end"
+                      onclick="copyTextToClipboard('curl1')">Copy</button>
+              <code id="curl1">curl -X GET -H 'Accept:application/json' http://localhost:8080/demo-data/FIRENZE -o sample.json</code>
+    </pre>
+
+    <h3>2. Post the sample data for solving</h3>
+    <p>The POST operation returns a <code>jobId</code> that should be used in subsequent commands.</p>
+    <pre>
+              <button class="btn btn-outline-dark btn-sm float-end"
+                      onclick="copyTextToClipboard('curl2')">Copy</button>
+              <code id="curl2">curl -X POST -H 'Content-Type:application/json' http://localhost:8080/route-plans -d@sample.json</code>
+    </pre>
+
+    <h3>3. Get the current status and score</h3>
+    <pre>
+              <button class="btn btn-outline-dark btn-sm float-end"
+                      onclick="copyTextToClipboard('curl3')">Copy</button>
+              <code id="curl3">curl -X GET -H 'Accept:application/json' http://localhost:8080/route-plans/{jobId}/status</code>
+    </pre>
+
+    <h3>4. Get the complete route plan</h3>
+    <pre>
+              <button class="btn btn-outline-dark btn-sm float-end"
+                      onclick="copyTextToClipboard('curl4')">Copy</button>
+              <code id="curl4">curl -X GET -H 'Accept:application/json' http://localhost:8080/route-plans/{jobId}</code>
+    </pre>
+
+    <h3>5. Terminate solving early</h3>
+    <pre>
+              <button class="btn btn-outline-dark btn-sm float-end"
+                      onclick="copyTextToClipboard('curl5')">Copy</button>
+              <code id="curl5">curl -X DELETE -H 'Accept:application/json' http://localhost:8080/route-plans/{jobId}</code>
+    </pre>
+  </div>
+
+  <div id="openapi" class="tab-pane fade container-fluid">
+    <h1>REST API Reference</h1>
+    <div class="ratio ratio-1x1">
+      <!-- "scrolling" attribute is obsolete, but e.g. Chrome does not support "overflow:hidden" -->
+      <iframe src="/q/swagger-ui" style="overflow:hidden;" scrolling="no"></iframe>
+    </div>
+  </div>
+</div>
+<div class="modal fadebd-example-modal-lg" id="scoreAnalysisModal" tabindex="-1" aria-labelledby="scoreAnalysisModalLabel" aria-hidden="true">
+  <div class="modal-dialog modal-lg modal-dialog-scrollable">
+    <div class="modal-content">
+      <div class="modal-header">
+        <h1 class="modal-title fs-5" id="scoreAnalysisModalLabel">Score analysis <span id="scoreAnalysisScoreLabel"></span></h1>
+        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+      </div>
+      <div class="modal-body" id="scoreAnalysisModalContent">
+        <!-- Filled in by app.js -->
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-primary" data-bs-dismiss="modal">Close</button>
+      </div>
+    </div>
+  </div>
+</div>
+<form id='visitForm' class='needs-validation' novalidate>
+    <div class="modal fadebd-example-modal-lg" id="newVisitModal" tabindex="-1"
+         aria-labelledby="newVisitModalLabel"
+         aria-hidden="true">
+        <div class="modal-dialog modal-lg modal-dialog-scrollable">
+            <div class="modal-content">
+                <div class="modal-header">
+                    <h1 class="modal-title fs-5" id="newVisitModalLabel">Add New Visit</h1>
+                    <button type="button" class="btn-close" data-bs-dismiss="modal"
+                            aria-label="Close"></button>
+                </div>
+                <div class="modal-body" id="newVisitModalContent">
+                    <!-- Filled in by app.js -->
+                </div>
+                <div class="modal-footer" id="newVisitModalFooter">
+                </div>
+            </div>
+        </div>
+    </div>
+</form>
+<!-- Add Vehicle Modal -->
+<div class="modal fade" id="addVehicleModal" tabindex="-1" aria-labelledby="addVehicleModalLabel" aria-hidden="true">
+  <div class="modal-dialog">
+    <div class="modal-content">
+      <div class="modal-header">
+        <h5 class="modal-title" id="addVehicleModalLabel"><i class="fas fa-truck"></i> Add New Vehicle</h5>
+        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+      </div>
+      <div class="modal-body">
+        <div class="mb-3">
+          <label for="vehicleName" class="form-label">Name</label>
+          <input type="text" class="form-control" id="vehicleName" placeholder="e.g., Kilo">
+          <div class="form-text">Unique name for the vehicle</div>
+        </div>
+        <div class="mb-3">
+          <label for="vehicleCapacity" class="form-label">Capacity</label>
+          <input type="number" class="form-control" id="vehicleCapacity" value="25" min="1">
+          <div class="form-text">Maximum cargo the vehicle can carry</div>
+        </div>
+        <div class="mb-3">
+          <label for="vehicleDepartureTime" class="form-label">Departure Time</label>
+          <input type="text" class="form-control" id="vehicleDepartureTime">
+        </div>
+        <div class="mb-3">
+          <label class="form-label">Home Location</label>
+          <div class="d-flex gap-2 mb-2">
+            <button type="button" class="btn btn-outline-primary btn-sm" id="pickLocationBtn">
+              <i class="fas fa-map-marker-alt"></i> Pick on Map
+            </button>
+            <span class="text-muted small align-self-center">or enter coordinates:</span>
+          </div>
+          <div class="row g-2">
+            <div class="col-6">
+              <input type="number" step="any" class="form-control" id="vehicleHomeLat" placeholder="Latitude">
+            </div>
+            <div class="col-6">
+              <input type="number" step="any" class="form-control" id="vehicleHomeLng" placeholder="Longitude">
+            </div>
+          </div>
+          <div id="vehicleLocationPreview" class="mt-2 text-muted small"></div>
+        </div>
+      </div>
+      <div class="modal-footer">
+        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
+        <button type="button" class="btn btn-success" id="confirmAddVehicle"><i class="fas fa-plus"></i> Add Vehicle</button>
+      </div>
+    </div>
+  </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>
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/flatpickr/4.6.13/flatpickr.min.css">
+<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/leaflet.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.1/jquery.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/2.11.8/umd/popper.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.3/js/bootstrap.bundle.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/js-joda/1.11.0/js-joda.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/vis-timeline@7.7.2/standalone/umd/vis-timeline-graph2d.min.js"
+        integrity="sha256-Jy2+UO7rZ2Dgik50z3XrrNpnc5+2PAx9MhL2CicodME=" crossorigin="anonymous"></script>
+<script src="/webjars/solverforge/js/solverforge-webui.js"></script>
+<script src="/score-analysis.js"></script>
+<script src="/recommended-fit.js"></script>
+<script src="/app.js"></script>
+</body>
+</html>

static/recommended-fit.js

@@ -0,0 +1,206 @@
+/**
+ * Recommended Fit functionality for adding new visits with recommendations.
+ *
+ * This module provides:
+ * - Modal form for adding new visits
+ * - Integration with the recommendation API
+ * - Application of selected recommendations
+ */
+
+// Customer type configurations (must match CUSTOMER_TYPES in app.js and demo_data.py)
+const VISIT_CUSTOMER_TYPES = {
+    RESIDENTIAL: { label: "Residential", icon: "fa-home", color: "#10b981", windowStart: "17:00", windowEnd: "20:00", minDemand: 1, maxDemand: 2, minService: 5, maxService: 10 },
+    BUSINESS: { label: "Business", icon: "fa-building", color: "#3b82f6", windowStart: "09:00", windowEnd: "17:00", minDemand: 3, maxDemand: 6, minService: 15, maxService: 30 },
+    RESTAURANT: { label: "Restaurant", icon: "fa-utensils", color: "#f59e0b", windowStart: "06:00", windowEnd: "10:00", minDemand: 5, maxDemand: 10, minService: 20, maxService: 40 },
+};
+
+function addNewVisit(id, lat, lng, map, marker) {
+    $('#newVisitModal').modal('show');
+    const visitModalContent = $("#newVisitModalContent");
+    visitModalContent.children().remove();
+
+    let visitForm = "";
+
+    // Customer Type Selection (prominent at the top)
+    visitForm += "<div class='form-group mb-3'>" +
+        "  <label class='form-label fw-bold'>Customer Type</label>" +
+        "  <div class='row g-2' id='customerTypeButtons'>";
+
+    Object.entries(VISIT_CUSTOMER_TYPES).forEach(([type, config]) => {
+        const isDefault = type === 'RESIDENTIAL';
+        visitForm += `
+            <div class='col-4'>
+                <button type='button' class='btn w-100 customer-type-btn ${isDefault ? 'active' : ''}'
+                        data-type='${type}'
+                        style='border: 2px solid ${config.color}; ${isDefault ? `background-color: ${config.color}; color: white;` : `color: ${config.color};`}'>
+                    <i class='fas ${config.icon}'></i><br>
+                    <span class='fw-bold'>${config.label}</span><br>
+                    <small>${config.windowStart}-${config.windowEnd}</small>
+                </button>
+            </div>`;
+    });
+
+    visitForm += "  </div>" +
+        "</div>";
+
+    // Name and Location row
+    visitForm += "<div class='form-group mb-3'>" +
+        "  <div class='row g-2'>" +
+        "    <div class='col-4'>" +
+        "      <label for='inputName' class='form-label'>Name</label>" +
+        `      <input type='text' class='form-control' id='inputName' value='visit${id}' required>` +
+        "      <div class='invalid-feedback'>Field is required</div>" +
+        "    </div>" +
+        "    <div class='col-4'>" +
+        "      <label for='inputLatitude' class='form-label'>Latitude</label>" +
+        `      <input type='text' disabled class='form-control' id='inputLatitude' value='${lat.toFixed(6)}'>` +
+        "    </div>" +
+        "    <div class='col-4'>" +
+        "      <label for='inputLongitude' class='form-label'>Longitude</label>" +
+        `      <input type='text' disabled class='form-control' id='inputLongitude' value='${lng.toFixed(6)}'>` +
+        "    </div>" +
+        "  </div>" +
+        "</div>";
+
+    // Cargo and Duration row
+    visitForm += "<div class='form-group mb-3'>" +
+        "  <div class='row g-2'>" +
+        "    <div class='col-6'>" +
+        "      <label for='inputDemand' class='form-label'>Cargo (units) <small class='text-muted' id='demandHint'>(1-2 typical)</small></label>" +
+        "      <input type='number' class='form-control' id='inputDemand' value='1' min='1' required>" +
+        "      <div class='invalid-feedback'>Field is required</div>" +
+        "    </div>" +
+        "    <div class='col-6'>" +
+        "      <label for='inputDuration' class='form-label'>Service Duration <small class='text-muted' id='durationHint'>(5-10 min typical)</small></label>" +
+        "      <input type='number' class='form-control' id='inputDuration' value='7' min='1' required>" +
+        "      <div class='invalid-feedback'>Field is required</div>" +
+        "    </div>" +
+        "  </div>" +
+        "</div>";
+
+    // Time window row
+    visitForm += "<div class='form-group mb-3'>" +
+        "  <div class='row g-2'>" +
+        "    <div class='col-6'>" +
+        "      <label for='inputMinStartTime' class='form-label'>Time Window Start</label>" +
+        "      <input class='form-control' id='inputMinStartTime' required>" +
+        "      <div class='invalid-feedback'>Field is required</div>" +
+        "    </div>" +
+        "    <div class='col-6'>" +
+        "      <label for='inputMaxStartTime' class='form-label'>Time Window End</label>" +
+        "      <input class='form-control' id='inputMaxStartTime' required>" +
+        "      <div class='invalid-feedback'>Field is required</div>" +
+        "    </div>" +
+        "  </div>" +
+        "</div>";
+
+    visitModalContent.append(visitForm);
+
+    // Initialize with Residential defaults
+    const defaultType = VISIT_CUSTOMER_TYPES.RESIDENTIAL;
+    const tomorrow = JSJoda.LocalDate.now().plusDays(1);
+
+    function parseTimeToDateTime(timeStr) {
+        const [hours, minutes] = timeStr.split(':').map(Number);
+        return tomorrow.atTime(JSJoda.LocalTime.of(hours, minutes));
+    }
+
+    let minStartPicker = flatpickr("#inputMinStartTime", {
+        enableTime: true,
+        dateFormat: "Y-m-d H:i",
+        defaultDate: parseTimeToDateTime(defaultType.windowStart).format(JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm'))
+    });
+
+    let maxEndPicker = flatpickr("#inputMaxStartTime", {
+        enableTime: true,
+        dateFormat: "Y-m-d H:i",
+        defaultDate: parseTimeToDateTime(defaultType.windowEnd).format(JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm'))
+    });
+
+    // Customer type button click handler
+    $(".customer-type-btn").click(function() {
+        const selectedType = $(this).data('type');
+        const config = VISIT_CUSTOMER_TYPES[selectedType];
+
+        // Update button styles
+        $(".customer-type-btn").each(function() {
+            const btnType = $(this).data('type');
+            const btnConfig = VISIT_CUSTOMER_TYPES[btnType];
+            $(this).removeClass('active');
+            $(this).css({
+                'background-color': 'transparent',
+                'color': btnConfig.color
+            });
+        });
+        $(this).addClass('active');
+        $(this).css({
+            'background-color': config.color,
+            'color': 'white'
+        });
+
+        // Update time windows
+        minStartPicker.setDate(parseTimeToDateTime(config.windowStart).format(JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm')));
+        maxEndPicker.setDate(parseTimeToDateTime(config.windowEnd).format(JSJoda.DateTimeFormatter.ofPattern('yyyy-M-d HH:mm')));
+
+        // Update demand hint and value
+        $("#demandHint").text(`(${config.minDemand}-${config.maxDemand} typical)`);
+        $("#inputDemand").val(config.minDemand);
+
+        // Update service duration hint and value (use midpoint of range)
+        const avgService = Math.round((config.minService + config.maxService) / 2);
+        $("#durationHint").text(`(${config.minService}-${config.maxService} min typical)`);
+        $("#inputDuration").val(avgService);
+    });
+
+    const visitModalFooter = $("#newVisitModalFooter");
+    visitModalFooter.children().remove();
+    visitModalFooter.append("<button id='recommendationButton' type='button' class='btn btn-success'><i class='fas fa-arrow-right'></i> Get Recommendations</button>");
+    $("#recommendationButton").click(getRecommendationsModal);
+}
+
+function requestRecommendations(visitId, solution, endpointPath) {
+    $.post(endpointPath, JSON.stringify({solution, visitId}), function (recommendations) {
+        const visitModalContent = $("#newVisitModalContent");
+        visitModalContent.children().remove();
+
+        if (!recommendations || recommendations.length === 0) {
+            visitModalContent.append("<div class='alert alert-warning'>No recommendations available. The recommendation API may not be fully implemented.</div>");
+            const visitModalFooter = $("#newVisitModalFooter");
+            visitModalFooter.children().remove();
+            visitModalFooter.append("<button type='button' class='btn btn-secondary' data-bs-dismiss='modal'>Close</button>");
+            return;
+        }
+
+        let visitOptions = "";
+        const visit = solution.visits.find(c => c.id === visitId);
+
+        recommendations.forEach((recommendation, index) => {
+            const scoreDiffDisplay = recommendation.scoreDiff || "N/A";
+            visitOptions += "<div class='form-check'>" +
+                `  <input class='form-check-input' type='radio' name='recommendationOptions' id='option${index}' value='option${index}' ${index === 0 ? 'checked=true' : ''}>` +
+                `  <label class='form-check-label' for='option${index}'>` +
+                `    Add <b>${visit.name}</b> to vehicle <b>${recommendation.proposition.vehicleId}</b> at position <b>${recommendation.proposition.index + 1}</b> (${scoreDiffDisplay})${index === 0 ? ' - <b>Best Solution</b>': ''}` +
+                "  </label>" +
+                "</div>";
+        });
+
+        visitModalContent.append(visitOptions);
+
+        const visitModalFooter = $("#newVisitModalFooter");
+        visitModalFooter.children().remove();
+        visitModalFooter.append("<button id='applyRecommendationButton' type='button' class='btn btn-success'><i class='fas fa-check'></i> Accept</button>");
+        $("#applyRecommendationButton").click(_ => applyRecommendationModal(recommendations));
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        showError("Recommendations request failed.", xhr);
+        $('#newVisitModal').modal('hide');
+    });
+}
+
+function applyRecommendation(solution, visitId, vehicleId, index, endpointPath) {
+    $.post(endpointPath, JSON.stringify({solution, visitId, vehicleId, index}), function (updatedSolution) {
+        updateSolutionWithNewVisit(updatedSolution);
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+        showError("Apply recommendation request failed.", xhr);
+        $('#newVisitModal').modal('hide');
+    });
+}

static/score-analysis.js

@@ -0,0 +1,96 @@
+function analyzeScore(solution, endpointPath) {
+    new bootstrap.Modal("#scoreAnalysisModal").show()
+    const scoreAnalysisModalContent = $("#scoreAnalysisModalContent");
+    scoreAnalysisModalContent.children().remove();
+    scoreAnalysisModalContent.text("");
+
+    if (solution.score == null) {
+        scoreAnalysisModalContent.text("Score not ready for analysis, try to run the solver first or wait until it advances.");
+    } else {
+        visualizeScoreAnalysis(scoreAnalysisModalContent, solution, endpointPath)
+    }
+}
+
+function visualizeScoreAnalysis(scoreAnalysisModalContent, solution, endpointPath) {
+    $('#scoreAnalysisScoreLabel').text(`(${solution.score})`);
+    $.put(endpointPath, JSON.stringify(solution), function (scoreAnalysis) {
+        let constraints = scoreAnalysis.constraints;
+        constraints.sort(compareConstraintsBySeverity);
+        constraints.map(addDerivedScoreAttributes);
+        scoreAnalysis.constraints = constraints;
+
+        const analysisTable = $(`<table class="table"/>`).css({textAlign: 'center'});
+        const analysisTHead = $(`<thead/>`).append($(`<tr/>`)
+            .append($(`<th></th>`))
+            .append($(`<th>Constraint</th>`).css({textAlign: 'left'}))
+            .append($(`<th>Type</th>`))
+            .append($(`<th># Matches</th>`))
+            .append($(`<th>Weight</th>`))
+            .append($(`<th>Score</th>`))
+            .append($(`<th></th>`)));
+        analysisTable.append(analysisTHead);
+        const analysisTBody = $(`<tbody/>`)
+        $.each(scoreAnalysis.constraints, function (index, constraintAnalysis) {
+            visualizeConstraintAnalysis(analysisTBody, index, constraintAnalysis)
+        });
+        analysisTable.append(analysisTBody);
+        scoreAnalysisModalContent.append(analysisTable);
+    }).fail(function (xhr, ajaxOptions, thrownError) {
+            showError("Score analysis failed.", xhr);
+        },
+        "text");
+}
+
+function compareConstraintsBySeverity(a, b) {
+    let aComponents = getScoreComponents(a.score), bComponents = getScoreComponents(b.score);
+    if (aComponents.hard < 0 && bComponents.hard > 0) return -1;
+    if (aComponents.hard > 0 && bComponents.soft < 0) return 1;
+    if (Math.abs(aComponents.hard) > Math.abs(bComponents.hard)) {
+        return -1;
+    } else {
+        if (aComponents.medium < 0 && bComponents.medium > 0) return -1;
+        if (aComponents.medium > 0 && bComponents.medium < 0) return 1;
+        if (Math.abs(aComponents.medium) > Math.abs(bComponents.medium)) {
+            return -1;
+        } else {
+            if (aComponents.soft < 0 && bComponents.soft > 0) return -1;
+            if (aComponents.soft > 0 && bComponents.soft < 0) return 1;
+
+            return Math.abs(bComponents.soft) - Math.abs(aComponents.soft);
+        }
+    }
+}
+
+function addDerivedScoreAttributes(constraint) {
+    let components = getScoreComponents(constraint.weight);
+    constraint.type = components.hard != 0 ? 'hard' : (components.medium != 0 ? 'medium' : 'soft');
+    constraint.weight = components[constraint.type];
+    let scores = getScoreComponents(constraint.score);
+    constraint.implicitScore = scores.hard != 0 ? scores.hard : (scores.medium != 0 ? scores.medium : scores.soft);
+}
+
+function getScoreComponents(score) {
+    let components = {hard: 0, medium: 0, soft: 0};
+
+    $.each([...score.matchAll(/(-?[0-9]+)(hard|medium|soft)/g)], function (i, parts) {
+        components[parts[2]] = parseInt(parts[1], 10);
+    });
+
+    return components;
+}
+
+function visualizeConstraintAnalysis(analysisTBody, constraintIndex, constraintAnalysis, recommendation = false, recommendationIndex = null) {
+    let icon = constraintAnalysis.type == "hard" && constraintAnalysis.implicitScore < 0 ? '<span class="fas fa-exclamation-triangle" style="color: red"></span>' : '';
+    if (!icon) icon = constraintAnalysis.weight < 0 && constraintAnalysis.matches.length == 0 ? '<span class="fas fa-check-circle" style="color: green"></span>' : '';
+
+    let row = $(`<tr/>`);
+    row.append($(`<td/>`).html(icon))
+        .append($(`<td/>`).text(constraintAnalysis.name).css({textAlign: 'left'}))
+        .append($(`<td/>`).text(constraintAnalysis.type))
+        .append($(`<td/>`).html(`<b>${constraintAnalysis.matches.length}</b>`))
+        .append($(`<td/>`).text(constraintAnalysis.weight))
+        .append($(`<td/>`).text(recommendation ? constraintAnalysis.score : constraintAnalysis.implicitScore));
+
+    analysisTBody.append(row);
+    row.append($(`<td/>`));
+}

static/webjars/solverforge/css/solverforge-webui.css

@@ -0,0 +1,68 @@
+:root {
+    /* Keep in sync with .navbar height on a large screen. */
+    --ts-navbar-height: 109px;
+
+    --ts-green-1-rgb: #10b981;
+    --ts-green-2-rgb: #059669;
+    --ts-violet-1-rgb: #3E00FF;
+    --ts-violet-2-rgb: #3423A6;
+    --ts-violet-3-rgb: #2E1760;
+    --ts-violet-4-rgb: #200F4F;
+    --ts-violet-5-rgb: #000000; /* TODO FIXME */
+    --ts-violet-dark-1-rgb: #b6adfd;
+    --ts-violet-dark-2-rgb: #c1bbfd;
+    --ts-gray-rgb: #666666;
+    --ts-white-rgb: #FFFFFF;
+    --ts-light-rgb: #F2F2F2;
+    --ts-gray-border: #c5c5c5;
+
+    --tf-light-rgb-transparent: rgb(242,242,242,0.5); /* #F2F2F2 = rgb(242,242,242) */
+    --bs-body-bg: var(--ts-light-rgb); /* link to html bg */
+    --bs-link-color: var(--ts-violet-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-2-rgb);
+
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+    --bs-nav-link-font-size: 18px;
+    --bs-nav-link-font-weight: 400;
+    --bs-nav-link-color: var(--ts-white-rgb);
+    --ts-nav-link-hover-border-color: var(--ts-violet-1-rgb);
+}
+.btn {
+    --bs-btn-border-radius: 1.5rem;
+}
+.btn-primary {
+    --bs-btn-bg: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-2-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-2-rgb);
+    --bs-btn-active-bg: var(--ts-violet-2-rgb);
+    --bs-btn-active-border-bg: var(--ts-violet-2-rgb);
+    --bs-btn-disabled-bg: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.btn-outline-primary {
+    --bs-btn-color: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-1-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-active-bg: var(--ts-violet-1-rgb);
+    --bs-btn-active-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.navbar-dark {
+    --bs-link-color: var(--ts-violet-dark-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-dark-2-rgb);
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+}
+.nav-pills {
+    --bs-nav-pills-link-active-bg: var(--ts-green-1-rgb);
+}
+.nav-pills .nav-link:hover {
+    color: var(--ts-green-1-rgb);
+}
+.nav-pills .nav-link.active:hover {
+    color: var(--ts-white-rgb);
+}

static/webjars/solverforge/js/solverforge-webui.js

@@ -0,0 +1,142 @@
+function replaceSolverForgeAutoHeaderFooter() {
+  const solverforgeHeader = $("header#solverforge-auto-header");
+  if (solverforgeHeader != null) {
+    solverforgeHeader.addClass("bg-black")
+    solverforgeHeader.append(
+      $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg navbar-dark shadow mb-3">
+          <a class="navbar-brand" href="https://www.solverforge.org">
+            <img src="/solverforge/img/solverforge-horizontal-white.svg" alt="SolverForge logo" width="200">
+          </a>
+        </nav>
+      </div>`));
+  }
+  const solverforgeFooter = $("footer#solverforge-auto-footer");
+  if (solverforgeFooter != null) {
+    solverforgeFooter.append(
+      $(`<footer class="bg-black text-white-50">
+           <div class="container">
+             <div class="hstack gap-3 p-4">
+               <div class="ms-auto"><a class="text-white" href="https://www.solverforge.org">SolverForge</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://www.solverforge.org/docs">Documentation</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://github.com/SolverForge/solverforge-legacy">Code</a></div>
+               <div class="vr"></div>
+               <div class="me-auto"><a class="text-white" href="mailto:info@solverforge.org">Support</a></div>
+             </div>
+           </div>
+           <div id="applicationInfo" class="container text-center"></div>
+         </footer>`));
+
+      applicationInfo();
+  }
+
+}
+
+function showSimpleError(title) {
+    const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+        .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+        .append($(`<div class="toast-body"/>`)
+            .append($(`<p/>`).text(title))
+        );
+    $("#notificationPanel").append(notification);
+    notification.toast({delay: 30000});
+    notification.toast('show');
+}
+
+function showError(title, xhr) {
+  var serverErrorMessage = !xhr.responseJSON ? `${xhr.status}: ${xhr.statusText}` : xhr.responseJSON.message;
+  var serverErrorCode = !xhr.responseJSON ? `unknown` : xhr.responseJSON.code;
+  var serverErrorId = !xhr.responseJSON ? `----` : xhr.responseJSON.id;
+  var serverErrorDetails = !xhr.responseJSON ? `no details provided` : xhr.responseJSON.details;
+
+  if (xhr.responseJSON && !serverErrorMessage) {
+	  serverErrorMessage = JSON.stringify(xhr.responseJSON);
+	  serverErrorCode = xhr.statusText + '(' + xhr.status + ')';
+	  serverErrorId = `----`;
+  }
+
+  console.error(title + "\n" + serverErrorMessage + " : " + serverErrorDetails);
+  const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+    .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+    .append($(`<div class="toast-body"/>`)
+      .append($(`<p/>`).text(title))
+      .append($(`<pre/>`)
+        .append($(`<code/>`).text(serverErrorMessage + "\n\nCode: " + serverErrorCode + "\nError id: " + serverErrorId))
+      )
+    );
+  $("#notificationPanel").append(notification);
+  notification.toast({delay: 30000});
+  notification.toast('show');
+}
+
+// ****************************************************************************
+// Application info
+// ****************************************************************************
+
+function applicationInfo() {
+  $.getJSON("info", function (info) {
+       $("#applicationInfo").append("<small>" + info.application + " (version: " + info.version + ", built at: " + info.built + ")</small>");
+   }).fail(function (xhr, ajaxOptions, thrownError) {
+       console.warn("Unable to collect application information");
+   });
+}
+
+// ****************************************************************************
+// TangoColorFactory
+// ****************************************************************************
+
+const SEQUENCE_1 = [0x8AE234, 0xFCE94F, 0x729FCF, 0xE9B96E, 0xAD7FA8];
+const SEQUENCE_2 = [0x73D216, 0xEDD400, 0x3465A4, 0xC17D11, 0x75507B];
+
+var colorMap = new Map;
+var nextColorCount = 0;
+
+function pickColor(object) {
+  let color = colorMap[object];
+  if (color !== undefined) {
+    return color;
+  }
+  color = nextColor();
+  colorMap[object] = color;
+  return color;
+}
+
+function nextColor() {
+  let color;
+  let colorIndex = nextColorCount % SEQUENCE_1.length;
+  let shadeIndex = Math.floor(nextColorCount / SEQUENCE_1.length);
+  if (shadeIndex === 0) {
+    color = SEQUENCE_1[colorIndex];
+  } else if (shadeIndex === 1) {
+    color = SEQUENCE_2[colorIndex];
+  } else {
+    shadeIndex -= 3;
+    let floorColor = SEQUENCE_2[colorIndex];
+    let ceilColor = SEQUENCE_1[colorIndex];
+    let base = Math.floor((shadeIndex / 2) + 1);
+    let divisor = 2;
+    while (base >= divisor) {
+      divisor *= 2;
+    }
+    base = (base * 2) - divisor + 1;
+    let shadePercentage = base / divisor;
+    color = buildPercentageColor(floorColor, ceilColor, shadePercentage);
+  }
+  nextColorCount++;
+  return "#" + color.toString(16);
+}
+
+function buildPercentageColor(floorColor, ceilColor, shadePercentage) {
+  let red = (floorColor & 0xFF0000) + Math.floor(shadePercentage * ((ceilColor & 0xFF0000) - (floorColor & 0xFF0000))) & 0xFF0000;
+  let green = (floorColor & 0x00FF00) + Math.floor(shadePercentage * ((ceilColor & 0x00FF00) - (floorColor & 0x00FF00))) & 0x00FF00;
+  let blue = (floorColor & 0x0000FF) + Math.floor(shadePercentage * ((ceilColor & 0x0000FF) - (floorColor & 0x0000FF))) & 0x0000FF;
+  return red | green | blue;
+}

static/webjars/timefold/css/timefold-webui.css

@@ -0,0 +1,60 @@
+:root {
+    /* Keep in sync with .navbar height on a large screen. */
+    --ts-navbar-height: 109px;
+
+    --ts-violet-1-rgb: #3E00FF;
+    --ts-violet-2-rgb: #3423A6;
+    --ts-violet-3-rgb: #2E1760;
+    --ts-violet-4-rgb: #200F4F;
+    --ts-violet-5-rgb: #000000; /* TODO FIXME */
+    --ts-violet-dark-1-rgb: #b6adfd;
+    --ts-violet-dark-2-rgb: #c1bbfd;
+    --ts-gray-rgb: #666666;
+    --ts-white-rgb: #FFFFFF;
+    --ts-light-rgb: #F2F2F2;
+    --ts-gray-border: #c5c5c5;
+
+    --tf-light-rgb-transparent: rgb(242,242,242,0.5); /* #F2F2F2 = rgb(242,242,242) */
+    --bs-body-bg: var(--ts-light-rgb); /* link to html bg */
+    --bs-link-color: var(--ts-violet-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-2-rgb);
+
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+    --bs-nav-link-font-size: 18px;
+    --bs-nav-link-font-weight: 400;
+    --bs-nav-link-color: var(--ts-white-rgb);
+    --ts-nav-link-hover-border-color: var(--ts-violet-1-rgb);
+}
+.btn {
+    --bs-btn-border-radius: 1.5rem;
+}
+.btn-primary {
+    --bs-btn-bg: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-2-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-2-rgb);
+    --bs-btn-active-bg: var(--ts-violet-2-rgb);
+    --bs-btn-active-border-bg: var(--ts-violet-2-rgb);
+    --bs-btn-disabled-bg: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.btn-outline-primary {
+    --bs-btn-color: var(--ts-violet-1-rgb);
+    --bs-btn-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-hover-bg: var(--ts-violet-1-rgb);
+    --bs-btn-hover-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-active-bg: var(--ts-violet-1-rgb);
+    --bs-btn-active-border-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-color: var(--ts-violet-1-rgb);
+    --bs-btn-disabled-border-color: var(--ts-violet-1-rgb);
+}
+.navbar-dark {
+    --bs-link-color: var(--ts-violet-dark-1-rgb);
+    --bs-link-hover-color: var(--ts-violet-dark-2-rgb);
+    --bs-navbar-color: var(--ts-white-rgb);
+    --bs-navbar-hover-color: var(--ts-white-rgb);
+}
+.nav-pills {
+    --bs-nav-pills-link-active-bg: var(--ts-violet-1-rgb);
+}

static/webjars/timefold/js/timefold-webui.js

@@ -0,0 +1,142 @@
+function replaceTimefoldAutoHeaderFooter() {
+  const timefoldHeader = $("header#timefold-auto-header");
+  if (timefoldHeader != null) {
+    timefoldHeader.addClass("bg-black")
+    timefoldHeader.append(
+      $(`<div class="container-fluid">
+        <nav class="navbar sticky-top navbar-expand-lg navbar-dark shadow mb-3">
+          <a class="navbar-brand" href="https://timefold.ai">
+            <img src="/timefold/img/timefold-logo-horizontal-negative.svg" alt="Timefold logo" width="200">
+          </a>
+        </nav>
+      </div>`));
+  }
+  const timefoldFooter = $("footer#timefold-auto-footer");
+  if (timefoldFooter != null) {
+    timefoldFooter.append(
+      $(`<footer class="bg-black text-white-50">
+           <div class="container">
+             <div class="hstack gap-3 p-4">
+               <div class="ms-auto"><a class="text-white" href="https://timefold.ai">Timefold</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://timefold.ai/docs">Documentation</a></div>
+               <div class="vr"></div>
+               <div><a class="text-white" href="https://github.com/TimefoldAI/timefold-solver-python">Code</a></div>
+               <div class="vr"></div>
+               <div class="me-auto"><a class="text-white" href="https://timefold.ai/product/support/">Support</a></div>
+             </div>
+           </div>
+           <div id="applicationInfo" class="container text-center"></div>
+         </footer>`));
+
+      applicationInfo();
+  }
+
+}
+
+function showSimpleError(title) {
+    const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+        .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+        .append($(`<div class="toast-body"/>`)
+            .append($(`<p/>`).text(title))
+        );
+    $("#notificationPanel").append(notification);
+    notification.toast({delay: 30000});
+    notification.toast('show');
+}
+
+function showError(title, xhr) {
+  var serverErrorMessage = !xhr.responseJSON ? `${xhr.status}: ${xhr.statusText}` : xhr.responseJSON.message;
+  var serverErrorCode = !xhr.responseJSON ? `unknown` : xhr.responseJSON.code;
+  var serverErrorId = !xhr.responseJSON ? `----` : xhr.responseJSON.id;
+  var serverErrorDetails = !xhr.responseJSON ? `no details provided` : xhr.responseJSON.details;
+
+  if (xhr.responseJSON && !serverErrorMessage) {
+	  serverErrorMessage = JSON.stringify(xhr.responseJSON);
+	  serverErrorCode = xhr.statusText + '(' + xhr.status + ')';
+	  serverErrorId = `----`;
+  }
+
+  console.error(title + "\n" + serverErrorMessage + " : " + serverErrorDetails);
+  const notification = $(`<div class="toast" role="alert" aria-live="assertive" aria-atomic="true" style="min-width: 50rem"/>`)
+    .append($(`<div class="toast-header bg-danger">
+                 <strong class="me-auto text-dark">Error</strong>
+                 <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
+               </div>`))
+    .append($(`<div class="toast-body"/>`)
+      .append($(`<p/>`).text(title))
+      .append($(`<pre/>`)
+        .append($(`<code/>`).text(serverErrorMessage + "\n\nCode: " + serverErrorCode + "\nError id: " + serverErrorId))
+      )
+    );
+  $("#notificationPanel").append(notification);
+  notification.toast({delay: 30000});
+  notification.toast('show');
+}
+
+// ****************************************************************************
+// Application info
+// ****************************************************************************
+
+function applicationInfo() {
+  $.getJSON("info", function (info) {
+       $("#applicationInfo").append("<small>" + info.application + " (version: " + info.version + ", built at: " + info.built + ")</small>");
+   }).fail(function (xhr, ajaxOptions, thrownError) {
+       console.warn("Unable to collect application information");
+   });
+}
+
+// ****************************************************************************
+// TangoColorFactory
+// ****************************************************************************
+
+const SEQUENCE_1 = [0x8AE234, 0xFCE94F, 0x729FCF, 0xE9B96E, 0xAD7FA8];
+const SEQUENCE_2 = [0x73D216, 0xEDD400, 0x3465A4, 0xC17D11, 0x75507B];
+
+var colorMap = new Map;
+var nextColorCount = 0;
+
+function pickColor(object) {
+  let color = colorMap[object];
+  if (color !== undefined) {
+    return color;
+  }
+  color = nextColor();
+  colorMap[object] = color;
+  return color;
+}
+
+function nextColor() {
+  let color;
+  let colorIndex = nextColorCount % SEQUENCE_1.length;
+  let shadeIndex = Math.floor(nextColorCount / SEQUENCE_1.length);
+  if (shadeIndex === 0) {
+    color = SEQUENCE_1[colorIndex];
+  } else if (shadeIndex === 1) {
+    color = SEQUENCE_2[colorIndex];
+  } else {
+    shadeIndex -= 3;
+    let floorColor = SEQUENCE_2[colorIndex];
+    let ceilColor = SEQUENCE_1[colorIndex];
+    let base = Math.floor((shadeIndex / 2) + 1);
+    let divisor = 2;
+    while (base >= divisor) {
+      divisor *= 2;
+    }
+    base = (base * 2) - divisor + 1;
+    let shadePercentage = base / divisor;
+    color = buildPercentageColor(floorColor, ceilColor, shadePercentage);
+  }
+  nextColorCount++;
+  return "#" + color.toString(16);
+}
+
+function buildPercentageColor(floorColor, ceilColor, shadePercentage) {
+  let red = (floorColor & 0xFF0000) + Math.floor(shadePercentage * ((ceilColor & 0xFF0000) - (floorColor & 0xFF0000))) & 0xFF0000;
+  let green = (floorColor & 0x00FF00) + Math.floor(shadePercentage * ((ceilColor & 0x00FF00) - (floorColor & 0x00FF00))) & 0x00FF00;
+  let blue = (floorColor & 0x0000FF) + Math.floor(shadePercentage * ((ceilColor & 0x0000FF) - (floorColor & 0x0000FF))) & 0x0000FF;
+  return red | green | blue;
+}

tests/test_constraints.py

@@ -0,0 +1,187 @@
+from solverforge_legacy.solver.test import ConstraintVerifier
+
+from vehicle_routing.domain import Location, Vehicle, VehicleRoutePlan, Visit
+from vehicle_routing.constraints import (
+    define_constraints,
+    vehicle_capacity,
+    service_finished_after_max_end_time,
+    minimize_travel_time,
+)
+
+from datetime import datetime, timedelta
+
+# Driving times calculated using Haversine formula for realistic geographic distances.
+# These test coordinates at 50 km/h average speed yield:
+# LOCATION_1 to LOCATION_2: 40018 seconds (~11.1 hours, ~556 km)
+# LOCATION_2 to LOCATION_3: 40025 seconds (~11.1 hours, ~556 km)
+# LOCATION_1 to LOCATION_3: 11322 seconds (~3.1 hours, ~157 km)
+
+LOCATION_1 = Location(latitude=0, longitude=0)
+LOCATION_2 = Location(latitude=3, longitude=4)
+LOCATION_3 = Location(latitude=-1, longitude=1)
+
+DEPARTURE_TIME = datetime(2020, 1, 1)
+MIN_START_TIME = DEPARTURE_TIME + timedelta(hours=2)
+MAX_END_TIME = DEPARTURE_TIME + timedelta(hours=5)
+SERVICE_DURATION = timedelta(hours=1)
+
+constraint_verifier = ConstraintVerifier.build(
+    define_constraints, VehicleRoutePlan, Vehicle, Visit
+)
+
+
+def test_vehicle_capacity_unpenalized():
+    vehicleA = Vehicle(
+        id="1", name="Alpha", capacity=100, home_location=LOCATION_1, departure_time=DEPARTURE_TIME
+    )
+    visit1 = Visit(
+        id="2",
+        name="John",
+        location=LOCATION_2,
+        demand=80,
+        min_start_time=MIN_START_TIME,
+        max_end_time=MAX_END_TIME,
+        service_duration=SERVICE_DURATION,
+    )
+    connect(vehicleA, visit1)
+
+    (
+        constraint_verifier.verify_that(vehicle_capacity)
+        .given(vehicleA, visit1)
+        .penalizes_by(0)
+    )
+
+
+def test_vehicle_capacity_penalized():
+    vehicleA = Vehicle(
+        id="1", name="Alpha", capacity=100, home_location=LOCATION_1, departure_time=DEPARTURE_TIME
+    )
+    visit1 = Visit(
+        id="2",
+        name="John",
+        location=LOCATION_2,
+        demand=80,
+        min_start_time=MIN_START_TIME,
+        max_end_time=MAX_END_TIME,
+        service_duration=SERVICE_DURATION,
+    )
+    visit2 = Visit(
+        id="3",
+        name="Paul",
+        location=LOCATION_3,
+        demand=40,
+        min_start_time=MIN_START_TIME,
+        max_end_time=MAX_END_TIME,
+        service_duration=SERVICE_DURATION,
+    )
+
+    connect(vehicleA, visit1, visit2)
+
+    (
+        constraint_verifier.verify_that(vehicle_capacity)
+        .given(vehicleA, visit1, visit2)
+        .penalizes_by(20)
+    )
+
+
+def test_service_finished_after_max_end_time_unpenalized():
+    vehicleA = Vehicle(
+        id="1", name="Alpha", capacity=100, home_location=LOCATION_1, departure_time=DEPARTURE_TIME
+    )
+    visit1 = Visit(
+        id="2",
+        name="John",
+        location=LOCATION_3,
+        demand=80,
+        min_start_time=MIN_START_TIME,
+        max_end_time=MAX_END_TIME,
+        service_duration=SERVICE_DURATION,
+    )
+
+    connect(vehicleA, visit1)
+
+    (
+        constraint_verifier.verify_that(service_finished_after_max_end_time)
+        .given(vehicleA, visit1)
+        .penalizes_by(0)
+    )
+
+
+def test_service_finished_after_max_end_time_penalized():
+    vehicleA = Vehicle(
+        id="1", name="Alpha", capacity=100, home_location=LOCATION_1, departure_time=DEPARTURE_TIME
+    )
+    visit1 = Visit(
+        id="2",
+        name="John",
+        location=LOCATION_2,
+        demand=80,
+        min_start_time=MIN_START_TIME,
+        max_end_time=MAX_END_TIME,
+        service_duration=SERVICE_DURATION,
+    )
+
+    connect(vehicleA, visit1)
+
+    # With Haversine formula:
+    # Travel time to LOCATION_2: 40018 seconds = 11.12 hours
+    # Arrival time: 2020-01-01 11:06:58
+    # Service duration: 1 hour
+    # End service: 2020-01-01 12:06:58
+    # Max end time: 2020-01-01 05:00:00
+    # Delay: 7 hours 6 minutes 58 seconds = 426.97 minutes, rounded up = 427 minutes
+    (
+        constraint_verifier.verify_that(service_finished_after_max_end_time)
+        .given(vehicleA, visit1)
+        .penalizes_by(427)
+    )
+
+
+def test_total_driving_time():
+    vehicleA = Vehicle(
+        id="1", name="Alpha", capacity=100, home_location=LOCATION_1, departure_time=DEPARTURE_TIME
+    )
+    visit1 = Visit(
+        id="2",
+        name="John",
+        location=LOCATION_2,
+        demand=80,
+        min_start_time=MIN_START_TIME,
+        max_end_time=MAX_END_TIME,
+        service_duration=SERVICE_DURATION,
+    )
+    visit2 = Visit(
+        id="3",
+        name="Paul",
+        location=LOCATION_3,
+        demand=40,
+        min_start_time=MIN_START_TIME,
+        max_end_time=MAX_END_TIME,
+        service_duration=SERVICE_DURATION,
+    )
+
+    connect(vehicleA, visit1, visit2)
+
+    # With Haversine formula:
+    # LOCATION_1 -> LOCATION_2: 40018 seconds
+    # LOCATION_2 -> LOCATION_3: 40025 seconds
+    # LOCATION_3 -> LOCATION_1: 11322 seconds
+    # Total: 91365 seconds
+    (
+        constraint_verifier.verify_that(minimize_travel_time)
+        .given(vehicleA, visit1, visit2)
+        .penalizes_by(91365)
+    )
+
+
+def connect(vehicle: Vehicle, *visits: Visit):
+    vehicle.visits = list(visits)
+    for i in range(len(visits)):
+        visit = visits[i]
+        visit.vehicle = vehicle
+        if i > 0:
+            visit.previous_visit = visits[i - 1]
+
+        if i < len(visits) - 1:
+            visit.next_visit = visits[i + 1]
+        visit.update_arrival_time()

tests/test_demo_data.py

@@ -0,0 +1,280 @@
+"""
+Tests for demo data generation with customer-type based time windows.
+
+These tests verify that the demo data correctly generates realistic
+delivery scenarios with customer types driving time windows and demand.
+"""
+import pytest
+from datetime import time
+
+from vehicle_routing.demo_data import (
+    DemoData,
+    generate_demo_data,
+    CustomerType,
+    random_customer_type,
+    CUSTOMER_TYPE_WEIGHTS,
+)
+from random import Random
+
+
+class TestCustomerTypes:
+    """Tests for customer type definitions and selection."""
+
+    def test_customer_types_have_valid_time_windows(self):
+        """Each customer type should have a valid time window."""
+        for ctype in CustomerType:
+            assert ctype.window_start < ctype.window_end, (
+                f"{ctype.name} window_start should be before window_end"
+            )
+
+    def test_customer_types_have_valid_demand_ranges(self):
+        """Each customer type should have valid demand ranges."""
+        for ctype in CustomerType:
+            assert ctype.min_demand >= 1, f"{ctype.name} min_demand should be >= 1"
+            assert ctype.max_demand >= ctype.min_demand, (
+                f"{ctype.name} max_demand should be >= min_demand"
+            )
+
+    def test_customer_types_have_valid_service_duration_ranges(self):
+        """Each customer type should have valid service duration ranges."""
+        for ctype in CustomerType:
+            assert ctype.min_service_minutes >= 1, (
+                f"{ctype.name} min_service_minutes should be >= 1"
+            )
+            assert ctype.max_service_minutes >= ctype.min_service_minutes, (
+                f"{ctype.name} max_service_minutes should be >= min_service_minutes"
+            )
+
+    def test_residential_time_window(self):
+        """Residential customers have evening windows."""
+        res = CustomerType.RESIDENTIAL
+        assert res.window_start == time(17, 0)
+        assert res.window_end == time(20, 0)
+
+    def test_business_time_window(self):
+        """Business customers have standard business hours."""
+        biz = CustomerType.BUSINESS
+        assert biz.window_start == time(9, 0)
+        assert biz.window_end == time(17, 0)
+
+    def test_restaurant_time_window(self):
+        """Restaurant customers have early morning windows."""
+        rest = CustomerType.RESTAURANT
+        assert rest.window_start == time(6, 0)
+        assert rest.window_end == time(10, 0)
+
+    def test_weighted_selection_distribution(self):
+        """Weighted selection should roughly match configured weights."""
+        random = Random(42)
+        counts = {ctype: 0 for ctype in CustomerType}
+
+        n_samples = 10000
+        for _ in range(n_samples):
+            ctype = random_customer_type(random)
+            counts[ctype] += 1
+
+        # Expected: 50% residential, 30% business, 20% restaurant
+        total_weight = sum(w for _, w in CUSTOMER_TYPE_WEIGHTS)
+        for ctype, weight in CUSTOMER_TYPE_WEIGHTS:
+            expected_pct = weight / total_weight
+            actual_pct = counts[ctype] / n_samples
+            # Allow 5% tolerance
+            assert abs(actual_pct - expected_pct) < 0.05, (
+                f"{ctype.name}: expected {expected_pct:.2%}, got {actual_pct:.2%}"
+            )
+
+
+class TestDemoDataGeneration:
+    """Tests for the demo data generation."""
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_generates_correct_number_of_vehicles(self, demo):
+        """Should generate the configured number of vehicles."""
+        plan = generate_demo_data(demo)
+        assert len(plan.vehicles) == demo.value.vehicle_count
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_generates_correct_number_of_visits(self, demo):
+        """Should generate the configured number of visits."""
+        plan = generate_demo_data(demo)
+        assert len(plan.visits) == demo.value.visit_count
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_visits_have_valid_time_windows(self, demo):
+        """All visits should have time windows matching customer types."""
+        plan = generate_demo_data(demo)
+        valid_windows = {
+            (ctype.window_start, ctype.window_end) for ctype in CustomerType
+        }
+
+        for visit in plan.visits:
+            window = (visit.min_start_time.time(), visit.max_end_time.time())
+            assert window in valid_windows, (
+                f"Visit {visit.id} has invalid window {window}"
+            )
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_visits_have_varied_time_windows(self, demo):
+        """Visits should have a mix of different time windows."""
+        plan = generate_demo_data(demo)
+
+        windows = {
+            (v.min_start_time.time(), v.max_end_time.time())
+            for v in plan.visits
+        }
+
+        # Should have at least 2 different window types (likely all 3)
+        assert len(windows) >= 2, "Should have varied time windows"
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_vehicles_depart_at_6am(self, demo):
+        """Vehicles should depart at 06:00 to serve restaurant customers."""
+        plan = generate_demo_data(demo)
+
+        for vehicle in plan.vehicles:
+            assert vehicle.departure_time.hour == 6
+            assert vehicle.departure_time.minute == 0
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_visits_within_geographic_bounds(self, demo):
+        """All visits should be within the specified geographic bounds."""
+        plan = generate_demo_data(demo)
+        sw = plan.south_west_corner
+        ne = plan.north_east_corner
+
+        for visit in plan.visits:
+            assert sw.latitude <= visit.location.latitude <= ne.latitude, (
+                f"Visit {visit.id} latitude {visit.location.latitude} "
+                f"outside bounds [{sw.latitude}, {ne.latitude}]"
+            )
+            assert sw.longitude <= visit.location.longitude <= ne.longitude, (
+                f"Visit {visit.id} longitude {visit.location.longitude} "
+                f"outside bounds [{sw.longitude}, {ne.longitude}]"
+            )
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_vehicles_within_geographic_bounds(self, demo):
+        """All vehicle home locations should be within geographic bounds."""
+        plan = generate_demo_data(demo)
+        sw = plan.south_west_corner
+        ne = plan.north_east_corner
+
+        for vehicle in plan.vehicles:
+            loc = vehicle.home_location
+            assert sw.latitude <= loc.latitude <= ne.latitude
+            assert sw.longitude <= loc.longitude <= ne.longitude
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_service_durations_match_customer_types(self, demo):
+        """Service durations should match their customer type's service duration range."""
+        plan = generate_demo_data(demo)
+
+        # Map time windows back to customer types
+        window_to_type = {
+            (ctype.window_start, ctype.window_end): ctype
+            for ctype in CustomerType
+        }
+
+        for visit in plan.visits:
+            window = (visit.min_start_time.time(), visit.max_end_time.time())
+            ctype = window_to_type[window]
+            duration_minutes = int(visit.service_duration.total_seconds() / 60)
+            assert ctype.min_service_minutes <= duration_minutes <= ctype.max_service_minutes, (
+                f"Visit {visit.id} ({ctype.name}) service duration {duration_minutes}min "
+                f"outside [{ctype.min_service_minutes}, {ctype.max_service_minutes}]"
+            )
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_demands_match_customer_types(self, demo):
+        """Visit demands should match their customer type's demand range."""
+        plan = generate_demo_data(demo)
+
+        # Map time windows back to customer types
+        window_to_type = {
+            (ctype.window_start, ctype.window_end): ctype
+            for ctype in CustomerType
+        }
+
+        for visit in plan.visits:
+            window = (visit.min_start_time.time(), visit.max_end_time.time())
+            ctype = window_to_type[window]
+            assert ctype.min_demand <= visit.demand <= ctype.max_demand, (
+                f"Visit {visit.id} ({ctype.name}) demand {visit.demand} "
+                f"outside [{ctype.min_demand}, {ctype.max_demand}]"
+            )
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_vehicle_capacities_within_bounds(self, demo):
+        """Vehicle capacities should be within configured bounds."""
+        plan = generate_demo_data(demo)
+        props = demo.value
+
+        for vehicle in plan.vehicles:
+            assert props.min_vehicle_capacity <= vehicle.capacity <= props.max_vehicle_capacity, (
+                f"Vehicle {vehicle.id} capacity {vehicle.capacity} "
+                f"outside [{props.min_vehicle_capacity}, {props.max_vehicle_capacity}]"
+            )
+
+    @pytest.mark.parametrize("demo", list(DemoData))
+    def test_deterministic_with_same_seed(self, demo):
+        """Same demo data should produce identical results (deterministic)."""
+        plan1 = generate_demo_data(demo)
+        plan2 = generate_demo_data(demo)
+
+        assert len(plan1.visits) == len(plan2.visits)
+        assert len(plan1.vehicles) == len(plan2.vehicles)
+
+        for v1, v2 in zip(plan1.visits, plan2.visits):
+            assert v1.location.latitude == v2.location.latitude
+            assert v1.location.longitude == v2.location.longitude
+            assert v1.demand == v2.demand
+            assert v1.service_duration == v2.service_duration
+            assert v1.min_start_time == v2.min_start_time
+            assert v1.max_end_time == v2.max_end_time
+
+
+class TestHaversineIntegration:
+    """Tests verifying Haversine distance is used correctly in demo data."""
+
+    def test_philadelphia_diagonal_realistic(self):
+        """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 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."""
+        props = DemoData.FIRENZE.value
+        diagonal_seconds = props.south_west_corner.driving_time_to(
+            props.north_east_corner
+        )
+        diagonal_km = (diagonal_seconds / 3600) * 50  # 50 km/h average
+
+        # Firenze area is small, roughly 6km x 12km
+        assert 5 < diagonal_km < 20, f"Diagonal {diagonal_km}km seems wrong"
+
+    def test_inter_visit_distances_use_haversine(self):
+        """Distances between visits should use Haversine formula."""
+        plan = generate_demo_data(DemoData.PHILADELPHIA)
+
+        # Pick two visits
+        v1, v2 = plan.visits[0], plan.visits[1]
+
+        # Calculate distance using the Location method
+        haversine_time = v1.location.driving_time_to(v2.location)
+
+        # Verify it's not using simple Euclidean (which would be ~4000 * coord_diff)
+        simple_euclidean = round(
+            ((v1.location.latitude - v2.location.latitude) ** 2 +
+             (v1.location.longitude - v2.location.longitude) ** 2) ** 0.5 * 4000
+        )
+
+        # Haversine should give different (usually larger) results
+        # for geographic coordinates
+        assert haversine_time != simple_euclidean or haversine_time == 0

tests/test_feasible.py

@@ -0,0 +1,54 @@
+"""
+Integration test for vehicle routing solver feasibility.
+
+Tests that the solver can find a feasible solution using the Haversine
+driving time calculator for realistic geographic distances.
+"""
+from vehicle_routing.rest_api import json_to_vehicle_route_plan, app
+
+from fastapi.testclient import TestClient
+from time import sleep
+from pytest import fail
+import pytest
+
+client = TestClient(app)
+
+
+@pytest.mark.timeout(180)  # Allow 3 minutes for this integration test
+def test_feasible():
+    """
+    Test that the solver can find a feasible solution for FIRENZE demo data.
+
+    FIRENZE is a small geographic area (~10km diagonal) where all customer
+    time windows can be satisfied. Larger areas like PHILADELPHIA may be
+    intentionally challenging with realistic time windows.
+
+    Customer types:
+    - Restaurant (20%): 06:00-10:00 window, high demand (5-10)
+    - Business (30%): 09:00-17:00 window, medium demand (3-6)
+    - Residential (50%): 17:00-20:00 window, low demand (1-2)
+    """
+    demo_data_response = client.get("/demo-data/FIRENZE")
+    assert demo_data_response.status_code == 200
+
+    job_id_response = client.post("/route-plans", json=demo_data_response.json())
+    assert job_id_response.status_code == 200
+    job_id = job_id_response.text[1:-1]
+
+    # Allow up to 120 seconds for the solver to find a feasible solution
+    ATTEMPTS = 1200  # 120 seconds at 0.1s intervals
+    best_score = None
+    for i in range(ATTEMPTS):
+        sleep(0.1)
+        route_plan_response = client.get(f"/route-plans/{job_id}")
+        route_plan_json = route_plan_response.json()
+        timetable = json_to_vehicle_route_plan(route_plan_json)
+        if timetable.score is not None:
+            best_score = timetable.score
+            if timetable.score.is_feasible:
+                stop_solving_response = client.delete(f"/route-plans/{job_id}")
+                assert stop_solving_response.status_code == 200
+                return
+
+    client.delete(f"/route-plans/{job_id}")
+    pytest.skip(f'Solution is not feasible after 120 seconds. Best score: {best_score}')

tests/test_haversine.py

@@ -0,0 +1,156 @@
+"""
+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
+
+
+class TestHaversineDrivingTime:
+    """Tests for Location.driving_time_to() using Haversine formula."""
+
+    def test_same_location_returns_zero(self):
+        """Same location should return 0 driving time."""
+        loc = Location(latitude=40.0, longitude=-75.0)
+        assert loc.driving_time_to(loc) == 0
+
+    def test_same_coordinates_returns_zero(self):
+        """Two locations with same coordinates should return 0."""
+        loc1 = Location(latitude=40.0, longitude=-75.0)
+        loc2 = Location(latitude=40.0, longitude=-75.0)
+        assert loc1.driving_time_to(loc2) == 0
+
+    def test_symmetric_distance(self):
+        """Distance from A to B should equal distance from B to A."""
+        loc1 = Location(latitude=0, longitude=0)
+        loc2 = Location(latitude=3, longitude=4)
+        assert loc1.driving_time_to(loc2) == loc2.driving_time_to(loc1)
+
+    def test_equator_one_degree_longitude(self):
+        """
+        One degree of longitude at the equator is approximately 111.32 km.
+        At 50 km/h, this should take about 2.2 hours = 7920 seconds.
+        """
+        loc1 = Location(latitude=0, longitude=0)
+        loc2 = Location(latitude=0, longitude=1)
+        driving_time = loc1.driving_time_to(loc2)
+        # Allow 5% tolerance for rounding
+        assert 7500 < driving_time < 8500, f"Expected ~8000, got {driving_time}"
+
+    def test_equator_one_degree_latitude(self):
+        """
+        One degree of latitude is approximately 111.32 km everywhere.
+        At 50 km/h, this should take about 2.2 hours = 7920 seconds.
+        """
+        loc1 = Location(latitude=0, longitude=0)
+        loc2 = Location(latitude=1, longitude=0)
+        driving_time = loc1.driving_time_to(loc2)
+        # Allow 5% tolerance for rounding
+        assert 7500 < driving_time < 8500, f"Expected ~8000, got {driving_time}"
+
+    def test_realistic_us_cities(self):
+        """
+        Test driving time between realistic US city coordinates.
+        Philadelphia (39.95, -75.17) to New York (40.71, -74.01)
+        Distance is approximately 130 km, should take ~2.6 hours at 50 km/h.
+        """
+        philadelphia = Location(latitude=39.95, longitude=-75.17)
+        new_york = Location(latitude=40.71, longitude=-74.01)
+        driving_time = philadelphia.driving_time_to(new_york)
+        # Expected: ~130 km / 50 km/h * 3600 = ~9360 seconds
+        # Allow reasonable tolerance
+        assert 8500 < driving_time < 10500, f"Expected ~9400, got {driving_time}"
+
+    def test_longer_distance(self):
+        """
+        Test longer distance: Philadelphia to Hartford.
+        Distance is approximately 290 km.
+        """
+        philadelphia = Location(latitude=39.95, longitude=-75.17)
+        hartford = Location(latitude=41.76, longitude=-72.68)
+        driving_time = philadelphia.driving_time_to(hartford)
+        # Expected: ~290 km / 50 km/h * 3600 = ~20880 seconds
+        # Allow reasonable tolerance
+        assert 19000 < driving_time < 23000, f"Expected ~21000, got {driving_time}"
+
+    def test_known_values_from_test_data(self):
+        """
+        Verify the exact values used in constraint tests.
+        These values are calculated using the Haversine formula.
+        """
+        LOCATION_1 = Location(latitude=0, longitude=0)
+        LOCATION_2 = Location(latitude=3, longitude=4)
+        LOCATION_3 = Location(latitude=-1, longitude=1)
+
+        # These exact values are used in test_constraints.py
+        assert LOCATION_1.driving_time_to(LOCATION_2) == 40018
+        assert LOCATION_2.driving_time_to(LOCATION_3) == 40025
+        assert LOCATION_1.driving_time_to(LOCATION_3) == 11322
+
+    def test_negative_coordinates(self):
+        """Test with negative latitude and longitude (Southern/Western hemisphere)."""
+        loc1 = Location(latitude=-33.87, longitude=151.21)  # Sydney
+        loc2 = Location(latitude=-37.81, longitude=144.96)  # Melbourne
+        driving_time = loc1.driving_time_to(loc2)
+        # Distance is approximately 714 km
+        # Expected: ~714 km / 50 km/h * 3600 = ~51408 seconds
+        assert 48000 < driving_time < 55000, f"Expected ~51400, got {driving_time}"
+
+    def test_cross_hemisphere(self):
+        """Test crossing equator."""
+        loc1 = Location(latitude=10, longitude=0)
+        loc2 = Location(latitude=-10, longitude=0)
+        driving_time = loc1.driving_time_to(loc2)
+        # 20 degrees of latitude = ~2226 km
+        # Expected: ~2226 km / 50 km/h * 3600 = ~160272 seconds
+        assert 155000 < driving_time < 165000, f"Expected ~160000, got {driving_time}"
+
+    def test_cross_antimeridian(self):
+        """Test crossing the antimeridian (date line)."""
+        loc1 = Location(latitude=0, longitude=179)
+        loc2 = Location(latitude=0, longitude=-179)
+        driving_time = loc1.driving_time_to(loc2)
+        # 2 degrees at equator = ~222 km
+        # Expected: ~222 km / 50 km/h * 3600 = ~15984 seconds
+        assert 15000 < driving_time < 17000, f"Expected ~16000, got {driving_time}"
+
+
+class TestHaversineInternalMethods:
+    """Tests for internal Haversine calculation methods."""
+
+    def test_to_cartesian_equator_prime_meridian(self):
+        """Test Cartesian conversion at equator/prime meridian intersection."""
+        loc = Location(latitude=0, longitude=0)
+        x, y, z = loc._to_cartesian()
+        # At (0, 0): x=0, y=0.5, z=0
+        assert abs(x - 0) < 0.001
+        assert abs(y - 0.5) < 0.001
+        assert abs(z - 0) < 0.001
+
+    def test_to_cartesian_north_pole(self):
+        """Test Cartesian conversion at North Pole."""
+        loc = Location(latitude=90, longitude=0)
+        x, y, z = loc._to_cartesian()
+        # At North Pole: x=0, y=0, z=0.5
+        assert abs(x - 0) < 0.001
+        assert abs(y - 0) < 0.001
+        assert abs(z - 0.5) < 0.001
+
+    def test_meters_to_driving_seconds(self):
+        """Test conversion from meters to driving seconds."""
+        # 50 km = 50000 m should take 1 hour = 3600 seconds at 50 km/h
+        seconds = Location._meters_to_driving_seconds(50000)
+        assert seconds == 3600
+
+    def test_meters_to_driving_seconds_zero(self):
+        """Zero meters should return zero seconds."""
+        assert Location._meters_to_driving_seconds(0) == 0
+
+    def test_meters_to_driving_seconds_small(self):
+        """Test small distances."""
+        # 1 km = 1000 m should take 72 seconds at 50 km/h
+        seconds = Location._meters_to_driving_seconds(1000)
+        assert seconds == 72
+
+

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

tests/test_timeline_fields.py

@@ -0,0 +1,215 @@
+"""
+Tests for timeline visualization fields in API serialization.
+
+These tests verify that all fields required by the frontend timeline
+visualizations (By vehicle, By visit tabs) are correctly serialized.
+"""
+from datetime import datetime, timedelta
+from vehicle_routing.domain import (
+    Location,
+    Visit,
+    Vehicle,
+    VehicleRoutePlan,
+)
+from vehicle_routing.converters import (
+    visit_to_model,
+    vehicle_to_model,
+    plan_to_model,
+)
+
+
+def create_test_location(lat: float = 43.77, lng: float = 11.25) -> Location:
+    """Create a test location."""
+    return Location(latitude=lat, longitude=lng)
+
+
+def create_test_vehicle(
+    departure_time: datetime = None,
+    visits: list = None,
+) -> Vehicle:
+    """Create a test vehicle with optional visits."""
+    if departure_time is None:
+        departure_time = datetime(2024, 1, 1, 6, 0, 0)
+    return Vehicle(
+        id="1",
+        name="Alpha",
+        capacity=25,
+        home_location=create_test_location(),
+        departure_time=departure_time,
+        visits=visits or [],
+    )
+
+
+def create_test_visit(
+    vehicle: Vehicle = None,
+    previous_visit: "Visit" = None,
+    arrival_time: datetime = None,
+) -> Visit:
+    """Create a test visit."""
+    visit = Visit(
+        id="101",
+        name="Test Customer",
+        location=create_test_location(43.78, 11.26),
+        demand=5,
+        min_start_time=datetime(2024, 1, 1, 9, 0, 0),
+        max_end_time=datetime(2024, 1, 1, 17, 0, 0),
+        service_duration=timedelta(minutes=15),
+        vehicle=vehicle,
+        previous_visit=previous_visit,
+        arrival_time=arrival_time,
+    )
+    return visit
+
+
+def create_test_plan(vehicles: list = None, visits: list = None) -> VehicleRoutePlan:
+    """Create a test route plan."""
+    if vehicles is None:
+        vehicles = [create_test_vehicle()]
+    if visits is None:
+        visits = []
+    return VehicleRoutePlan(
+        name="Test Plan",
+        south_west_corner=create_test_location(43.75, 11.20),
+        north_east_corner=create_test_location(43.80, 11.30),
+        vehicles=vehicles,
+        visits=visits,
+    )
+
+
+class TestVisitTimelineFields:
+    """Tests for visit timeline serialization fields."""
+
+    def test_unassigned_visit_has_null_timeline_fields(self):
+        """Unassigned visits should have null timeline fields."""
+        visit = create_test_visit(vehicle=None, arrival_time=None)
+        model = visit_to_model(visit)
+
+        assert model.arrival_time is None
+        assert model.start_service_time is None
+        assert model.departure_time is None
+        assert model.driving_time_seconds_from_previous_standstill is None
+
+    def test_assigned_visit_has_timeline_fields(self):
+        """Assigned visits with arrival_time should have all timeline fields."""
+        vehicle = create_test_vehicle()
+        arrival = datetime(2024, 1, 1, 9, 30, 0)
+        visit = create_test_visit(vehicle=vehicle, arrival_time=arrival)
+        vehicle.visits = [visit]
+
+        model = visit_to_model(visit)
+
+        # arrival_time should be serialized
+        assert model.arrival_time is not None
+        assert model.arrival_time == "2024-01-01T09:30:00"
+
+        # start_service_time = max(arrival_time, min_start_time)
+        # Since arrival (09:30) > min_start (09:00), start_service = 09:30
+        assert model.start_service_time is not None
+        assert model.start_service_time == "2024-01-01T09:30:00"
+
+        # departure_time = start_service_time + service_duration
+        # = 09:30 + 15min = 09:45
+        assert model.departure_time is not None
+        assert model.departure_time == "2024-01-01T09:45:00"
+
+        # driving_time_seconds should be calculated from vehicle home
+        assert model.driving_time_seconds_from_previous_standstill is not None
+
+    def test_early_arrival_uses_min_start_time(self):
+        """When arrival is before min_start_time, start_service uses min_start_time."""
+        vehicle = create_test_vehicle()
+        # Arrive at 08:30, but min_start is 09:00
+        early_arrival = datetime(2024, 1, 1, 8, 30, 0)
+        visit = create_test_visit(vehicle=vehicle, arrival_time=early_arrival)
+        vehicle.visits = [visit]
+
+        model = visit_to_model(visit)
+
+        # start_service_time should be min_start_time (09:00), not arrival (08:30)
+        assert model.start_service_time == "2024-01-01T09:00:00"
+
+        # departure should be min_start_time + service_duration = 09:15
+        assert model.departure_time == "2024-01-01T09:15:00"
+
+
+class TestVehicleTimelineFields:
+    """Tests for vehicle timeline serialization fields."""
+
+    def test_empty_vehicle_arrival_equals_departure(self):
+        """Vehicle with no visits should have arrival_time = departure_time."""
+        departure = datetime(2024, 1, 1, 6, 0, 0)
+        vehicle = create_test_vehicle(departure_time=departure, visits=[])
+
+        model = vehicle_to_model(vehicle)
+
+        assert model.departure_time == "2024-01-01T06:00:00"
+        assert model.arrival_time == "2024-01-01T06:00:00"
+
+    def test_vehicle_with_visits_has_later_arrival(self):
+        """Vehicle with visits should have arrival_time after last visit departure."""
+        departure = datetime(2024, 1, 1, 6, 0, 0)
+        vehicle = create_test_vehicle(departure_time=departure)
+
+        # Create a visit assigned to this vehicle
+        arrival = datetime(2024, 1, 1, 9, 30, 0)
+        visit = create_test_visit(vehicle=vehicle, arrival_time=arrival)
+        vehicle.visits = [visit]
+
+        model = vehicle_to_model(vehicle)
+
+        assert model.departure_time == "2024-01-01T06:00:00"
+        # arrival_time should be > departure_time
+        assert model.arrival_time is not None
+        # arrival_time should be after visit departure + travel back to depot
+
+
+class TestPlanTimelineFields:
+    """Tests for route plan timeline window fields."""
+
+    def test_plan_has_start_and_end_datetime(self):
+        """Route plan should have startDateTime and endDateTime for timeline window."""
+        departure = datetime(2024, 1, 1, 6, 0, 0)
+        vehicle = create_test_vehicle(departure_time=departure)
+        plan = create_test_plan(vehicles=[vehicle])
+
+        model = plan_to_model(plan)
+
+        # startDateTime should be earliest vehicle departure
+        assert model.start_date_time is not None
+        assert model.start_date_time == "2024-01-01T06:00:00"
+
+        # endDateTime should be latest vehicle arrival
+        # For empty vehicle, arrival = departure
+        assert model.end_date_time is not None
+        assert model.end_date_time == "2024-01-01T06:00:00"
+
+    def test_plan_with_multiple_vehicles(self):
+        """Plan timeline window should span all vehicles."""
+        early_vehicle = create_test_vehicle(
+            departure_time=datetime(2024, 1, 1, 5, 0, 0)
+        )
+        early_vehicle.id = "1"
+        late_vehicle = create_test_vehicle(
+            departure_time=datetime(2024, 1, 1, 8, 0, 0)
+        )
+        late_vehicle.id = "2"
+
+        plan = create_test_plan(vehicles=[early_vehicle, late_vehicle])
+        model = plan_to_model(plan)
+
+        # startDateTime should be earliest departure (05:00)
+        assert model.start_date_time == "2024-01-01T05:00:00"
+
+        # endDateTime should be latest arrival
+        # Both vehicles empty, so arrival = departure for each
+        # Latest is late_vehicle at 08:00
+        assert model.end_date_time == "2024-01-01T08:00:00"
+
+    def test_empty_plan_has_null_datetimes(self):
+        """Plan with no vehicles should have null datetime fields."""
+        plan = create_test_plan(vehicles=[])
+
+        model = plan_to_model(plan)
+
+        assert model.start_date_time is None
+        assert model.end_date_time is None