Cadrix

Distributed job scheduling and processing framework for Java 25 / Spring Boot 4.1.

Cadrix persists Jobs and their Executions in a shared store (JDBC or MongoDB), lets any number of nodes poll and claim due work under a lease-based mutex, and recovers automatically when a node dies or a lease expires — no external coordinator required.

Overview

Modules

Module	Purpose
cadrix-core	Domain model and scheduling engine: Job, Trigger, Execution, Calendar, Queue, retry/misfire policies. Storage-agnostic.
cadrix-cron	Standalone cron expression parser used by CronTrigger.
cadrix-jdbc	StorageProvider implementation on portable JDBC — PostgreSQL, SQL Server, MySQL, MariaDB, Oracle, SQLite, H2 and HSQLDB, each run against the full conformance suite.
cadrix-mongodb	StorageProvider implementation on MongoDB.
cadrix-spring-boot-starter	Auto-configuration: engine wiring, REST API (/cadrix-api), and the cadrix-ui dashboard (/cadrix-ui).
cadrix-ui	React/TypeScript/Tailwind dashboard — Jobs, Executions, Queues, Calendars, Workers — served by the starter.
cadrix-bom	Bill of materials for consuming Cadrix's modules with aligned versions.
cadrix-demo	Runnable reference app showing the API surface end to end. See cadrix-demo/README.md.

Status

Early stage — API and storage schema are not yet stable between releases.

Getting started

Requirements: Java 25, Maven (wrapper included).

./mvnw clean install

Add the starter and a storage backend to your Spring Boot application:

<dependency>
    <groupId>io.github.robsonkades</groupId>
    <artifactId>cadrix-spring-boot-starter</artifactId>
</dependency>
<dependency>
    <groupId>io.github.robsonkades</groupId>
    <artifactId>cadrix-jdbc</artifactId>
    <!-- or cadrix-mongodb -->
</dependency>

Database schema (JDBC backend)

Cadrix does not run DDL against your database — schema migration belongs to the application. The DDL for every supported dialect ships inside the cadrix-jdbc jar, under /io/github/robsonkades/cadrix/jdbc/schema/schema-<dialect>.sql (schema-postgresql.sql, schema-sqlserver.sql, schema-mysql.sql, schema-mariadb.sql, schema-oracle.sql, schema-sqlite.sql, schema-h2.sql, schema-hsqldb.sql). Copy the one for your database into your migration tool (Flyway, Liquibase, spring.sql.init, ...) — these are the exact files the conformance suite runs against each dialect, so they are the schema contract, not an example. The MongoDB backend needs no step here: it creates its own indexes at startup.

For a full example — Handlers, every scheduling API, load testing — run cadrix-demo:

docker compose up -d postgres   # shared dev Postgres, see repo root docker-compose.yml
./mvnw -pl cadrix-demo spring-boot:run

Usage

Define a Handler — the unit of work a Job runs:

@Component
public class WelcomeEmailHandler implements JobHandler<WelcomeEmailHandler.Params> {

    public record Params(String email) {}

    @Override
    public void execute(Params parameters, ExecutionContext context) {
        // send the email — must be idempotent, Executions are at-least-once
    }
}

Inject Scheduler and schedule it:

@Component
public class SignupListener {

    private final Scheduler scheduler;

    public SignupListener(Scheduler scheduler) {
        this.scheduler = scheduler;
    }

    void onSignup(String email) {
        // one-shot Job, runs as soon as a node claims it
        scheduler.enqueue(WelcomeEmailHandler.class, new WelcomeEmailHandler.Params(email));
    }
}

Scheduler also has scheduleAt, scheduleCron, scheduleFixedRate, scheduleFixedDelay, and recurring (upserts by Job Key — safe to call on every application boot) for recurring work.

Try it with the demo

cadrix-demo wires the starter to Postgres and exposes every scheduling method over REST, so you can see it running without writing any code:

docker compose up -d postgres   # shared dev Postgres, see repo root docker-compose.yml
./mvnw -pl cadrix-demo spring-boot:run

curl -X POST http://localhost:8080/jobs/enqueue \
  -H 'Content-Type: application/json' \
  -d '{"handler":"welcome-email","email":"alice@example.com"}'

curl http://localhost:8080/jobs/{jobId}

See cadrix-demo/README.md for the full API (cron, fixed rate/delay, queues, retry/misfire policies, load testing) and the dashboard at /cadrix-ui.

Contributing

See CONTRIBUTING.md. Please also read the Code of Conduct.

Security

The dashboard and its REST API ship without authentication of their own and always run on your application's own server, under cadrix.api.path (default /cadrix-api) and /cadrix-ui — so your application's security configuration is what protects them. The API includes command endpoints (pause/resume/cancel jobs, enqueue, cancel/retry executions): if your application is reachable by anyone who shouldn't operate the scheduler, protect those prefixes, e.g. with Spring Security:

http.authorizeHttpRequests(auth -> auth
        .requestMatchers("/cadrix-api/**", "/cadrix-ui/**").hasRole("OPS")
        ...);

Or turn them off entirely with cadrix.api.enabled: false / cadrix.frontend.enabled: false.

See SECURITY.md for how to report a vulnerability.

License

Apache License 2.0 — see LICENSE.