# soullose/task-scheduler-job architecture

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

- Interactive diagram: https://gitdiagram.com/soullose/task-scheduler-job
- Repository: https://github.com/soullose/task-scheduler-job

## Overview

This Spring-based in-process task scheduler loads and validates task definitions, registers enabled cron or fixed-interval triggers, and runs task handlers asynchronously with concurrency control, timeout, retries, and execution records. Its main path is configuration source → scheduler and registry → execution wrapper → handler; startup-only tasks and manual triggers also enter the executor. The REST admin path persists task edits and reloads the scheduler. Persistence and monitoring components are included; unsampled wiring is omitted where the tree and README do not establish it.

Main entry points: [`src/main/java/com/w3/taskscheduler/core/scheduler/DefaultSchedulerService.java`](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/scheduler/DefaultSchedulerService.java) (Scheduler service), [`src/main/java/com/w3/taskscheduler/admin/TaskAdminService.java`](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/admin/TaskAdminService.java) (Admin service), [`src/main/java/com/w3/taskscheduler/core/exec/TaskExecutorWrapper.java`](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/exec/TaskExecutorWrapper.java) (Execution wrapper), [`src/main/java/com/w3/taskscheduler/core/config/TaskConfigSource.java`](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/config/TaskConfigSource.java) (Task source)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Task administration"]
  node_admin_api["Admin REST API"]
  node_admin_service["Admin service"]
end

subgraph group_config["Task configuration"]
  node_config_source["Task source"]
  node_db_loader["Database loader"]
  node_yaml_loader["YAML loader"]
end

subgraph group_runtime["Scheduling runtime"]
  node_scheduler_service["Scheduler service"]
  node_registry["Task registry<br/>[TaskRegistry.java]"]
  node_scheduled_handler["Scheduled task handler"]
  node_lifecycle["Scheduler lifecycle"]
end

subgraph group_execution["Execution and handlers"]
  node_executor_wrapper["Execution wrapper"]
  node_task_invoker["Task invoker<br/>[TaskInvoker.java]"]
  node_task_handlers["Task handlers"]
  node_cleanup_handler["History cleanup"]
end

subgraph group_state["Persistence and monitoring"]
  node_scheduler_job_store[("Task definitions DB")]
  node_event_writer["Execution event writer"]
  node_history_store["Execution history store"]
  node_execution_repo["Execution repository"]
  node_execution_db[("Execution records DB")]
  node_metrics["Scheduler metrics"]
end

node_admin_user(("Admin client"))
node_yaml_config["YAML task definitions"]

node_admin_user -->|"manages tasks"| node_admin_api
node_admin_api -->|"routes requests"| node_admin_service
node_admin_service -->|"reads and writes"| node_scheduler_job_store
node_admin_service -->|"validates rows"| node_db_loader
node_admin_service -->|"reloads or triggers"| node_scheduler_service
node_scheduler_service -->|"loads definitions"| node_config_source
node_config_source -->|"tries database"| node_db_loader
node_config_source -->|"uses fallback"| node_yaml_loader
node_db_loader -->|"reads definitions"| node_scheduler_job_store
node_yaml_loader -->|"reads definitions"| node_yaml_config
node_scheduler_service -->|"registers and diffs"| node_registry
node_registry -->|"dispatches triggers"| node_scheduled_handler
node_scheduled_handler -->|"submits executions"| node_executor_wrapper
node_scheduler_service -->|"submits startup or manual runs"| node_executor_wrapper
node_executor_wrapper -->|"invokes handler"| node_task_invoker
node_task_invoker -->|"calls task code"| node_task_handlers
node_task_invoker -->|"calls task code"| node_cleanup_handler
node_executor_wrapper -->|"records outcomes"| node_event_writer
node_event_writer -->|"writes events"| node_history_store
node_history_store -->|"persists records"| node_execution_repo
node_execution_repo -->|"reads and writes"| node_execution_db
node_cleanup_handler -->|"deletes old successes"| node_execution_repo
node_lifecycle -->|"starts and stops"| node_scheduler_service

click node_admin_api "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/admin/TaskAdminController.java"
click node_admin_service "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/admin/TaskAdminService.java"
click node_config_source "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/config/TaskConfigSource.java"
click node_db_loader "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/config/DatabaseTaskConfigLoader.java"
click node_yaml_loader "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/config/TaskConfigLoader.java"
click node_scheduler_job_store "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/persistence/repository/SchedulerJobRepository.java"
click node_scheduler_service "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/scheduler/DefaultSchedulerService.java"
click node_registry "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/scheduler/TaskRegistry.java"
click node_scheduled_handler "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/scheduler/ScheduledTaskHandler.java"
click node_executor_wrapper "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/exec/TaskExecutorWrapper.java"
click node_task_invoker "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/invoke/TaskInvoker.java"
click node_task_handlers "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/jobs/handler/DataSyncHandler.java"
click node_cleanup_handler "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/jobs/handler/JobExecutionCleanupHandler.java"
click node_event_writer "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/history/JobExecutionEventWriter.java"
click node_history_store "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/history/ExecutionHistoryStore.java"
click node_execution_repo "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/persistence/repository/ExecutionRecordRepository.java"
click node_execution_db "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/persistence/entity/JobExecutionPO.java"
click node_metrics "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/monitor/SchedulerMetrics.java"
click node_lifecycle "https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/scheduler/SchedulerLifecycle.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_admin_api,node_admin_service,node_admin_user toneBlue
class node_config_source,node_db_loader,node_yaml_loader toneAmber
class node_scheduler_service,node_registry,node_scheduled_handler,node_lifecycle toneMint
class node_executor_wrapper,node_task_invoker,node_task_handlers,node_cleanup_handler,node_yaml_config toneRose
class node_scheduler_job_store,node_event_writer,node_history_store,node_execution_repo,node_execution_db,node_metrics toneIndigo
```

## Components

### Task administration

- [Admin REST API](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/admin/TaskAdminController.java): `src/main/java/com/w3/taskscheduler/admin/TaskAdminController.java`
- [Admin service](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/admin/TaskAdminService.java): `src/main/java/com/w3/taskscheduler/admin/TaskAdminService.java`

### Task configuration

- [Task source](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/config/TaskConfigSource.java): `src/main/java/com/w3/taskscheduler/core/config/TaskConfigSource.java`
- [Database loader](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/config/DatabaseTaskConfigLoader.java): `src/main/java/com/w3/taskscheduler/core/config/DatabaseTaskConfigLoader.java`
- [YAML loader](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/config/TaskConfigLoader.java): `src/main/java/com/w3/taskscheduler/core/config/TaskConfigLoader.java`

### Scheduling runtime

- [Scheduler service](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/scheduler/DefaultSchedulerService.java): `src/main/java/com/w3/taskscheduler/core/scheduler/DefaultSchedulerService.java`
- [Task registry](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/scheduler/TaskRegistry.java): `src/main/java/com/w3/taskscheduler/core/scheduler/TaskRegistry.java`
- [Scheduled task handler](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/scheduler/ScheduledTaskHandler.java): `src/main/java/com/w3/taskscheduler/core/scheduler/ScheduledTaskHandler.java`
- [Scheduler lifecycle](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/scheduler/SchedulerLifecycle.java): `src/main/java/com/w3/taskscheduler/core/scheduler/SchedulerLifecycle.java`

### Execution and handlers

- [Execution wrapper](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/exec/TaskExecutorWrapper.java): `src/main/java/com/w3/taskscheduler/core/exec/TaskExecutorWrapper.java`
- [Task invoker](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/invoke/TaskInvoker.java): `src/main/java/com/w3/taskscheduler/core/invoke/TaskInvoker.java`
- [Task handlers](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/jobs/handler/DataSyncHandler.java): `src/main/java/com/w3/taskscheduler/jobs/handler/DataSyncHandler.java`
- [History cleanup](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/jobs/handler/JobExecutionCleanupHandler.java): `src/main/java/com/w3/taskscheduler/jobs/handler/JobExecutionCleanupHandler.java`

### Persistence and monitoring

- [Task definitions DB](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/persistence/repository/SchedulerJobRepository.java): `src/main/java/com/w3/taskscheduler/core/persistence/repository/SchedulerJobRepository.java`
- [Execution event writer](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/history/JobExecutionEventWriter.java): `src/main/java/com/w3/taskscheduler/core/history/JobExecutionEventWriter.java`
- [Execution history store](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/history/ExecutionHistoryStore.java): `src/main/java/com/w3/taskscheduler/core/history/ExecutionHistoryStore.java`
- [Execution repository](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/persistence/repository/ExecutionRecordRepository.java): `src/main/java/com/w3/taskscheduler/core/persistence/repository/ExecutionRecordRepository.java`
- [Execution records DB](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/core/persistence/entity/JobExecutionPO.java): `src/main/java/com/w3/taskscheduler/core/persistence/entity/JobExecutionPO.java`
- [Scheduler metrics](https://github.com/soullose/task-scheduler-job/blob/master/src/main/java/com/w3/taskscheduler/monitor/SchedulerMetrics.java): `src/main/java/com/w3/taskscheduler/monitor/SchedulerMetrics.java`

### Other components

- **Admin client**
- **YAML task definitions**

## Connections

- Admin client → Admin REST API: manages tasks
- Admin REST API → Admin service: routes requests
- Admin service → Task definitions DB: reads and writes
- Admin service → Database loader: validates rows
- Admin service → Scheduler service: reloads or triggers
- Scheduler service → Task source: loads definitions
- Task source → Database loader: tries database
- Task source → YAML loader: uses fallback
- Database loader → Task definitions DB: reads definitions
- YAML loader → YAML task definitions: reads definitions
- Scheduler service → Task registry: registers and diffs
- Task registry → Scheduled task handler: dispatches triggers
- Scheduled task handler → Execution wrapper: submits executions
- Scheduler service → Execution wrapper: submits startup or manual runs
- Execution wrapper → Task invoker: invokes handler
- Task invoker → Task handlers: calls task code
- Task invoker → History cleanup: calls task code
- Execution wrapper → Execution event writer: records outcomes
- Execution event writer → Execution history store: writes events
- Execution history store → Execution repository: persists records
- Execution repository → Execution records DB: reads and writes
- History cleanup → Execution repository: deletes old successes
- Scheduler lifecycle → Scheduler service: starts and stops