# kagkarlsson/db-scheduler architecture

> Architecture diagram of the GitHub repository kagkarlsson/db-scheduler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kagkarlsson/db-scheduler
- Repository: https://github.com/kagkarlsson/db-scheduler

## Overview

db-scheduler is an embeddable, database-backed Java task scheduler designed for clustered execution. Applications define task types and schedules, build and start a Scheduler, then submit or inspect instances through its client API. The runtime polls and claims due work, invokes task handlers, and records completion, retry, or recurrence state in a relational table. Spring Boot starters and optional health/metrics support are separate integration branches. Several runtime internals are unsampled, so unverified execution links are marked dashed rather than asserted.

Main entry points: [`db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Scheduler.java`](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Scheduler.java) (Scheduler), [`db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Executor.java`](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Executor.java) (Task execution), [`db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskRepository.java`](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskRepository.java) (Repository contract), [`db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java`](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java) (Scheduling client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_definition["Tasks and schedules"]
  node_task_api["Task definitions<br/>[Task.java]"]
  node_task_builders["Task builders<br/>[Tasks.java]"]
  node_schedules["Schedule types<br/>[Schedule.java]"]
  node_instances["Task instances<br/>[TaskInstance.java]"]
  node_schedulable["Scheduled instances"]
end

subgraph group_runtime["Scheduler runtime"]
  node_scheduler["Scheduler<br/>[Scheduler.java]"]
  node_client["Scheduling client"]
  node_polling["Due polling"]
  node_executor["Task execution<br/>[Executor.java]"]
  node_completion["Completion handling"]
  node_failure["Failure handling"]
  node_task_resolver["Task resolution<br/>[TaskResolver.java]"]
end

subgraph group_storage["Persistence"]
  node_repository_api["Repository contract"]
  node_jdbc_repo["JDBC repository"]
  node_jdbc_tx["JDBC transactions"]
  node_database[("Relational database")]
end

subgraph group_integration["Framework integrations"]
  node_spring["Spring Boot starter"]
  node_health["Health indicator"]
  node_metrics["Metrics support"]
end

node_app(("Application"))

node_app -->|"defines tasks"| node_task_builders
node_task_builders -->|"builds"| node_task_api
node_task_api -->|"uses schedules"| node_schedules
node_app -->|"builds and starts"| node_scheduler
node_scheduler -->|"runs polling"| node_polling
node_polling -.->|"dispatches due work"| node_executor
node_executor -.->|"resolves task"| node_task_resolver
node_executor -.->|"handles result"| node_completion
node_executor -.->|"handles failure"| node_failure
node_completion -.->|"reschedules"| node_repository_api
node_failure -->|"retries"| node_repository_api
node_app -->|"submits instances"| node_client
node_client -->|"reads and writes"| node_repository_api
node_client -->|"accepts instances"| node_instances
node_instances -->|"forms scheduled work"| node_schedulable
node_repository_api -.->|"implemented by"| node_jdbc_repo
node_jdbc_repo -->|"persists executions"| node_database
node_jdbc_repo -.->|"uses transactions"| node_jdbc_tx
node_spring -.->|"starts scheduler"| node_scheduler
node_health -->|"checks state"| node_scheduler
node_metrics -.->|"observes runtime"| node_scheduler

click node_task_api "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/Task.java"
click node_task_builders "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/helper/Tasks.java"
click node_schedules "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/schedule/Schedule.java"
click node_instances "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/TaskInstance.java"
click node_schedulable "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/SchedulableInstance.java"
click node_scheduler "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Scheduler.java"
click node_client "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java"
click node_polling "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/FetchCandidates.java"
click node_executor "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Executor.java"
click node_completion "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/CompletionHandler.java"
click node_failure "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/FailureHandler.java"
click node_task_resolver "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskResolver.java"
click node_repository_api "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskRepository.java"
click node_jdbc_repo "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/jdbc/JdbcTaskRepository.java"
click node_jdbc_tx "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/jdbc/TransactionManager.java"
click node_spring "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler-spring-boot-starter-parent/db-scheduler-spring-common/src/main/java/com/github/kagkarlsson/scheduler/boot/config/DbSchedulerStarter.java"
click node_health "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler-spring-boot-starter-parent/db-scheduler-spring-boot3-starter/src/main/java/com/github/kagkarlsson/scheduler/boot/actuator/DbSchedulerHealthIndicator.java"
click node_metrics "https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/stats/MicrometerStatsRegistry.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_task_api,node_task_builders,node_schedules,node_instances,node_schedulable toneBlue
class node_scheduler,node_client,node_polling,node_executor,node_completion,node_failure,node_task_resolver toneAmber
class node_repository_api,node_jdbc_repo,node_jdbc_tx,node_database toneMint
class node_spring,node_health,node_metrics toneRose
class node_app toneIndigo
```

## Components

### Tasks and schedules

- [Task definitions](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/Task.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/Task.java`
- [Task builders](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/helper/Tasks.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/helper/Tasks.java`
- [Schedule types](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/schedule/Schedule.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/schedule/Schedule.java`
- [Task instances](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/TaskInstance.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/TaskInstance.java`
- [Scheduled instances](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/SchedulableInstance.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/SchedulableInstance.java`

### Scheduler runtime

- [Scheduler](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Scheduler.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Scheduler.java`
- [Scheduling client](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java`
- [Due polling](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/FetchCandidates.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/FetchCandidates.java`
- [Task execution](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Executor.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Executor.java`
- [Completion handling](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/CompletionHandler.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/CompletionHandler.java`
- [Failure handling](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/FailureHandler.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/FailureHandler.java`
- [Task resolution](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskResolver.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskResolver.java`

### Persistence

- [Repository contract](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskRepository.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/TaskRepository.java`
- [JDBC repository](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/jdbc/JdbcTaskRepository.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/jdbc/JdbcTaskRepository.java`
- [JDBC transactions](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/jdbc/TransactionManager.java): `db-scheduler/src/main/java/com/github/kagkarlsson/jdbc/TransactionManager.java`
- **Relational database**

### Framework integrations

- [Spring Boot starter](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler-spring-boot-starter-parent/db-scheduler-spring-common/src/main/java/com/github/kagkarlsson/scheduler/boot/config/DbSchedulerStarter.java): `db-scheduler-spring-boot-starter-parent/db-scheduler-spring-common/src/main/java/com/github/kagkarlsson/scheduler/boot/config/DbSchedulerStarter.java`
- [Health indicator](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler-spring-boot-starter-parent/db-scheduler-spring-boot3-starter/src/main/java/com/github/kagkarlsson/scheduler/boot/actuator/DbSchedulerHealthIndicator.java): `db-scheduler-spring-boot-starter-parent/db-scheduler-spring-boot3-starter/src/main/java/com/github/kagkarlsson/scheduler/boot/actuator/DbSchedulerHealthIndicator.java`
- [Metrics support](https://github.com/kagkarlsson/db-scheduler/blob/master/db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/stats/MicrometerStatsRegistry.java): `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/stats/MicrometerStatsRegistry.java`

### Other components

- **Application**

## Connections

- Application → Task builders: defines tasks (evidence: `README.md`)
- Task builders → Task definitions: builds (evidence: `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/helper/Tasks.java`)
- Task definitions → Schedule types: uses schedules (evidence: `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/helper/Tasks.java`)
- Application → Scheduler: builds and starts (evidence: `README.md`)
- Scheduler → Due polling: runs polling (evidence: `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/Scheduler.java`)
- Due polling → Task execution: dispatches due work
- Task execution → Task resolution: resolves task
- Task execution → Completion handling: handles result
- Task execution → Failure handling: handles failure
- Completion handling → Repository contract: reschedules
- Failure handling → Repository contract: retries (evidence: `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/FailureHandler.java`)
- Application → Scheduling client: submits instances (evidence: `README.md`)
- Scheduling client → Repository contract: reads and writes (evidence: `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java`)
- Scheduling client → Task instances: accepts instances (evidence: `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/SchedulerClient.java`)
- Task instances → Scheduled instances: forms scheduled work (evidence: `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/task/TaskInstance.java`)
- Repository contract → JDBC repository: implemented by (evidence: `db-scheduler/src/main/java/com/github/kagkarlsson/scheduler/jdbc/JdbcTaskRepository.java`)
- JDBC repository → Relational database: persists executions (evidence: `README.md`)
- JDBC repository → JDBC transactions: uses transactions
- Spring Boot starter → Scheduler: starts scheduler
- Health indicator → Scheduler: checks state (evidence: `db-scheduler-spring-boot-starter-parent/db-scheduler-spring-boot3-starter/src/main/java/com/github/kagkarlsson/scheduler/boot/actuator/DbSchedulerHealthIndicator.java`)
- Metrics support → Scheduler: observes runtime