# xuxueli/xxl-job architecture

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

- Interactive diagram: https://gitdiagram.com/xuxueli/xxl-job
- Repository: https://github.com/xuxueli/xxl-job

## Overview

XXL-JOB is a distributed task-scheduling framework. Users configure and operate jobs through the admin web console; the admin schedules and routes triggers to registered executor instances, which run handlers and report completion for logs, monitoring, and failure alerting. The graph also includes the documented OpenAPI and registration capabilities, plus user/permission management. The README supports the major product flows; source excerpts show selected admin dispatch, executor-log access, and script execution details. Other links are limited to those documented capabilities rather than assumed from module names.

Main entry points: [`xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/openapi/OpenApiController.java`](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/openapi/OpenApiController.java) (Registry API), [`xxl-job-admin/src/main/java/com/xxl/job/admin/business/mapper/XxlJobInfoMapper.java`](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/mapper/XxlJobInfoMapper.java) (Admin Database), [`xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/thread/JobScheduleHelper.java`](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/thread/JobScheduleHelper.java) (Schedule Loop), [`xxl-job-admin/src/main/java/com/xxl/job/admin/business/controller/JobInfoController.java`](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/controller/JobInfoController.java) (Admin Web)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Admin Console"]
  node_web["Admin Web"]
  node_jobservice["Job Service<br/>[XxlJobService.java]"]
  node_groups["Executor Groups<br/>[XxlJobGroup.java]"]
  node_users["User Access"]
end

subgraph group_schedule["Scheduling"]
  node_schedule["Schedule Loop"]
  node_trigger["Trigger Dispatch<br/>[JobTrigger.java]"]
  node_routing["Executor Routing"]
  node_misfire["Misfire Handling"]
  node_registry["Registry API"]
end

subgraph group_execution["Execution"]
  node_executor["Executor Runtime"]
  node_server["Executor Server<br/>[EmbedServer.java]"]
  node_handler["Job Handlers<br/>[IJobHandler.java]"]
  node_script["Script Handler"]
  node_context["Run Context<br/>[XxlJobContext.java]"]
end

subgraph group_observability["Operations"]
  node_database[("Admin Database")]
  node_logs["Run Logs"]
  node_alerts["Failure Alerts<br/>[JobAlarmer.java]"]
  node_reports["Run Reports"]
end

node_operator(("Operator"))
node_email["Email Service"]
node_executor_nodes(("Executor Instances"))

node_operator -->|"configures jobs"| node_web
node_web -->|"manages jobs"| node_jobservice
node_jobservice -.->|"persists job data"| node_database
node_operator -->|"manages access"| node_users
node_schedule -->|"dispatches due jobs"| node_trigger
node_schedule -->|"handles missed runs"| node_misfire
node_trigger -->|"selects executor"| node_routing
node_routing -->|"routes triggers"| node_executor_nodes
node_executor_nodes -->|"registers addresses"| node_registry
node_registry -->|"validates app group"| node_groups
node_executor_nodes -.->|"hosts runtime"| node_server
node_server -.->|"receives job calls"| node_executor
node_executor -->|"runs handler"| node_handler
node_handler -->|"supports script jobs"| node_script
node_script -->|"reads run parameters"| node_context
node_executor_nodes -->|"registers periodically"| node_registry
node_executor_nodes -->|"provides rolling logs"| node_logs
node_logs -->|"reads run records"| node_database
node_executor_nodes -->|"reports failures"| node_alerts
node_alerts -->|"sends notifications"| node_email
node_reports -->|"aggregates run data"| node_database

click node_web "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/controller/JobInfoController.java"
click node_jobservice "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/service/XxlJobService.java"
click node_groups "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/model/XxlJobGroup.java"
click node_users "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/framework/controller/JobUserController.java"
click node_schedule "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/thread/JobScheduleHelper.java"
click node_trigger "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/trigger/JobTrigger.java"
click node_routing "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/route/ExecutorRouteStrategyEnum.java"
click node_misfire "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/misfire/MisfireHandler.java"
click node_registry "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/openapi/OpenApiController.java"
click node_executor "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/executor/XxlJobExecutor.java"
click node_server "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/server/EmbedServer.java"
click node_handler "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/handler/IJobHandler.java"
click node_script "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/handler/impl/ScriptJobHandler.java"
click node_context "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/context/XxlJobContext.java"
click node_database "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/mapper/XxlJobInfoMapper.java"
click node_logs "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/controller/JobLogController.java"
click node_alerts "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/alarm/JobAlarmer.java"
click node_reports "https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/thread/JobLogReportHelper.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_web,node_jobservice,node_groups,node_users toneBlue
class node_schedule,node_trigger,node_routing,node_misfire,node_registry toneAmber
class node_executor,node_server,node_handler,node_script,node_context toneMint
class node_database,node_logs,node_alerts,node_reports toneRose
class node_operator,node_email,node_executor_nodes toneIndigo
```

## Components

### Admin Console

- [Admin Web](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/controller/JobInfoController.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/controller/JobInfoController.java`
- [Job Service](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/service/XxlJobService.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/service/XxlJobService.java`
- [Executor Groups](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/model/XxlJobGroup.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/model/XxlJobGroup.java`
- [User Access](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/framework/controller/JobUserController.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/framework/controller/JobUserController.java`

### Scheduling

- [Schedule Loop](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/thread/JobScheduleHelper.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/thread/JobScheduleHelper.java`
- [Trigger Dispatch](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/trigger/JobTrigger.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/trigger/JobTrigger.java`
- [Executor Routing](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/route/ExecutorRouteStrategyEnum.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/route/ExecutorRouteStrategyEnum.java`
- [Misfire Handling](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/misfire/MisfireHandler.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/misfire/MisfireHandler.java`
- [Registry API](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/openapi/OpenApiController.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/openapi/OpenApiController.java`

### Execution

- [Executor Runtime](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/executor/XxlJobExecutor.java): `xxl-job-core/src/main/java/com/xxl/job/core/executor/XxlJobExecutor.java`
- [Executor Server](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/server/EmbedServer.java): `xxl-job-core/src/main/java/com/xxl/job/core/server/EmbedServer.java`
- [Job Handlers](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/handler/IJobHandler.java): `xxl-job-core/src/main/java/com/xxl/job/core/handler/IJobHandler.java`
- [Script Handler](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/handler/impl/ScriptJobHandler.java): `xxl-job-core/src/main/java/com/xxl/job/core/handler/impl/ScriptJobHandler.java`
- [Run Context](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-core/src/main/java/com/xxl/job/core/context/XxlJobContext.java): `xxl-job-core/src/main/java/com/xxl/job/core/context/XxlJobContext.java`

### Operations

- [Admin Database](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/mapper/XxlJobInfoMapper.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/mapper/XxlJobInfoMapper.java`
- [Run Logs](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/controller/JobLogController.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/controller/JobLogController.java`
- [Failure Alerts](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/alarm/JobAlarmer.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/alarm/JobAlarmer.java`
- [Run Reports](https://github.com/xuxueli/xxl-job/blob/master/xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/thread/JobLogReportHelper.java): `xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/thread/JobLogReportHelper.java`

### Other components

- **Operator**
- **Email Service**
- **Executor Instances**

## Connections

- Operator → Admin Web: configures jobs (evidence: `README.md`)
- Admin Web → Job Service: manages jobs (evidence: `README.md`)
- Job Service → Admin Database: persists job data
- Operator → User Access: manages access (evidence: `README.md`)
- Schedule Loop → Trigger Dispatch: dispatches due jobs (evidence: `README.md`)
- Schedule Loop → Misfire Handling: handles missed runs (evidence: `README.md`)
- Trigger Dispatch → Executor Routing: selects executor (evidence: `README.md`)
- Executor Routing → Executor Instances: routes triggers (evidence: `README.md`)
- Executor Instances → Registry API: registers addresses (evidence: `README.md`)
- Registry API → Executor Groups: validates app group (evidence: `xxl-job-admin/src/main/java/com/xxl/job/admin/business/scheduler/openapi/OpenApiController.java`)
- Executor Instances → Executor Server: hosts runtime
- Executor Server → Executor Runtime: receives job calls
- Executor Runtime → Job Handlers: runs handler (evidence: `README.md`)
- Job Handlers → Script Handler: supports script jobs (evidence: `README.md`)
- Script Handler → Run Context: reads run parameters (evidence: `xxl-job-core/src/main/java/com/xxl/job/core/handler/impl/ScriptJobHandler.java`)
- Executor Instances → Registry API: registers periodically (evidence: `README.md`)
- Executor Instances → Run Logs: provides rolling logs (evidence: `README.md`)
- Run Logs → Admin Database: reads run records (evidence: `xxl-job-admin/src/main/java/com/xxl/job/admin/business/controller/JobLogController.java`)
- Executor Instances → Failure Alerts: reports failures (evidence: `README.md`)
- Failure Alerts → Email Service: sends notifications (evidence: `README.md`)
- Run Reports → Admin Database: aggregates run data (evidence: `README.md`)
