Timefold Solver: a Java and Kotlin constraint solver for routing and rostering

What Timefold Solver solves, and for whom

Timefold Solver is an AI constraint solver for Java and Kotlin. The README lists the problem families it targets: the Vehicle Routing Problem, Employee Rostering, Maintenance Scheduling, Task Assignment, School Timetabling, Cloud Optimization, Conference Scheduling and Job Shop Scheduling. The common thread is combinatorial planning, where a set of resources has to be assigned to a set of tasks under constraints, and the number of feasible arrangements is far too large to enumerate.

The audience is JVM developers who already own the domain model. The README describes the project as "Planning optimization made easy", but the work it removes is the search, not the modelling. You still write the classes that represent vehicles, visits, shifts and employees, and you still write the constraints. What you do not write is a branch-and-bound or local search engine.

The project was forked on 20 April 2023 from OptaPlanner, which was entirely Apache-2.0 licensed, and is developed by the original OptaPlanner team. That lineage matters for two reasons. Existing OptaPlanner users will recognise the annotation-driven model, and the fork means the community code sits under a permissive licence while a separate commercial edition exists beside it.

How the solver works: score, constraints and search

The architecture visible in the repository is a solver core with integration layers on top. The top-level entries include core/, persistence/, quarkus-integration/, spring-integration/, service/ and tools/. The core holds the solving engine, persistence handles loading and storing problem data, and the two integration modules wire the solver into Quarkus and Spring Boot applications.

The solving model is score-based. You declare planning entities and planning variables, and you express your business rules as constraints that contribute to a single score. The solver then searches for a solution with the best score it can reach in the time you allow. This is the same mechanism OptaPlanner used, and it is why the constraint set, not the algorithm, is where most of your effort goes.

The README does not document the internal search algorithms, the move types, or the termination configuration. For those details it points to the documentation site and the Quickstarts repository. That split is deliberate: the README is a signpost, and the docs are the manual. If you are evaluating the project, treat the README as an index and budget time for the documentation before you judge whether the constraint model fits your problem.

Installing Timefold Solver and running a first model

The README gives two paths. The recommended one is to read the Getting Started guide and clone the Quickstarts repository, which is where the working examples live. The other is to build the solver itself from source, which you only need if you intend to work on the solver rather than with it.

Building from source requires JDK 21 or newer and Maven 3.9.11 or newer. The README suggests Sdkman for both:

$ sdk install java
$ sdk install maven

Then clone and build. The -Dquickly flag is what the README uses to keep the build short:

$ git clone https://github.com/TimefoldAI/timefold-solver.git
$ cd timefold-solver
$ ./mvnw clean install -Dquickly

For application code, the dependency is published on Maven Central under the group ai.timefold.solver, and the README links a bill of materials artifact, timefold-solver-bom. The README does not show a pom.xml snippet, so take the exact coordinates and version from the Quickstarts rather than guessing them. The README also states the JVM support requirement as Java 21+.

A first real use looks like this: pick the quickstart closest to your problem (vehicle routing, employee rostering, and so on), replace its domain classes with yours, then rewrite its constraint definitions to match your rules. The solver configuration, the termination settings and the score calculation are all in that project, which is why the README sends you there instead of printing a minimal example.

The Community and Enterprise split is the first thing to check

The README is explicit that there are two editions. The Community Edition is this repository and is licensed under Apache-2.0. The Enterprise Edition is a non-open-source commercial offering and requires a Timefold licence to run. The README links to a licence comparison page rather than listing the differences itself.

That is the most consequential limitation for an adopter, and it is a limitation of the documentation as much as of the product. The README does not enumerate which capabilities are community and which are enterprise. A team that prototypes against the community artifacts and later discovers a needed feature is enterprise-only has to renegotiate both the licence and the architecture. Check the comparison page before the prototype, not after.

The licence position on the community code is otherwise clean. Timefold Solver is a derivative work of OptaPlanner and OptaPy, including copyrights of Red Hat Inc., affiliates and contributors, all originally Apache-2.0. Every source file has been modified. For most adopters Apache-2.0 means the usual permissive terms, but this is a description of the repository, not legal advice, and any organisation with a licence review process should run it.

Where Timefold Solver is the wrong tool

The clearest boundary is language. The README describes Timefold Solver as a solver for Java and Kotlin. If your service is Python, this repository is not the answer, even though related searches about Python appear often. The documentation covers JVM integration only: Maven artifacts, a Quarkus integration and a Spring integration.

A second boundary is problem shape. The solver is built for planning problems expressed as entities, variables and constraints. If your problem is a straightforward assignment that a greedy pass or a database query can settle, adding a solver adds a domain model, a constraint set, a termination policy and a tuning exercise. The score-based approach pays off when the constraint interactions are what make the problem hard, not when there is one obvious best answer.

A third is operational. The README does not document rollback, persistence of in-progress solving, or how to run the solver as a separate service, despite a service/ directory being present. If you need a long-running planning service with recovery semantics, treat that as unverified and confirm it in the documentation before you design around it.

What you would use instead, and how it differs

The natural alternative is OptaPlanner, the project Timefold Solver was forked from on 20 April 2023. The two share a lineage and an annotation-driven, score-based model, so the difference is not conceptual. It is governance and release cadence: Timefold Solver is developed by the original OptaPlanner team and publishes its own release stream, with v2.6.0 on 2026-09-01, v2.5.0 on 2026-08-12 and a v1.34.0 maintenance release on 2026-08-03. An OptaPlanner codebase is not a drop-in match for Timefold Solver, but the modelling vocabulary transfers.

If your problem is a pure routing problem with standard constraints, a dedicated routing library may be less machinery than a general constraint solver. The trade-off is expressiveness: a general solver lets you add rostering rules, shift preferences and equipment constraints to the same model, while a routing-specific tool expects you to stay inside its problem definition. Timefold Solver's own topic list, which spans vehicle routing, employee scheduling and maintenance scheduling, is the argument for the general approach.

For teams already on Quarkus or Spring Boot, the integration modules in this repository are the practical reason to stay. The solver is a library you embed, not a service you call, and the integration layers are where that embedding is already written.

Maintenance, releases and upgrade cost

The repository is not archived, and the last push was on 2026-09-15. Releases are frequent: v2.6.0 on 2026-09-01, v2.5.0 on 2026-08-12, and a v1.34.0 maintenance release on 2026-08-03. The presence of both a 2.x line and a maintained 1.x line is worth noting, because it means two upgrade paths exist and you should confirm which one your project is on before planning a migration.

The README does not document a deprecation policy, a support window, or what changes between minor versions. It also does not describe rollback. For a library that sits inside your application, that means upgrade cost is mostly the cost of re-validating your constraints and your score configuration after a version bump, which is work only your test suite can measure.

On licensing, the community code is Apache-2.0 and the Enterprise Edition requires a Timefold licence to run. The README points to a comparison page for choosing between them. Nothing here suggests the community licence is changing, but the edition boundary is the thing to verify first, because it determines whether an upgrade is a build change or a commercial decision.

Editorial conclusion

Adopt Timefold Solver if your planning problem is expressed as Java or Kotlin domain classes and you want an Apache-2.0 solver you can embed in a Spring Boot or Quarkus service. Do not adopt it if you need a Python solver, since the README points to Java and Kotlin only, or if you need features reserved for the Enterprise Edition. Before committing, verify which edition covers the constraints you need, that your build runs on JDK 21 or newer, and that the quickstarts model matches your problem shape.

Frequently asked questions

Official sources

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