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 oppinionated 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.

The service approach takes an opinionated stance: it builds a fully independent optimization service on top of Quarkus. The service has a single responsibility, running optimization, and exposes it over a well-defined API. You do not need to manage solver lifecycle, thread pools, or result handling yourself.

This approach is the right choice when you want to:

  • Decouple optimization from the rest of your application

  • Scale the optimization service independently

  • Adopt a clean service boundary without boilerplate

To get started with the service approach, see Getting started: building a service.