Overview

This documentation covers our Open Source solver to build a model from scratch. We also provide off-the-shelf models to solve common planning problems. These can be found here.

Timefold Solver can be used in two ways. Pick the approach that best fits your architecture:

Embed as a library

Add the solver as a dependency and wire it into your application however you like. Use Spring Boot, Quarkus…​ or no framework at all.

Run as a service (Preview)

Deploy a fully isolated optimization service. This opinionated approach reduces the amount of boilerplate code needed to get to a running application.
Table 1. Comparison
Embed as a library Run as a service

Best for

Embedding the solver into an existing application

Running optimization as a standalone, isolated service

Ease of use

Requires manual wiring: you manage configuration, lifecycle, and integration

Minimal setup: the framework handles REST endpoints and lifecycle for you

Integration

You control how the solver is wired into your application. Integrations for Spring Boot and Quarkus available.

Opinionated, ready-to-run service built on Quarkus

Flexibility

Use any framework or no framework at all

Constrained by design, the service only runs optimization

Status

Stable

Preview

Embed as a library

The library approach gives you the solver core as a dependency. You integrate it into your application however you see fit. There are no constraints on your application framework or architecture.

The following getting started guides demonstrate the library approach:

  • Hello World

    • The simplest starting point. Build a plain Java or Kotlin application with no additional framework.

  • Quarkus

    • Build a REST application with Java or Kotlin on top of Quarkus, a popular Java platform that supports native compilation.

  • Spring Boot

    • Build a REST application with Java or Kotlin on top of Spring Boot, a popular Java platform that supports native compilation.

All three guides optimize a school timetable for students and teachers:

schoolTimetablingInputOutput
The timefold-quickstarts repository contains the source code for all these guides.

For additional use cases using the library approach, take a look at the timefold-quickstarts GitHub repository.

Run as a service (Preview)

The service approach is currently in preview. It is the recommended path going forward, but the API may still change before it reaches general availability.

This is the approach we recommend for integrating Timefold Solver into a larger system, and it is the approach we use ourselves when building optimization models at Timefold.

The service has a single responsibility: running optimization. It receives a dataset, solves it, and returns the result over a well-defined REST API. That is all it does.

Why no database? Deliberately. The service does not store datasets, manage user state, or own any persistence layer. Your application already has a database; the service does not need one. This makes the service stateless, trivially scalable, and completely free of operational concerns like schema migrations or data ownership. When optimization is one step in a larger workflow, a stateless service with a clean API slots into any architecture without friction.

Why opinionated? An opinionated framework means less boilerplate, fewer ways to get it wrong, and a consistent shape that we all can reason about together. The library approach gives you full control; this approach gives you a proven path.

To get started, see Getting started: building a service.