How patmesh/kairos-scheduler works
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: JobService.java Job lifecycle · TaskExecutionService.java Task execution service · JobController.java Job REST API · TaskDispatchService.java Task dispatch
Components 27
User interface
- Dashboard and schedules
frontend/app/(dashboard)/dashboard/page.tsx - Frontend API client
frontend/lib/api.ts
Authentication
- Auth endpoints
user-auth-service/src/main/java/io/kairos/authservice/controller/AuthController.java - Auth service
user-auth-service/src/main/java/io/kairos/authservice/service/AuthService.java - Refresh tokens
user-auth-service/src/main/java/io/kairos/authservice/service/RefreshTokenService.java - User repository
user-auth-service/src/main/java/io/kairos/authservice/repository/UserRepository.java
Job management
- Job REST API
job-service/src/main/java/io/kairos/jobservice/controller/JobController.java - Job lifecycle
job-service/src/main/java/io/kairos/jobservice/service/JobService.java - Job records
job-service/src/main/java/io/kairos/jobservice/repository/JobRepository.java - Schedule records
job-service/src/main/java/io/kairos/jobservice/repository/TaskScheduleRepository.java - Execution history
job-service/src/main/java/io/kairos/jobservice/repository/TaskExecutionHistoryRepository.java
Scheduling and consensus
- Raft cluster manager
scheduler-service/src/main/java/io/kairos/scheduler/raft/RaftClusterManager.java - Replicated scheduler state
scheduler-service/src/main/java/io/kairos/scheduler/raft/SchedulerStateMachine.java - Hash range assignment
scheduler-service/src/main/java/io/kairos/scheduler/hashing/HashRange.java - Polling worker
scheduler-service/src/main/java/io/kairos/scheduler/polling/PollingWorker.java - Recovery worker
scheduler-service/src/main/java/io/kairos/scheduler/polling/RecoveryWorker.java - Task dispatch
scheduler-service/src/main/java/io/kairos/scheduler/service/TaskDispatchService.java - Scheduler schedule repository
scheduler-service/src/main/java/io/kairos/scheduler/repository/TaskScheduleRepository.java - Task event producer
scheduler-service/src/main/java/io/kairos/scheduler/kafka/producer/TaskEventProducer.java
Task execution
- Task execution consumer
execution-service/src/main/java/io/kairos/execution/kafka/consumer/TaskExecutionConsumer.java - Execution deduplication
execution-service/src/main/java/io/kairos/execution/service/IdempotencyService.java - Task execution service
execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java - Execution job repository
execution-service/src/main/java/io/kairos/execution/repo/JobRepository.java - Execution history repository
execution-service/src/main/java/io/kairos/execution/repo/TaskExecutionHistoryRepository.java
Other components
- User
- Kafka task topic
- Job callback service
Connections 29
- 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
user-auth-service/src/main/java/io/kairos/authservice/controller/AuthController.java - Auth endpoints → Auth service: delegates to
user-auth-service/src/main/java/io/kairos/authservice/controller/AuthController.java - Auth service → User repository: reads and writes
user-auth-service/src/main/java/io/kairos/authservice/service/AuthService.java - Auth service → Refresh tokens: manages tokens
user-auth-service/src/main/java/io/kairos/authservice/service/AuthService.java - Job REST API → Job lifecycle: delegates to
job-service/src/main/java/io/kairos/jobservice/controller/JobController.java - Job lifecycle → Job records: reads and writes
job-service/src/main/java/io/kairos/jobservice/service/JobService.java - Job lifecycle → Schedule records: syncs schedules
job-service/src/main/java/io/kairos/jobservice/service/JobService.java - Job lifecycle → Execution history: reads history
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
scheduler-service/src/main/java/io/kairos/scheduler/raft/RaftClusterManager.java - Raft cluster manager → Hash range assignment: calculates ranges
scheduler-service/src/main/java/io/kairos/scheduler/raft/RaftClusterManager.java - Polling worker → Task dispatch: dispatches due tasks
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
scheduler-service/src/main/java/io/kairos/scheduler/service/TaskDispatchService.java - Task dispatch → Task event producer: publishes batch
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
execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java - Task execution service → Job callback service: posts callback
execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java - Task execution service → Execution history repository: writes history
execution-service/src/main/java/io/kairos/execution/service/TaskExecutionService.java - Execution history repository → Job REST API: history queried through
job-service/src/main/java/io/kairos/jobservice/controller/JobController.java - Polling worker → Replicated scheduler state: uses range ownership
scheduler-service/src/main/java/io/kairos/scheduler/polling/PollingWorker.java