batman

.gitignore

@@ -0,0 +1,29 @@
+target
+local
+__pycache__
+.pytest_cache
+/*.egg-info
+/**/dist
+/**/*.egg-info
+/**/*-stubs
+.venv
+
+# Eclipse, Netbeans and IntelliJ files
+/.*
+!/.github
+!/.ci
+!.gitignore
+!.gitattributes
+!/.mvn
+/nbproject
+*.ipr
+*.iws
+*.iml
+
+# Repository wide ignore mac DS_Store files
+.DS_Store
+*.code-workspace
+CLAUDE.md
+DOCUMENTATION_AUDIT.md
+
+**/.venv/**

Dockerfile

@@ -0,0 +1,24 @@
+# Use Python 3.12 base image
+FROM python:3.12
+
+# Install JDK 21 (required for solverforge-legacy)
+RUN apt-get update && \
+    apt-get install -y wget gnupg2 && \
+    wget -O- https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor > /usr/share/keyrings/adoptium-archive-keyring.gpg && \
+    echo "deb [signed-by=/usr/share/keyrings/adoptium-archive-keyring.gpg] https://packages.adoptium.net/artifactory/deb bookworm main" > /etc/apt/sources.list.d/adoptium.list && \
+    apt-get update && \
+    apt-get install -y temurin-21-jdk && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy application files
+COPY . .
+
+# Install the application
+RUN pip install --no-cache-dir -e .
+
+# Expose port 8080
+EXPOSE 8080
+
+# Run the application
+CMD ["run-app"]

README.md

@@ -0,0 +1,73 @@
+---
+title: Vehicle Routing (Python)
+emoji: 👀
+colorFrom: gray
+colorTo: green
+sdk: docker
+app_port: 8080
+pinned: false
+license: apache-2.0
+short_description: SolverForge Quickstart for the Vehicle Routing problem
+---
+
+# Vehicle Routing (Python)
+
+Find the most efficient routes for a fleet of vehicles.
+
+![Vehicle Routing Screenshot](./vehicle-routing-screenshot.png)
+
+- [Prerequisites](#prerequisites)
+- [Run the application](#run-the-application)
+- [Test the application](#test-the-application)
+
+## Prerequisites
+
+1. Install [Python 3.10, 3.11 or 3.12](https://www.python.org/downloads/).
+
+2. Install JDK 17+, for example with [Sdkman](https://sdkman.io):
+    ```sh
+    $ sdk install java
+
+## Run the application
+
+1. Git clone the solverforge-quickstarts repo and navigate to this directory:
+   ```sh
+   $ git clone https://github.com/SolverForge/solverforge-quickstarts.git
+   ...
+   $ cd solverforge-quickstarts/fast/vehicle-routing-fast
+   ```
+
+2. Create a virtual environment:
+   ```sh
+   $ python -m venv .venv
+   ```
+
+3. Activate the virtual environment:
+   ```sh
+   $ . .venv/bin/activate
+   ```
+
+4. Install the application:
+   ```sh
+   $ pip install -e .
+   ```
+
+5. Run the application:
+   ```sh
+   $ run-app
+   ```
+
+6. Visit [http://localhost:8080](http://localhost:8080) in your browser.
+
+7. Click on the **Solve** button.
+
+## Test the application
+
+1. Run tests:
+   ```sh
+   $ pytest
+   ```
+
+## More information
+
+Visit [solverforge.org](https://www.solverforge.org).

logging.conf

@@ -0,0 +1,30 @@
+[loggers]
+keys=root,timefold_solver
+
+[handlers]
+keys=consoleHandler
+
+[formatters]
+keys=simpleFormatter
+
+[logger_root]
+level=INFO
+handlers=consoleHandler
+
+[logger_timefold_solver]
+level=INFO
+qualname=timefold.solver
+handlers=consoleHandler
+propagate=0
+
+[handler_consoleHandler]
+class=StreamHandler
+level=INFO
+formatter=simpleFormatter
+args=(sys.stdout,)
+
+[formatter_simpleFormatter]
+class=uvicorn.logging.ColourizedFormatter
+format={levelprefix:<8} @ {name} : {message}
+style={
+use_colors=True

pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[project]
+name = "vehicle_routing"
+version = "1.0.1"
+requires-python = ">=3.10"
+dependencies = [
+    'solverforge-legacy == 1.24.1',
+    'fastapi == 0.111.0',
+    'pydantic == 2.7.3',
+    'uvicorn == 0.30.1',
+    'pytest == 8.2.2',
+]
+
+
+[project.scripts]
+run-app = "vehicle_routing:main"

src/vehicle_routing/__init__.py

@@ -0,0 +1,17 @@
+import uvicorn
+
+from .rest_api import app as app
+
+
+def main():
+    config = uvicorn.Config("vehicle_routing:app",
+                            host=0.0.0.0
+                            port=8080,
+                            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,67 @@
+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"
+
+
+@constraint_provider
+def define_constraints(factory: ConstraintFactory):
+    return [
+        # Hard constraints
+        vehicle_capacity(factory),
+        service_finished_after_max_end_time(factory),
+        # 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)
+    )

src/vehicle_routing/converters.py

@@ -0,0 +1,221 @@
+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,
+        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,
+    )
+
+
+# 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,212 @@
+from typing import Generator, TypeVar, Sequence
+from datetime import date, datetime, time, timedelta
+from enum import Enum
+from random import Random
+from dataclasses import dataclass
+
+from .domain import Location, Vehicle, VehicleRoutePlan, Visit, init_driving_time_matrix, clear_driving_time_matrix
+
+
+FIRST_NAMES = ("Amy", "Beth", "Carl", "Dan", "Elsa", "Flo", "Gus", "Hugo", "Ivy", "Jay")
+LAST_NAMES = ("Cole", "Fox", "Green", "Jones", "King", "Li", "Poe", "Rye", "Smith", "Watt")
+
+# 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):
+    PHILADELPHIA = _DemoDataProperties(0, 55, 6, time(6, 0),
+                                       15, 30,
+                                       Location(latitude=39.7656099067391,
+                                                longitude=-76.83782328143754),
+                                       Location(latitude=40.77636644354855,
+                                                longitude=-74.9300739430771))
+
+    HARTFORT = _DemoDataProperties(1, 50, 6, time(6, 0),
+                                   20, 30,
+                                   Location(latitude=41.48366520850297,
+                                            longitude=-73.15901689943055),
+                                   Location(latitude=41.99512052869307,
+                                            longitude=-72.25114548877427))
+
+    FIRENZE = _DemoDataProperties(2, 77, 6, time(6, 0),
+                                  20, 40,
+                                  Location(latitude=43.751466,
+                                           longitude=11.177210),
+                                  Location(latitude=43.809291,
+                                           longitude=11.290195))
+
+
+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, use_precomputed_matrix: bool = False) -> VehicleRoutePlan:
+    """
+    Generate demo data for vehicle routing.
+
+    Creates a realistic delivery scenario with three customer types:
+    - Residential (50%): Evening windows (17:00-20:00), small orders (1-2 units)
+    - Business (30%): Business hours (09:00-17:00), medium orders (3-6 units)
+    - Restaurant (20%): Early morning (06:00-10:00), large orders (5-10 units)
+
+    Args:
+        demo_data_enum: The demo data configuration to use
+        use_precomputed_matrix: If True, pre-compute driving time matrix for O(1) lookups.
+                               If False (default), calculate distances on-demand.
+                               Pre-computed is faster during solving but uses O(n²) memory.
+    """
+    name = "demo"
+    demo_data = demo_data_enum.value
+    random = Random(demo_data.seed)
+    latitudes = doubles(random, demo_data.south_west_corner.latitude, demo_data.north_east_corner.latitude)
+    longitudes = doubles(random, demo_data.south_west_corner.longitude, demo_data.north_east_corner.longitude)
+
+    vehicle_capacities = ints(random, demo_data.min_vehicle_capacity,
+                              demo_data.max_vehicle_capacity + 1)
+
+    vehicles = [Vehicle(id=str(i),
+                        name=VEHICLE_NAMES[i % len(VEHICLE_NAMES)],
+                        capacity=next(vehicle_capacities),
+                        home_location=Location(
+                            latitude=next(latitudes),
+                            longitude=next(longitudes)),
+                        departure_time=datetime.combine(
+                            date.today() + timedelta(days=1), demo_data.vehicle_start_time)
+                        )
+                for i in range(demo_data.vehicle_count)]
+
+    names = generate_names(random)
+    tomorrow = date.today() + timedelta(days=1)
+
+    visits = []
+    for i in range(demo_data.visit_count):
+        ctype = random_customer_type(random)
+        service_minutes = random.randint(ctype.min_service_minutes, ctype.max_service_minutes)
+        visits.append(
+            Visit(
+                id=str(i),
+                name=next(names),
+                location=Location(latitude=next(latitudes), longitude=next(longitudes)),
+                demand=random.randint(ctype.min_demand, ctype.max_demand),
+                min_start_time=datetime.combine(tomorrow, ctype.window_start),
+                max_end_time=datetime.combine(tomorrow, ctype.window_end),
+                service_duration=timedelta(minutes=service_minutes),
+            )
+        )
+
+    # Handle driving time calculation mode
+    if use_precomputed_matrix:
+        # Pre-compute driving time matrix for faster solving
+        all_locations = [v.home_location for v in vehicles] + [v.location for v in visits]
+        init_driving_time_matrix(all_locations)
+    else:
+        # Clear any existing pre-computed matrix to ensure on-demand calculation
+        clear_driving_time_matrix()
+
+    return VehicleRoutePlan(name=name,
+                            south_west_corner=demo_data.south_west_corner,
+                            north_east_corner=demo_data.north_east_corner,
+                            vehicles=vehicles,
+                            visits=visits)
+
+
+def tomorrow_at(local_time: time) -> datetime:
+    return datetime.combine(date.today(), local_time)

src/vehicle_routing/domain.py

@@ -0,0 +1,381 @@
+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
+from dataclasses import dataclass, field
+from .json_serialization import JsonDomainBase
+from pydantic import Field
+
+
+# Global driving time matrix for pre-computed mode
+# Key: (from_lat, from_lng, to_lat, to_lng) -> driving_time_seconds
+# This is kept outside the Location class to avoid transpiler issues with mutable fields
+_DRIVING_TIME_MATRIX: dict[tuple[float, float, float, float], int] = {}
+
+
+def _get_matrix_key(from_loc: "Location", to_loc: "Location") -> tuple[float, float, float, float]:
+    """Create a hashable key for the driving time matrix lookup."""
+    return (from_loc.latitude, from_loc.longitude, to_loc.latitude, to_loc.longitude)
+
+
+@dataclass
+class Location:
+    """
+    Represents a geographic location with latitude and longitude.
+
+    Driving times can be calculated in two modes:
+    1. On-demand (default): Uses Haversine formula for each calculation
+    2. Pre-computed matrix: O(1) lookup from global pre-calculated distance matrix
+
+    The pre-computed mode is faster during solving (millions of lookups)
+    but requires O(n²) memory and one-time initialization cost.
+
+    To enable pre-computed mode, call init_driving_time_matrix() with all locations
+    before solving.
+    """
+    latitude: float
+    longitude: float
+
+    # 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
+
+    def driving_time_to(self, other: "Location") -> int:
+        """
+        Get driving time in seconds to another location.
+
+        If a pre-computed matrix is available (via init_driving_time_matrix),
+        uses O(1) lookup. Otherwise, calculates on-demand using Haversine formula.
+        """
+        # Use pre-computed matrix if available
+        key = _get_matrix_key(self, other)
+        if key in _DRIVING_TIME_MATRIX:
+            return _DRIVING_TIME_MATRIX[key]
+
+        # Fall back to on-demand calculation
+        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})"
+
+
+def init_driving_time_matrix(locations: list[Location]) -> None:
+    """
+    Pre-compute driving times between all location pairs.
+
+    This trades O(n²) memory for O(1) lookup during solving.
+    For n=77 locations (FIRENZE), this is only 5,929 entries.
+
+    Call this once after creating all locations but before solving.
+    The matrix is stored globally and persists across solver runs.
+    """
+    global _DRIVING_TIME_MATRIX
+    _DRIVING_TIME_MATRIX = {}
+    for from_loc in locations:
+        for to_loc in locations:
+            key = _get_matrix_key(from_loc, to_loc)
+            _DRIVING_TIME_MATRIX[key] = from_loc._calculate_driving_time_haversine(to_loc)
+
+
+def clear_driving_time_matrix() -> None:
+    """Clear the pre-computed driving time matrix."""
+    global _DRIVING_TIME_MATRIX
+    _DRIVING_TIME_MATRIX = {}
+
+
+def is_driving_time_matrix_initialized() -> bool:
+    """Check if the driving time matrix has been pre-computed."""
+    return len(_DRIVING_TIME_MATRIX) > 0
+
+
+@planning_entity
+@dataclass
+class Visit:
+    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
+
+    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
+    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")

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,241 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.staticfiles import StaticFiles
+from uuid import uuid4
+from typing import Dict, List
+from dataclasses import asdict
+
+from .domain import VehicleRoutePlan
+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 pydantic import BaseModel, Field
+
+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]
+
+@app.get("/demo-data/{demo_name}", response_model=VehicleRoutePlanModel)
+async def get_demo_data_by_name(demo_name: str, distanceMode: str = "ON_DEMAND") -> VehicleRoutePlanModel:
+    """
+    Get a specific demo data set.
+
+    Args:
+        demo_name: Name of the demo dataset (PHILADELPHIA, HARTFORT, FIRENZE)
+        distanceMode: Distance calculation mode:
+            - ON_DEMAND: Calculate distances using Haversine formula on each call (default)
+            - PRECOMPUTED: Pre-compute distance matrix for O(1) lookups (faster solving)
+    """
+    try:
+        demo_data = DemoData[demo_name]
+        use_precomputed = distanceMode == "PRECOMPUTED"
+        domain_plan = generate_demo_data(demo_data, use_precomputed_matrix=use_precomputed)
+        return plan_to_model(domain_plan)
+    except KeyError:
+        raise HTTPException(status_code=404, detail=f"Demo data '{demo_name}' not found")
+
+@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)
+
+
+app.mount("/", StaticFiles(directory="static", html=True), name="static")

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,1344 @@
+let autoRefreshIntervalId = null;
+let initialized = false;
+let optimizing = false;
+let demoDataId = null;
+let scheduleId = null;
+let loadedRoutePlan = null;
+let newVisit = null;
+let visitMarker = null;
+const solveButton = $("#solveButton");
+const stopSolvingButton = $("#stopSolvingButton");
+const vehiclesTable = $("#vehicles");
+const analyzeButton = $("#analyzeButton");
+
+/*************************************** 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;
+      }
+    }
+  });
+
+  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}`;
+}
+
+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
+  renderRoutes(loadedRoutePlan);
+  renderTimelines(loadedRoutePlan);
+
+  showNotification(`Vehicle "${vehicleName}" added successfully!`, "success");
+}
+
+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
+  renderRoutes(loadedRoutePlan);
+  renderTimelines(loadedRoutePlan);
+
+  showNotification(`Vehicle "${lastVehicle.name || lastVehicle.id}" removed.`, "info");
+}
+
+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
+  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]
+  });
+}
+
+function renderRouteLines(highlightedId = null) {
+  routeGroup.clearLayers();
+
+  if (!loadedRoutePlan) return;
+
+  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;
+
+    if (locations.length > 0) {
+      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;
+}
+
+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
+  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();
+
+  $.each(routePlan.vehicles, function (index, vehicle) {
+    const { totalDemand, capacity } = vehicle;
+    const percentage = (totalDemand / capacity) * 100;
+    const vehicleWithLoad = `<h5 class="card-title mb-1">vehicle-${vehicle.id}</h5>
+                                 <div class="progress" data-bs-toggle="tooltip-load" data-bs-placement="left"
+                                      data-html="true" title="Cargo: ${totalDemand} / Capacity: ${capacity}">
+                                   <div class="progress-bar" 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 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(
+        $(`<h5 class="card-title mb-1"/>`).text(`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 arrivalPlusService = arrivalTime.plus(serviceDuration);
+      const afterDue = arrivalPlusService.isAfter(maxEndTime);
+
+      const byVehicleElement = $(`<div/>`)
+        .append("<div/>")
+        .append($(`<h5 class="card-title mb-1"/>`).html(
+          `<i class="fas ${customerType.icon}" style="color: ${customerType.color}"></i> ${visit.name}`
+        ));
+
+      const byVisitElement = $(`<div/>`)
+        // visit.vehicle is the vehicle.id due to Jackson serialization
+        .append(
+          $(`<h5 class="card-title mb-1"/>`).text("vehicle-" + visit.vehicle),
+        );
+
+      const byVehicleTravelElement = $(`<div/>`).append(
+        $(`<h5 class="card-title mb-1"/>`).text("Travel"),
+      );
+
+      const previousDeparture = arrivalTime.minusSeconds(
+        visit.drivingTimeSecondsFromPreviousStandstill,
+      );
+      byVehicleItemData.add({
+        id: visit.id + "_travel",
+        group: visit.vehicle, // visit.vehicle is the vehicle.id due to Jackson serialization
+        subgroup: visit.vehicle,
+        content: byVehicleTravelElement.html(),
+        start: previousDeparture.toString(),
+        end: visit.arrivalTime,
+        style: "background-color: #f7dd8f90",
+      });
+      if (beforeReady) {
+        const byVehicleWaitElement = $(`<div/>`).append(
+          $(`<h5 class="card-title mb-1"/>`).text("Wait"),
+        );
+
+        byVehicleItemData.add({
+          id: visit.id + "_wait",
+          group: visit.vehicle, // visit.vehicle is the vehicle.id due to Jackson serialization
+          subgroup: visit.vehicle,
+          content: byVehicleWaitElement.html(),
+          start: visit.arrivalTime,
+          end: visit.minStartTime,
+        });
+      }
+      let serviceElementBackground = afterDue ? "#EF292999" : "#83C15955";
+
+      byVehicleItemData.add({
+        id: visit.id + "_service",
+        group: visit.vehicle, // visit.vehicle is the vehicle.id due to Jackson serialization
+        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, // visit.vehicle is the vehicle.id due to Jackson serialization
+          subgroup: vehicle.id,
+          content: $(`<div/>`)
+            .append($(`<h5 class="card-title mb-1"/>`).text("Travel"))
+            .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"
+  );
+}
+
+function updateSolutionWithNewVisit(newSolution) {
+  loadedRoutePlan = newSolution;
+  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() {
+  $.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;
+    }
+  }
+}
+
+function refreshRoutePlan() {
+  let path = "/route-plans/" + scheduleId;
+  if (scheduleId === null) {
+    if (demoDataId === null) {
+      alert("Please select a test data set.");
+      return;
+    }
+
+    path = "/demo-data/" + demoDataId;
+  }
+
+  $.getJSON(path, function (routePlan) {
+    loadedRoutePlan = routePlan;
+    refreshSolvingButtons(
+      routePlan.solverStatus != null &&
+        routePlan.solverStatus !== "NOT_SOLVING",
+    );
+    renderRoutes(routePlan);
+    renderTimelines(routePlan);
+    initialized = true;
+  }).fail(function (xhr, ajaxOptions, thrownError) {
+    showError("Getting route plan has failed.", xhr);
+    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="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,394 @@
+<!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;
+    }
+  </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="true">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>
+
+<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 ~150km with Haversine."""
+        props = DemoData.PHILADELPHIA.value
+        diagonal_seconds = props.south_west_corner.driving_time_to(
+            props.north_east_corner
+        )
+        diagonal_km = (diagonal_seconds / 3600) * 50  # 50 km/h average
+
+        # Philadelphia area is roughly 100km x 170km
+        # Diagonal should be around 150-200km
+        assert 100 < diagonal_km < 250, f"Diagonal {diagonal_km}km seems wrong"
+
+    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(120)  # Allow 2 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 60 seconds for the solver to find a feasible solution
+    ATTEMPTS = 600  # 60 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}")
+    fail(f'Solution is not feasible after 60 seconds. Best score: {best_score}')

tests/test_haversine.py

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