timefold-quickstarts: worked planning examples for the Timefold solver

This repository is examples, not the solver

The distinction matters, because the name of the repository can lead you to expect either the wrong thing. This repository contains quickstarts for Timefold Solver, which is an AI constraint solver for Java and Kotlin living in its own repository. What is here is a set of runnable applications that show different use cases and basic implementations to get you started on an optimization problem.

So the solver is the dependency, and this is where you see it used. If you are deciding whether to adopt the solver, this is the place to form a judgement, because the examples are the solver's own demonstration of how its concepts are meant to fit together. If you are looking for the solver's documentation on the algorithm itself, you are in the wrong repository, and the readme points at the documentation site and the GitHub Discussions on the solver repository instead.

The scale of the collection is worth noting. There is a use-cases directory with fifteen planning problems, a getting-started directory with five projects, and a visualizations directory. Each use case has its own folder with a README, and the root of the repository is a Maven project with a pom.xml, plus a settings.gradle file and a CONTRIBUTING.adoc.

The licence is Apache 2.0, with the licence text in LICENSE.txt, and the default branch is named stable rather than main, which tells you the project treats its examples as something that has to keep working.

Fifteen problems mapped to the concepts each one teaches

The overview table is the most useful page in the repository, because it pairs each problem with the solver features it exercises. That pairing is how you should read the collection: pick the use case whose problem you have, and look at the concept column to see what you would learn.

Vehicle routing is paired with Chained Through Time and Shadow Variables, and the problem it solves is finding efficient routes for vehicles to reach visits, taking vehicle capacity and time windows into account, which the readme notes is sometimes called CVRPTW. Employee scheduling is paired with Load Balancing and covers assigning shifts to employees given their availability and shift skill requirements. Maintenance scheduling is paired with the Service Model, TimeGrain, a Shadow Variable and a Variable Listener, and it schedules maintenance jobs to crews over time to reduce both premature and overdue maintenance. Food packaging uses the Service Model, a Mixed Model, Shadow Variables and Pinning, scheduling packaging orders to manufacturing lines to minimise downtime and fulfil orders on time. Order picking uses a Chained Planning Variable with Shadow Variables to generate an optimal picking plan for a set of orders.

The rest of the table is just as varied. School timetabling introduces the Timeslot concept by assigning lessons to timeslots and rooms. Facility location is a Shadow Variable example. Conference scheduling combines the Service Model, ValueRange on Entity, Timeslot and Justifications. Bed allocation uses the Service Model, Allows Unassigned and Pinning. Flight crew scheduling appears with no concepts listed, which is a hint that it is the least documented of the set. Meeting scheduling pairs the Service Model with TimeGrain and Justifications. Task assigning combines the Service Model, Chained Through Time and Allows Unassigned. Project job scheduling uses Shadow Variables, a Variable Listener and a strength comparator, and sports league scheduling uses the Service Model with Consecutive Sequences and Justifications, while tournament scheduling uses Pinning and Load Balancing.

Read as a menu, that table tells you which concepts have worked examples in front of you.

The getting started folder offers five ways in

If the fifteen use cases are overwhelming, the getting-started directory is the smaller entry point, and the readme explains the logic. The website contains several getting started guides, and all of them build the same use case, school timetabling, so that a reader can compare how the same problem looks under different integrations.

The five projects are listed in the documentation with their technology choices. There is a Service project in Java with Maven and Quarkus, a plain library project using the Core in Java with Maven, a Quarkus integration library in Java with Maven, a Quarkus integration library in Kotlin with Maven and Quarkus, and a Spring Boot integration in Java with Maven and Spring.

That list is a useful summary of the whole library's surface. The core library can be used on its own with no framework, the Quarkus integration gives you solver features wired into a Quarkus application, the Kotlin variant shows the same thing from Kotlin, and the Spring Boot integration shows a different application framework. If your stack is not in that list, the use cases still help, because the domain model and the constraints are largely independent of the framework around them.

For a first contact, the recommendation in the readme is to start with the school timetabling example, because it is the one every guide builds.

How to read and run one use case

Each use case folder follows the same shape, and knowing the shape saves time.

There is a README with two things you need. The first is a constraints section, linked from the overview table with a View constraints anchor, which is where the modelling decisions are written down for that problem. The second is a run instruction, linked as Run and named after the Quarkus module, for example quarkus-vehicle-routing, quarkus-employee-scheduling, quarkus-maintenance-scheduling, quarkus-food-packaging, quarkus-order-picking and quarkus-school-timetabling.

The stack for these runnable examples is Java with Maven and Quarkus, and the readme describes each as a Quarkus application. That is the practical path: open the folder for the problem you care about, read the constraints first so that you understand the model before the code, then follow the run instructions for that module.

A detail worth knowing before you start, because it is a property of the examples rather than of the solver. The readme states that Timefold Solver is a library and does not include a user interface, and that a rudimentary user interface is included in the quickstarts in order to illustrate the use cases. So when you run a quickstart you will see a small web interface with a solve button and a chart of the result, and that interface is scaffolding for the demo rather than a product you would keep.

This repository does not give you a shell command for fetching or running the examples, so the route is the one described here: the run instructions live in the README of the use case you have chosen.

Off-the-shelf models, and what the examples deliberately leave out

Alongside several use cases the readme points at prebuilt models hosted on the Timefold application site, and the difference in scope is instructive.

The vehicle routing tip links to a Field Service Routing model that goes beyond basic vehicle routing and supports additional constraints such as priorities, skills and fairness. The employee scheduling tip links to an Employee Shift Scheduling model that supports many additional constraints such as skills, pairing employees and fairness. So the example in this repository is the starting point and the hosted model is the fuller product, and the extra constraints are the practical difference.

What the examples deliberately leave out is the rest of an application. There is no user interface in the library, no persistence, no multi tenant concerns and no scheduling of the solver itself. The note at the top of the overview says the implementations serve as a starting point and or inspiration when creating your own application, which is a fair description of what a quickstart is: correct, minimal and disposable.

For an evaluator, that cuts both ways. You get fifteen worked examples of how the concepts combine, which is genuinely hard to find elsewhere, and you do not get a reference architecture for a production planning system, because the readme never claims to offer one.

Where the quickstarts are the wrong starting point

Four mismatches are worth naming before you build on them.

The first is that the examples are demonstrations, not a framework. Everything you see in a quickstart is written to be read once. If you need a shared planning domain model, a solver configuration that scales, and a way to re-plan when the plan changes, none of that is here, and you will write it.

The second is the stack. The runnable use cases are Java, Maven and Quarkus, and the getting-started set adds Kotlin and Spring Boot. If your planning service is on a different framework or build tool, the integration examples stop helping at the point where you need them.

The third is the version coupling. The examples track the solver's API, and a solver release that changes a concept will change the examples, so a fork of these projects has to be rebased rather than left alone. The repository publishes no GitHub releases, and the default branch is stable, so what you consume is a moving branch rather than a versioned artefact.

The fourth is scale of problem. These are the classic textbook planning problems. A real deployment usually has constraints that are awkward to express, and the honest way to find out how the library handles them is to try, not to expect the example to have solved them already.

Licence, governance and how the examples are kept current

The licence is Apache 2.0, held in LICENSE.txt at the root of the repository, so the example code can be copied into a commercial project and modified without copyleft obligations on your own code. This is not legal advice, and a company with a licence review process should still check the dependencies the examples pull in.

The repository keeps the standard community furniture. There is a CONTRIBUTING.adoc, a .github directory, a .gitignore and .gitattributes, and the logo image used in the readme header. The root project is a Maven build, given the pom.xml, with a settings.gradle file alongside it, and the whole thing sits under the TimefoldAI organisation next to the solver repository.

On maintenance, the last push was on 2026-10-20 and the repository is not archived, so the examples are being kept in step with the solver. The active discussion happens in the GitHub Discussions of the solver repository rather than in the issues here, which is a sensible split: questions about how to model a constraint belong next to the library, not next to the sample code.

The most important thing to notice is what the examples are not. They are not a product, they are not supported, and the readme says so. Read them as a large, well chosen set of worked examples, and pick the ones closest to your problem, and that is what they are good for.

Editorial conclusion

timefold-quickstarts is the right starting point for a Java or Kotlin team evaluating Timefold Solver, because it shows the domain model, the constraints and the solver configuration side by side for fifteen realistic planning problems, and each example is runnable rather than a snippet. It is the wrong place to look for a production ready planning application, since the readme states the implementations serve as a starting point and that the solver is a library with no user interface of its own. Before adopting, run the school timetabling example in the getting-started folder, then read the constraints section of the use case closest to your problem, and check whether the off-the-shelf models linked from the readme already cover the constraints you need.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Project website
4. README
5. TimefoldAI/timefold-quickstarts on GitHub