# patmesh/kairos-scheduler architecture

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

- Interactive diagram: https://gitdiagram.com/patmesh/kairos-scheduler
- Repository: https://github.com/patmesh/kairos-scheduler

## Overview

Kairos is a distributed task scheduler: users authenticate, create jobs, and inspect schedules and execution history in the frontend; jobs are persisted and synchronized to scheduler records, which are dispatched through Kafka for callback execution and audit. Scheduler internals add Raft-based range ownership and polling/recovery, while execution handles deduplication. Internal service connections are included where excerpts or README descriptions support them; unsampled subsystem details are represented at their source-directory paths.

Main entry points: [`job-service/src/main/java/io/kairos/jobservice/service/JobService.java`](https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/service/JobService.java) (Job lifecycle), [`execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java`](https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java) (Task execution service), [`job-service/src/main/java/io/kairos/jobservice/controller/JobController.java`](https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/controller/JobController.java) (Job REST API), [`scheduler-service/src/main/java/io/kairos/scheduler/service/TaskDispatchService.java`](https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/service/TaskDispatchService.java) (Task dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_dashboard["Dashboard and schedules<br/>[page.tsx]"]
  node_frontend_api["Frontend API client<br/>[api.ts]"]
end

subgraph group_auth["Authentication"]
  node_auth_api["Auth endpoints"]
  node_auth_service["Auth service<br/>[AuthService.java]"]
  node_refresh_tokens["Refresh tokens"]
  node_user_store[("User repository")]
end

subgraph group_jobs["Job management"]
  node_job_api["Job REST API<br/>[JobController.java]"]
  node_job_service["Job lifecycle<br/>[JobService.java]"]
  node_job_store[("Job records<br/>[JobRepository.java]")]
  node_schedule_store[("Schedule records")]
  node_history_store[("Execution history")]
end

subgraph group_scheduler["Scheduling and consensus"]
  node_raft_manager["Raft cluster manager"]
  node_raft_state["Replicated scheduler state"]
  node_hash_ranges["Hash range assignment<br/>[HashRange.java]"]
  node_polling["Polling worker<br/>[PollingWorker.java]"]
  node_recovery["Recovery worker"]
  node_dispatch["Task dispatch"]
  node_scheduler_schedule_store[("Scheduler schedule repository")]
  node_event_producer["Task event producer"]
end

subgraph group_execution["Task execution"]
  node_consumer["Task execution consumer"]
  node_idempotency["Execution deduplication"]
  node_execution_service["Task execution service"]
  node_execution_job_store[("Execution job repository<br/>[JobRepository.java]")]
  node_execution_history_store[("Execution history repository")]
end

node_user(("User"))
node_kafka["Kafka task topic"]
node_callback["Job callback service"]

node_user -->|"uses"| node_dashboard
node_dashboard -.->|"requests data"| node_frontend_api
node_frontend_api -.->|"calls REST API"| node_job_api
node_frontend_api -.->|"requests JWT"| node_auth_api
node_user -->|"signs in"| node_auth_api
node_auth_api -->|"delegates to"| node_auth_service
node_auth_service -->|"reads and writes"| node_user_store
node_auth_service -->|"manages tokens"| node_refresh_tokens
node_job_api -->|"delegates to"| node_job_service
node_job_service -->|"reads and writes"| node_job_store
node_job_service -->|"syncs schedules"| node_schedule_store
node_job_service -->|"reads history"| node_history_store
node_job_api -->|"serves job data"| node_dashboard
node_schedule_store -->|"polled by"| node_polling
node_raft_manager -->|"updates replicated state"| node_raft_state
node_raft_manager -->|"calculates ranges"| node_hash_ranges
node_polling -.->|"dispatches due tasks"| node_dispatch
node_recovery -.->|"recovers missed tasks"| node_dispatch
node_dispatch -->|"deletes and reschedules"| node_scheduler_schedule_store
node_dispatch -->|"publishes batch"| node_event_producer
node_event_producer -->|"publishes events"| node_kafka
node_kafka -->|"delivers events"| node_consumer
node_consumer -.->|"checks duplicates"| node_idempotency
node_consumer -.->|"invokes execution"| node_execution_service
node_execution_service -->|"loads job"| node_execution_job_store
node_execution_service -->|"posts callback"| node_callback
node_execution_service -->|"writes history"| node_execution_history_store
node_execution_history_store -->|"history queried through"| node_job_api
node_polling -.->|"uses range ownership"| node_raft_state

click node_dashboard "https://github.com/patmesh/kairos-scheduler/blob/main/frontend/app/(dashboard)/dashboard/page.tsx"
click node_frontend_api "https://github.com/patmesh/kairos-scheduler/blob/main/frontend/lib/api.ts"
click node_auth_api "https://github.com/patmesh/kairos-scheduler/blob/main/user-auth-service/src/main/java/io/kairos/authservice/controller/AuthController.java"
click node_auth_service "https://github.com/patmesh/kairos-scheduler/blob/main/user-auth-service/src/main/java/io/kairos/authservice/service/AuthService.java"
click node_refresh_tokens "https://github.com/patmesh/kairos-scheduler/blob/main/user-auth-service/src/main/java/io/kairos/authservice/service/RefreshTokenService.java"
click node_user_store "https://github.com/patmesh/kairos-scheduler/blob/main/user-auth-service/src/main/java/io/kairos/authservice/repository/UserRepository.java"
click node_job_api "https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/controller/JobController.java"
click node_job_service "https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/service/JobService.java"
click node_job_store "https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/repository/JobRepository.java"
click node_schedule_store "https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/repository/TaskScheduleRepository.java"
click node_history_store "https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/repository/TaskExecutionHistoryRepository.java"
click node_raft_manager "https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/raft/RaftClusterManager.java"
click node_raft_state "https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/raft/SchedulerStateMachine.java"
click node_hash_ranges "https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/hashing/HashRange.java"
click node_polling "https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/polling/PollingWorker.java"
click node_recovery "https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/polling/RecoveryWorker.java"
click node_dispatch "https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/service/TaskDispatchService.java"
click node_scheduler_schedule_store "https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/repository/TaskScheduleRepository.java"
click node_event_producer "https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/kafka/producer/TaskEventProducer.java"
click node_consumer "https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/kafka/consumer/TaskExecutionConsumer.java"
click node_idempotency "https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/service/IdempotencyService.java"
click node_execution_service "https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java"
click node_execution_job_store "https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/repo/JobRepository.java"
click node_execution_history_store "https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/repo/TaskExecutionHistoryRepository.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_dashboard,node_frontend_api,node_user toneBlue
class node_auth_api,node_auth_service,node_refresh_tokens,node_user_store toneAmber
class node_job_api,node_job_service,node_job_store,node_schedule_store,node_history_store toneMint
class node_raft_manager,node_raft_state,node_hash_ranges,node_polling,node_recovery,node_dispatch,node_scheduler_schedule_store,node_event_producer,node_kafka toneRose
class node_consumer,node_idempotency,node_execution_service,node_execution_job_store,node_execution_history_store,node_callback toneIndigo
```

## Components

### User interface

- [Dashboard and schedules](https://github.com/patmesh/kairos-scheduler/blob/main/frontend/app/(dashboard)/dashboard/page.tsx): `frontend/app/(dashboard)/dashboard/page.tsx`
- [Frontend API client](https://github.com/patmesh/kairos-scheduler/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Authentication

- [Auth endpoints](https://github.com/patmesh/kairos-scheduler/blob/main/user-auth-service/src/main/java/io/kairos/authservice/controller/AuthController.java): `user-auth-service/src/main/java/io/kairos/authservice/controller/AuthController.java`
- [Auth service](https://github.com/patmesh/kairos-scheduler/blob/main/user-auth-service/src/main/java/io/kairos/authservice/service/AuthService.java): `user-auth-service/src/main/java/io/kairos/authservice/service/AuthService.java`
- [Refresh tokens](https://github.com/patmesh/kairos-scheduler/blob/main/user-auth-service/src/main/java/io/kairos/authservice/service/RefreshTokenService.java): `user-auth-service/src/main/java/io/kairos/authservice/service/RefreshTokenService.java`
- [User repository](https://github.com/patmesh/kairos-scheduler/blob/main/user-auth-service/src/main/java/io/kairos/authservice/repository/UserRepository.java): `user-auth-service/src/main/java/io/kairos/authservice/repository/UserRepository.java`

### Job management

- [Job REST API](https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/controller/JobController.java): `job-service/src/main/java/io/kairos/jobservice/controller/JobController.java`
- [Job lifecycle](https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/service/JobService.java): `job-service/src/main/java/io/kairos/jobservice/service/JobService.java`
- [Job records](https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/repository/JobRepository.java): `job-service/src/main/java/io/kairos/jobservice/repository/JobRepository.java`
- [Schedule records](https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/repository/TaskScheduleRepository.java): `job-service/src/main/java/io/kairos/jobservice/repository/TaskScheduleRepository.java`
- [Execution history](https://github.com/patmesh/kairos-scheduler/blob/main/job-service/src/main/java/io/kairos/jobservice/repository/TaskExecutionHistoryRepository.java): `job-service/src/main/java/io/kairos/jobservice/repository/TaskExecutionHistoryRepository.java`

### Scheduling and consensus

- [Raft cluster manager](https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/raft/RaftClusterManager.java): `scheduler-service/src/main/java/io/kairos/scheduler/raft/RaftClusterManager.java`
- [Replicated scheduler state](https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/raft/SchedulerStateMachine.java): `scheduler-service/src/main/java/io/kairos/scheduler/raft/SchedulerStateMachine.java`
- [Hash range assignment](https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/hashing/HashRange.java): `scheduler-service/src/main/java/io/kairos/scheduler/hashing/HashRange.java`
- [Polling worker](https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/polling/PollingWorker.java): `scheduler-service/src/main/java/io/kairos/scheduler/polling/PollingWorker.java`
- [Recovery worker](https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/polling/RecoveryWorker.java): `scheduler-service/src/main/java/io/kairos/scheduler/polling/RecoveryWorker.java`
- [Task dispatch](https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/service/TaskDispatchService.java): `scheduler-service/src/main/java/io/kairos/scheduler/service/TaskDispatchService.java`
- [Scheduler schedule repository](https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/repository/TaskScheduleRepository.java): `scheduler-service/src/main/java/io/kairos/scheduler/repository/TaskScheduleRepository.java`
- [Task event producer](https://github.com/patmesh/kairos-scheduler/blob/main/scheduler-service/src/main/java/io/kairos/scheduler/kafka/producer/TaskEventProducer.java): `scheduler-service/src/main/java/io/kairos/scheduler/kafka/producer/TaskEventProducer.java`

### Task execution

- [Task execution consumer](https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/kafka/consumer/TaskExecutionConsumer.java): `execution-service/src/main/java/io/kairos/execution/kafka/consumer/TaskExecutionConsumer.java`
- [Execution deduplication](https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/service/IdempotencyService.java): `execution-service/src/main/java/io/kairos/execution/service/IdempotencyService.java`
- [Task execution service](https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java): `execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java`
- [Execution job repository](https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/repo/JobRepository.java): `execution-service/src/main/java/io/kairos/execution/repo/JobRepository.java`
- [Execution history repository](https://github.com/patmesh/kairos-scheduler/blob/main/execution-service/src/main/java/io/kairos/execution/repo/TaskExecutionHistoryRepository.java): `execution-service/src/main/java/io/kairos/execution/repo/TaskExecutionHistoryRepository.java`

### Other components

- **User**
- **Kafka task topic**
- **Job callback service**

## Connections

- User → Dashboard and schedules: uses
- Dashboard and schedules → Frontend API client: requests data
- Frontend API client → Job REST API: calls REST API
- Frontend API client → Auth endpoints: requests JWT
- User → Auth endpoints: signs in (evidence: `user-auth-service/src/main/java/io/kairos/authservice/controller/AuthController.java`)
- Auth endpoints → Auth service: delegates to (evidence: `user-auth-service/src/main/java/io/kairos/authservice/controller/AuthController.java`)
- Auth service → User repository: reads and writes (evidence: `user-auth-service/src/main/java/io/kairos/authservice/service/AuthService.java`)
- Auth service → Refresh tokens: manages tokens (evidence: `user-auth-service/src/main/java/io/kairos/authservice/service/AuthService.java`)
- Job REST API → Job lifecycle: delegates to (evidence: `job-service/src/main/java/io/kairos/jobservice/controller/JobController.java`)
- Job lifecycle → Job records: reads and writes (evidence: `job-service/src/main/java/io/kairos/jobservice/service/JobService.java`)
- Job lifecycle → Schedule records: syncs schedules (evidence: `job-service/src/main/java/io/kairos/jobservice/service/JobService.java`)
- Job lifecycle → Execution history: reads history (evidence: `job-service/src/main/java/io/kairos/jobservice/service/JobService.java`)
- Job REST API → Dashboard and schedules: serves job data
- Schedule records → Polling worker: polled by
- Raft cluster manager → Replicated scheduler state: updates replicated state (evidence: `scheduler-service/src/main/java/io/kairos/scheduler/raft/RaftClusterManager.java`)
- Raft cluster manager → Hash range assignment: calculates ranges (evidence: `scheduler-service/src/main/java/io/kairos/scheduler/raft/RaftClusterManager.java`)
- Polling worker → Task dispatch: dispatches due tasks (evidence: `scheduler-service/src/main/java/io/kairos/scheduler/polling/PollingWorker.java`)
- Recovery worker → Task dispatch: recovers missed tasks
- Task dispatch → Scheduler schedule repository: deletes and reschedules (evidence: `scheduler-service/src/main/java/io/kairos/scheduler/service/TaskDispatchService.java`)
- Task dispatch → Task event producer: publishes batch (evidence: `scheduler-service/src/main/java/io/kairos/scheduler/service/TaskDispatchService.java`)
- Task event producer → Kafka task topic: publishes events
- Kafka task topic → Task execution consumer: delivers events
- Task execution consumer → Execution deduplication: checks duplicates
- Task execution consumer → Task execution service: invokes execution
- Task execution service → Execution job repository: loads job (evidence: `execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java`)
- Task execution service → Job callback service: posts callback (evidence: `execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java`)
- Task execution service → Execution history repository: writes history (evidence: `execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java`)
- Execution history repository → Job REST API: history queried through (evidence: `job-service/src/main/java/io/kairos/jobservice/controller/JobController.java`)
- Polling worker → Replicated scheduler state: uses range ownership (evidence: `scheduler-service/src/main/java/io/kairos/scheduler/polling/PollingWorker.java`)
