overview.adoc

Overview

Tip	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:

[cubes] 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.

[server] 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 that is easier to integrate, orchestrate & scale
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 minimal 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:

Important

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)

Important

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.