docs: update vehicle routing use case guide by TomCools · Pull Request #2691 · TimefoldAI/timefold-solver

TomCools · 2026-09-23T19:57:42Z

Updated the vehicle routing use case guide to use the new service module. We don't describe everything in detail yet, but at least it mentions the maps service and the updated structure (to better lean into incremental) which I'm also fixing in TimefoldAI/timefold-quickstarts#1218.

Copilot

Copilot review overview

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 1

Open (2)

Qualify constraint justifications as Enterprise-only · New
Mark score analysis endpoint as Enterprise-only · New

What changed in this PR

Updates the vehicle-routing guide to use the service module, maps enrichment, asynchronous REST APIs, and incremental shadow variables.

Changes:

Reworks the domain model and constraints for medium-score unassigned visits.
Adds DTOs, model conversion, REST configuration, and service testing guidance.
Updates the quickstart source link and service-module Maven setup.

File	Description
docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/vehicle-routing-solution.adoc	Updated as part of this pull request.
docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/vehicle-routing-model.adoc	Updated as part of this pull request.
docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/vehicle-routing-constraints.adoc	Updated as part of this pull request.
docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/vehicle-routing-api.adoc	Updated as part of this pull request.
docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/quarkus-vehicle-routing-quickstart.adoc	Updated as part of this pull request.
docs/src/modules/ROOT/pages/_attributes.adoc	Updated as part of this pull request.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

triceo

I am adding a few comments, but mostly this PR is for @rsynek to review.

Copilot

Copilot review overview

🟡 Changes recommended

One or more issues must be addressed before approval.

Review effort: Lite
Findings: 1

Open (1)

Clarify that the weigher maximizes service duration, not visit count · New

Resolved since last review (2)

Qualify constraint justifications as Enterprise-only
Mark score analysis endpoint as Enterprise-only

Copilot

Copilot review overview

🟡 Changes recommended

One or more issues must be addressed before approval.

Review effort: Lite
Findings: 1 · 1

Open (2)

Invalid non-numeric configuration value causes application startup failure · New
Clarify that the weigher maximizes service duration, not visit count

Copilot

Copilot review overview

🟡 Changes recommended

One or more issues must be addressed before approval.

Review effort: Lite
Findings: 1

Open (1)

Reject duplicate visit IDs instead of silently discarding visits · New

Resolved since last review (2)

Invalid non-numeric configuration value causes application startup failure
Clarify that the weigher maximizes service duration, not visit count

Copilot

🔵 Needs a closer look

One or more issues must be addressed before approval.

0 open findings

🧠 Review effort: Lite

Change handling of duplicate visit IDs in visitMap collection. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Clarified the description of the 'enable-fallback' option to specify that it applies when the remote service is unavailable. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

TomCools · 2026-10-26T07:47:49Z

@rsynek, update this so it fixes all merge issues.

Copilot

🟡 Changes recommended

Unresolved critical conversion and map-handling issues, plus moderate constraint and testing issues, remain.

2 open issues

_{Review effort: Lite}

Copilot

🔵 Needs a closer look

A moderate active finding remains because the match weight optimizes assigned service duration rather than the documented goal of maximizing the number of assigned visits.

No open issues 🎉

2 resolved since last review

_{Review effort: Lite}

Copilot

🟡 Changes recommended

Active critical and moderate issues remain, including crashes on unreachable routes, inefficient duplicate location handling, and an incorrect visit-count constraint definition.

4 open issues

_{Review effort: Lite}

+    public double getNearbyDistance(Visit origin, LocationAware destination) {
+        return origin.getLocation().getTravelTimeTo(destination.getLocation()).seconds();


            return 0;
        }
-        return cumulativeDrivingTime + lastVisit.getLocation().getDrivingTimeTo(homeLocation);
+        return cumulativeDrivingTime + lastVisit.getLocation().getTravelTimeTo(homeLocation).seconds();


@@ -149,22 +111,26 @@ Specifically, these classes are the input of the problem:
 * The `vehicles` field with all vehicles
 ** This is a list of planning entities, because they change during solving.


+    }
+
+    private static Location toLocation(LocationInputDTO dto) {
+        return new Location(dto.latitude(), dto.longitude());


rsynek

Nicely written! Please see my question and comments inline; some parts may need a bit of polishing.

rsynek · 2026-11-04T14:30:12Z


 @QuarkusTest
-class VehicleRoutingConstraintProviderTest {
+class VehicleRoutePlanConstraintProviderTest {


The test content looks very different from what we have in the qs/use-cases/vehicle-routing. It's it a bit confusing for the reader?

rsynek · 2026-11-04T14:33:21Z

-                .body(vehicleRoutePlan)
-                .expect().contentType(ContentType.TEXT)
-                .when().post("/route-plans")
+                .body(mapper.writeValueAsString(Map.of("modelInput", input)))


No need to go for random object serialized to JSON. We have the ModelRequest in the solver-service that acts as the top-level DTO and contains the modelInput field.

rsynek · 2026-11-04T14:35:47Z

+=== Generate the initial OpenAPI specification

-This test verifies that after solving that it found a feasible solution (no hard constraints broken).
+Before running a full build with `mvn install`, generate the initial OpenAPI specification file.


This has been already improved and if the file is missing, the maven build generates it. Just checked that with the QS. Feel free to try for yourself.

rsynek · 2026-11-04T15:04:46Z

            return 0;
        }
+
        Visit lastVisit = visits.get(visits.size() - 1);


Strictly speaking, this is a dangerous pattern to teach our users. If the related constraint starts from a vehicle shift and does not join the last visit, there is a risk of a score corruption, since Bavet won't propagate the last visit's change to this constraint.

Not introduced to this PR, so not in scope to fix it here. Also, we have it in the QS for a while already.

rsynek · 2026-11-04T15:26:55Z

    }

-    protected Constraint vehicleCapacity(ConstraintFactory factory) {
+    public Constraint vehicleCapacity(ConstraintFactory factory) {


Nitpick: the way the constraint is written allows temporary inconsistencies:
vehicle capacity = 10, visit A demands 12, the next visit B demands -4, which leads to no penalty.

rsynek · 2026-11-04T15:31:27Z

-    constructor()
+    // Every solve builds its own one-off matrix rather than reusing a named, pre-built one.
+    @Override
+    public Optional<String> getLocationSetName() {


Can be removed, as the interface already comes with a default impl.

See https://github.com/TimefoldAI/timefold-solver/blob/main/service/maps/service-integration/src/main/java/ai/timefold/solver/service/maps/service/integration/api/LocationsAwareSolverModel.java#L24.

rsynek · 2026-11-04T15:31:53Z

-import org.acme.vehiclerouting.domain.Location;
+* `getLocations()` returns every location the matrix needs to cover:
+every vehicle's home location plus every visit's location.
+* `getLocationSetName()` returns empty, so each solve builds its own one-off matrix


See my above comment; perhaps not worth even mentioning the method here.

rsynek · 2026-11-04T15:33:07Z

----
--
-====
+Running locally, you use the local computation.


Should we at least mention that locally we use the Haversine with a fixed speed factor?

rsynek · 2026-11-04T15:42:22Z

+----
+package org.acme.vehiclerouting.dto.input;
+
+public record LocationInputDTO(Double latitude, Double longitude) {


Any particular reason to duplicate the original Location? It's JSON-serializable and used across our models.

TomCools temporarily deployed to internal September 23, 2026 19:57 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) September 23, 2026 19:58 — with GitHub Actions

View deployment

TomCools marked this pull request as ready for review September 25, 2026 07:47

TomCools requested review from a team and a lite review from Copilot September 25, 2026 07:47

TomCools requested review from rsynek and triceo as code owners September 25, 2026 07:47

TomCools temporarily deployed to internal September 25, 2026 07:47 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) September 25, 2026 07:47 — with GitHub Actions

View deployment

Copilot started reviewing on behalf of TomCools September 25, 2026 07:48

View session

Copilot AI reviewed Sep 25, 2026

View reviewed changes

Comment thread docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/vehicle-routing-constraints.adoc Resolved

Comment thread ...odules/ROOT/pages/quickstart/quarkus-vehicle-routing/quarkus-vehicle-routing-quickstart.adoc Resolved

triceo reviewed Sep 25, 2026

View reviewed changes

Comment thread ...odules/ROOT/pages/quickstart/quarkus-vehicle-routing/quarkus-vehicle-routing-quickstart.adoc Resolved

Comment thread ...odules/ROOT/pages/quickstart/quarkus-vehicle-routing/quarkus-vehicle-routing-quickstart.adoc Resolved

Copilot AI review requested due to automatic review settings September 29, 2026 08:44

TomCools temporarily deployed to internal September 29, 2026 08:44 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) September 29, 2026 08:44 — with GitHub Actions

View deployment

Copilot started reviewing on behalf of TomCools September 29, 2026 08:44

View session

TomCools temporarily deployed to internal September 29, 2026 08:49 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) September 29, 2026 08:49 — with GitHub Actions

View deployment

Copilot AI reviewed Sep 29, 2026

View reviewed changes

Comment thread docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/vehicle-routing-constraints.adoc Resolved

Copilot AI review requested due to automatic review settings September 29, 2026 08:53

Copilot started reviewing on behalf of TomCools September 29, 2026 08:53

View session

Copilot AI reviewed Sep 29, 2026

View reviewed changes

Comment thread ...odules/ROOT/pages/quickstart/quarkus-vehicle-routing/quarkus-vehicle-routing-quickstart.adoc Resolved

Copilot AI review requested due to automatic review settings September 29, 2026 09:12

TomCools temporarily deployed to internal September 29, 2026 09:12 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) September 29, 2026 09:12 — with GitHub Actions

View deployment

Copilot started reviewing on behalf of TomCools September 29, 2026 09:13

View session

Copilot AI reviewed Sep 29, 2026

View reviewed changes

Comment thread docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/vehicle-routing-api.adoc Resolved

Copilot AI lite review requested due to automatic review settings October 4, 2026 13:01

TomCools temporarily deployed to internal October 4, 2026 13:01 — with GitHub Actions Inactive

Copilot started reviewing on behalf of TomCools October 16, 2026 07:01

View session

Copilot AI reviewed Oct 16, 2026

View reviewed changes

TomCools and others added 6 commits October 26, 2026 08:47

docs: update vehicle routing use case guide

05af41d

docs: no enterprise by default

d5a8f08

docs: small clarifications

60fd467

docs: small clarifications

10d5e33

Improve duplicate visit ID handling in visitMap

e9c5492

Change handling of duplicate visit IDs in visitMap collection. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Update 'enable-fallback' description for clarity

785b3c0

Clarified the description of the 'enable-fallback' option to specify that it applies when the remote service is unavailable. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

TomCools force-pushed the docs/update-vehicle-routing branch from 8005ece to 785b3c0 Compare October 26, 2026 07:47

Copilot AI lite review requested due to automatic review settings October 26, 2026 07:47

TomCools temporarily deployed to internal October 26, 2026 07:47 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) October 26, 2026 07:47 — with GitHub Actions

View deployment

Copilot started reviewing on behalf of TomCools October 26, 2026 07:47

View session

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Comment thread docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/vehicle-routing-api.adoc Resolved

Comment thread docs/src/modules/ROOT/pages/quickstart/quarkus-vehicle-routing/vehicle-routing-solution.adoc Resolved

chore: resolve review comments

9f69192

Copilot AI lite review requested due to automatic review settings October 30, 2026 11:39

TomCools temporarily deployed to internal October 30, 2026 11:39 — with GitHub Actions Inactive

Merge branch 'main' into docs/update-vehicle-routing

53337c3

TomCools temporarily deployed to internal October 30, 2026 11:39 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) October 30, 2026 11:39 — with GitHub Actions

View deployment

Copilot started reviewing on behalf of TomCools October 30, 2026 11:40

View session

Copilot AI reviewed Oct 30, 2026

View reviewed changes

Merge branch 'main' into docs/update-vehicle-routing

632efcf

Copilot AI lite review requested due to automatic review settings October 30, 2026 13:33

TomCools temporarily deployed to internal October 30, 2026 13:33 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) October 30, 2026 13:33 — with GitHub Actions

View deployment

Copilot started reviewing on behalf of TomCools October 30, 2026 13:34

View session

Copilot AI reviewed Oct 30, 2026

View reviewed changes

rsynek requested changes Nov 4, 2026

View reviewed changes

		public double getNearbyDistance(Visit origin, LocationAware destination) {
		return origin.getLocation().getTravelTimeTo(destination.getLocation()).seconds();

		@@ -149,22 +111,26 @@ Specifically, these classes are the input of the problem:
		* The `vehicles` field with all vehicles
		** This is a list of planning entities, because they change during solving.

Conversation

TomCools commented Sep 23, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

triceo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

TomCools commented Oct 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

rsynek left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects