docs: Introduce initial docs for service module (Preview) by TomCools · Pull Request #2350 · TimefoldAI/timefold-solver

TomCools · 2026-06-10T07:56:49Z

Currently providing this PR in DRAFT as a preview of the changes to come. Some content still needs validation and review from my side: e.g. going through the quickstart guide myself again and updating some references, after the service module has been officially released.

We have introduced the "Service" module, but this did not contain any documentation yet.

This PR will:

Label some existing pages to be reworked (frontmatter data, no further impact)
Introduce a new navigation item: Building a service (Preview)
Introduce a couple of pages which describe basic service capabilities
Introduce a new quickstart explicitly built using the service module, and reworked some of the shared files to avoid too much duplication across quickstarts.
Rework the quickstart page to mention the distinction between using the solver as a library vs a service

triceo

Some notes after a first quick look.

triceo · 2026-06-10T10:03:19Z

 :sectnums:
 :icons: font
+:relevance: both
+:notes: Relevant, needs some rewrites. Also should include the "Getting Started" for Quarkus (raw) and Spring


Is this a third thing? "core", "service" and "raw"?

raw => Core + Quarkus plugin integration. That should be clarified. It's the weird double right now.

triceo · 2026-06-10T10:06:10Z

@@ -0,0 +1,28 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"


I never much liked copy-pasting stuff from production code. Gets quickly outdated and forgotten about, until some user points it out.

Any chance we could have a live mechanism to point to an authoritative piece of source code, such as one in the quickstarts repo?

Under investigation ;) We have a similar problem for all of the quickstarts btw.

triceo · 2026-06-10T10:08:24Z

+
+* **Knowledge**
+** Java (Basic)
+** Quarkus (Basic)


This is IMO where you immediately lose Spring people.
We can only keep Spring people if we treat the service as a black box that uses no technology which the user needs to care about.

Q: What is the exact quarkus knowledge that is needed?

Until we fully abstract Quarkus away and it is a black box, the reference should stay. It's just being up-front of what is needed.

oemebamo

I know this is a draft pr, but already some quick comments.

Great work @TomCools ❤️

oemebamo · 2026-06-10T11:20:22Z

+Open the http://localhost:8080/q/swagger-ui/[Swagger OpenAPI Viewer] to inspect the generated API Endpoints:
+http://localhost:8080/q/swagger-ui/
+
+image:quickstart/mdk/openapi.png[Screenshot of the Swagger OpenAPI UI showing the automatically generated REST API endpoints]


Folder name "mdk" to be updated?

oemebamo · 2026-06-10T11:21:55Z

 :sectnums:
 :icons: font

+:relevance: both


:relevance: is just something internal? an annotation? or does it trigger something automatically?

Doesn't trigger anything, just metadata for me while refactoring the docs, so i don't have to keep a separate file with this info.

oemebamo · 2026-06-10T11:40:13Z

+
+include::_preview-note.adoc[]
+
+Run optimization as a fully isolated service.


PP: Dataset optimization

oemebamo · 2026-06-10T11:41:28Z

+        "name": "run name",
+        "termination": {
+          "spentLimit": "PT5M",
+          "unimprovedSpentLimit": "PT10S"


Q: There probably are more terminations now? stepCount?

I will make an issue to tackle this. Describing the terminations would be a new section.
#2359

External loading doesn't work in Antora, at least not close to the source.

TomCools · 2026-06-12T18:27:24Z

Moving this to a full PR (no longer draft). I have added tickets for most tasks, still left a few TODOs in the code (which doesn't get rendered.

TomCools · 2026-06-12T18:29:28Z

I remembered I still need to update some of the maven dependencies and links after the final merge, so making it draft again.

Copilot

Pull request overview

This draft PR introduces initial documentation for the new “Service” module (Preview), adds navigation and quickstart content for running Timefold Solver as an isolated optimization service, and annotates existing docs pages with metadata intended to guide future service-vs-library refactoring.

Changes:

Add a new “Building a service (Preview)” documentation section covering REST API, model enrichment, constraint weight overrides, demo data, and metrics.
Introduce a new “Run as a service (Preview)” quickstart and restructure the quickstart overview/navigation to distinguish library embedding vs service deployment.
Add :relevance:/:notes: metadata to a number of existing pages to flag future content splits/rework.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
docs/src/modules/ROOT/pages/using-timefold-solver/running-the-solver.adoc	Adds service-vs-core relevance metadata to the “Running the solver” page.
docs/src/modules/ROOT/pages/using-timefold-solver/overview.adoc	Adds relevance metadata to indicate shared applicability across library/service.
docs/src/modules/ROOT/pages/using-timefold-solver/modeling-planning-problems.adoc	Adds relevance metadata and notes about shared vs service-specific modeling.
docs/src/modules/ROOT/pages/using-timefold-solver/configuration.adoc	Marks configuration docs as core-only via relevance metadata.
docs/src/modules/ROOT/pages/using-timefold-solver/benchmarking-and-tweaking.adoc	Adds relevance metadata to indicate partial applicability in service mode.
docs/src/modules/ROOT/pages/service/rest-api.adoc	New service REST API documentation (generated endpoints, request/response envelope, OpenAPI, validation, etc.).
docs/src/modules/ROOT/pages/service/overview.adoc	New top-level “Building a service (Preview)” landing page tying service docs to core concepts.
docs/src/modules/ROOT/pages/service/modeling-changes.adoc	New documentation on service-specific modeling concepts (SolverModel, enrichers, enrichment director).
docs/src/modules/ROOT/pages/service/exposing-metrics.adoc	New documentation for exposing input/output metrics via the service REST API.
docs/src/modules/ROOT/pages/service/demo-data.adoc	New documentation for exposing demo data endpoints via a DemoDataGenerator.
docs/src/modules/ROOT/pages/service/constraint-weights.adoc	New documentation describing ModelConfigOverrides and constraint weight overrides in service mode.
docs/src/modules/ROOT/pages/service/_preview-note.adoc	Adds a shared preview note included by service pages.
docs/src/modules/ROOT/pages/responding-to-change/responding-to-change.adoc	Adds relevance metadata noting service-vs-library differences.
docs/src/modules/ROOT/pages/quickstart/shared/school-timetabling/_school-timetabling-solution.adoc	Refactors repeated content into shared include files to reduce duplication.
docs/src/modules/ROOT/pages/quickstart/shared/school-timetabling/_school-timetabling-solution-value-range-providers.adoc	New shared include covering value range providers.
docs/src/modules/ROOT/pages/quickstart/shared/school-timetabling/_school-timetabling-solution-facts-and-entities.adoc	New shared include covering problem facts vs planning entities.
docs/src/modules/ROOT/pages/quickstart/shared/school-timetabling/_school-timetabling-model.adoc	Updates quickstart model docs (including switching Room example to a Java record).
docs/src/modules/ROOT/pages/quickstart/shared/school-timetabling/_school-timetabling-constraints.adoc	Updates constraint intro and links for the quickstart.
docs/src/modules/ROOT/pages/quickstart/shared/_whatyoubuild.adoc	Rewords “What you will build” to be less REST/service-specific.
docs/src/modules/ROOT/pages/quickstart/service/getting-started.adoc	New quickstart for building and running a service-based optimization model (Preview).
docs/src/modules/ROOT/pages/quickstart/overview.adoc	Reworks quickstart overview to compare “library” vs “service” approaches and introduce the new service quickstart.
docs/src/modules/ROOT/pages/optimization-algorithms/overview.adoc	Adds relevance metadata indicating applicability to both library and service usage.
docs/src/modules/ROOT/pages/introduction.adoc	Adds relevance metadata and notes to support future library-vs-service clarification.
docs/src/modules/ROOT/pages/integration/integration.adoc	Adds relevance metadata and notes about needed updates for service integration.
docs/src/modules/ROOT/pages/frequently-asked-questions.adoc	Adds relevance metadata.
docs/src/modules/ROOT/pages/design-patterns/design-patterns.adoc	Adds relevance metadata and internal notes about future restructuring.
docs/src/modules/ROOT/pages/constraints-and-score/overview.adoc	Adds relevance metadata for shared applicability.
docs/src/modules/ROOT/pages/constraints-and-score/constraint-configuration.adoc	Adds relevance metadata and notes about service-specific patterns.
docs/src/modules/ROOT/nav.adoc	Updates navigation to introduce “Run as a service (Preview)” and a library/service split in Getting Started, plus a new service docs subtree.

+== Request and response structure
+
+The generated endpoints do not accept/return the pure `ModelInput`/`ModelOutput` objects as JSON.
+Instead, a fixed envelop is used for both the requests and responses of solver actions.


+  "modelOutput": <ModelOutput class as JSON>,
+  "inputMetrics": {


+@ApplicationScoped
+public class TimetableConvertor implements ModelConvertor<HardSoftLongScore, TimetableDto, Timetable, EmptyModelConfigOverrides, EmptyModelInputMetrics, EmptyModelOutputMetrics, Timetable> {
+
+    @Override
+    public Timetable toSolverModel(TimetableDto modelInput, TimetableDto previousModelOutput, ModelConfig<EmptyModelConfigOverrides> modelConfig) {
+        return // Mapping logic
+    }
+
+    @Override
+    public Timetable toSolverModel(TimetableDto modelInput, ModelConfig<EmptyModelConfigOverrides> modelConfig) {
+        return // Mapping logic
+    }
+
+    @Override
+    public TimetableDto toModelOutput(Timetable solverModel) {
+        return // Mapping logic
+    }
+}


+`GET /v1/timetables/+{id}+/validation-result`
+
+Assuming the xref:timetableValidatorExample[example TimetableValidator], the endpoint provides the following response:
+
+.Validation result available via `GET /v1/timetables/+{id}+/validation-result`.


+To showcase that the model is now ready for use we only need 2 of those endpoints:
+
+- `POST /v1/timetables`: To request a problem to be solved. This returns a unique identifier which can be used to request the resulting schedule.
+- `GET /v1/timetables/+{id}+`: Get the calculated schedule with the given identifier.


+To calculate the score, implement a `TimetableConstraintProvider` class.
+It uses Timefold Solver's xref:https://docs.timefold.ai/timefold-solver/latest/constraints-and-score/score-calculation[Constraint Streams API]
 which is inspired by Java Streams and SQL:


+Your application will assign `Lessons` to `Timeslots` and `Rooms` automatically
+by using AI to adhere to hard and soft scheduling _constraints_, for example:


 :sectnums:
 :icons: font
+:relevance: core-only
+:notes: Too much things service module does automatically or with 1 single configuration.


+ConstraintWeightOverrides<HardMediumSoftLongScore> constraintWeightOverrides = ConstraintWeightOverrides.none();
+constraintWeightOverrides = ConstraintWeightOverrides.of(
+                    Map.ofEntries(
+                        Map.entry(TEACHER_CONFLICT,
+                                HardMediumSoftLongScore.ofHard(modelConfigOverrides.getTeacherConflictWeight())),
+                        Map.entry(ROOM_COMFLICT,
+                                HardMediumSoftLongScore
+                                        .ofSoft(modelConfigOverrides.getRoomConflictWeight()));
+
+solverModel.setConstraintWeightOverrides(constraintWeightOverrides);


sonarqubecloud · 2026-06-12T18:48:01Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

TomCools added 5 commits June 3, 2026 15:19

docs: mark pages for TFS relevance.

bfadd5c

docs: Add content for Service approach.

5265014

docs: Update the navigation

9b5dc06

docs: remove "SDK" references

36d36c6

docs: cleanup docs

ef48163

TomCools temporarily deployed to internal June 10, 2026 07:57 — with GitHub Actions Inactive

TomCools had a problem deploying to documentation (preview) June 10, 2026 07:57 — with GitHub Actions Failure

TomCools requested a review from oemebamo June 10, 2026 08:35

triceo reviewed Jun 10, 2026

View reviewed changes

oemebamo reviewed Jun 10, 2026

View reviewed changes

docs: fix internal links

fa6edcd

TomCools temporarily deployed to internal June 10, 2026 12:10 — with GitHub Actions Inactive

TomCools had a problem deploying to documentation (preview) June 10, 2026 12:10 — with GitHub Actions Failure

docs: inline examples

2e8a5c8

External loading doesn't work in Antora, at least not close to the source.

TomCools temporarily deployed to internal June 10, 2026 13:12 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) June 10, 2026 13:12 — with GitHub Actions View deployment

docs: resolve diverse comments

a189862

TomCools temporarily deployed to internal June 11, 2026 09:21 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) June 11, 2026 09:21 — with GitHub Actions View deployment

TomCools added 2 commits June 11, 2026 11:50

docs: add nowrap option to code examples

64e345a

docs: update metrics explainer

c7e663a

TomCools temporarily deployed to internal June 11, 2026 10:00 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) June 11, 2026 10:00 — with GitHub Actions View deployment

TomCools mentioned this pull request Jun 11, 2026

Docs: Service - clarify terminations #2359

Open

docs: update folder name

6efccc4

TomCools temporarily deployed to internal June 11, 2026 12:22 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) June 11, 2026 12:22 — with GitHub Actions View deployment

docs: nav update

6c3eb88

TomCools temporarily deployed to internal June 11, 2026 12:51 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) June 11, 2026 12:51 — with GitHub Actions View deployment

TomCools changed the title ~~Introduce initial docs for service module (Preview)~~ docs: Introduce initial docs for service module (Preview) Jun 11, 2026

TomCools temporarily deployed to internal June 12, 2026 10:58 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) June 12, 2026 10:58 — with GitHub Actions View deployment

TomCools requested a review from rsynek June 12, 2026 18:23

TomCools marked this pull request as ready for review June 12, 2026 18:23

Copilot AI review requested due to automatic review settings June 12, 2026 18:23

Copilot started reviewing on behalf of TomCools June 12, 2026 18:24 View session

docs: remove navigation emojis

631a585

TomCools force-pushed the mark-relevance-in-files branch from 35dd6f5 to 631a585 Compare June 12, 2026 18:25

TomCools temporarily deployed to internal June 12, 2026 18:25 — with GitHub Actions Inactive

TomCools deployed to documentation (preview) June 12, 2026 18:25 — with GitHub Actions View deployment

TomCools marked this pull request as draft June 12, 2026 18:28

Copilot AI reviewed Jun 12, 2026

View reviewed changes

		@@ -0,0 +1,28 @@
		<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"


		include::_preview-note.adoc[]

		Run optimization as a fully isolated service.

		"modelOutput": <ModelOutput class as JSON>,
		"inputMetrics": {

		Your application will assign `Lessons` to `Timeslots` and `Rooms` automatically
		by using AI to adhere to hard and soft scheduling _constraints_, for example:

Conversation

TomCools commented Jun 10, 2026

Uh oh!

triceo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

oemebamo 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TomCools commented Jun 12, 2026

Uh oh!

TomCools commented Jun 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

sonarqubecloud Bot commented Jun 12, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants