# aryan9787/concurrent-job-queue-engine architecture

> Architecture diagram of the GitHub repository aryan9787/concurrent-job-queue-engine, 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/aryan9787/concurrent-job-queue-engine
- Repository: https://github.com/aryan9787/concurrent-job-queue-engine

## Overview

This is a Spring-based persistent job queue. Clients submit, list, and revive jobs or register workers through REST controllers; workers claim due jobs, dispatch them to type-specific handlers, and report completion or failure. Retry timing and leases support re-execution, while scheduled recovery and load-based scaling maintain worker capacity. The graph follows the sampled service, worker, and repository references; handler execution and some scheduler wiring are represented only where the source index or excerpts support them.

Main entry points: [`src/main/java/com/ayush/jobqueue/service/JobService.java`](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/service/JobService.java) (Job service), [`src/main/java/com/ayush/jobqueue/repository/WorkerRepository.java`](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/repository/WorkerRepository.java) (Worker repository), [`src/main/java/com/ayush/jobqueue/Workers/WorkerManager.java`](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/Workers/WorkerManager.java) (Worker manager), [`src/main/java/com/ayush/jobqueue/repository/JobRepository.java`](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/repository/JobRepository.java) (Job repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_job_api["Job endpoints<br/>[JobController.java]"]
  node_worker_api["Worker endpoints"]
  node_job_dto["Revive request"]
  node_worker_dto["Registration request"]
end

subgraph group_jobs["Job Lifecycle"]
  node_job_service["Job service<br/>[JobService.java]"]
  node_handler_registry["Handler registry"]
  node_job_handler["Handler contract<br/>[JobHandler.java]"]
  node_typed_handlers["Typed handlers"]
end

subgraph group_workers["Worker Runtime"]
  node_worker_manager["Worker manager<br/>[WorkerManager.java]"]
  node_worker_thread["Worker loop<br/>[WorkerThread.java]"]
  node_worker_service["Worker service<br/>[WorkerService.java]"]
end

subgraph group_ops["Recovery and Scaling"]
  node_scaling_scheduler["Scaling scheduler"]
  node_scaling_service["Scaling service"]
  node_recovery_scheduler["Recovery scheduler"]
  node_recovery_service["Recovery service"]
end

subgraph group_persistence["Persistence"]
  node_job_repository["Job repository<br/>[JobRepository.java]"]
  node_worker_repository["Worker repository"]
  node_job_model["Job state<br/>[Job.java]"]
  node_worker_model["Worker state<br/>[Worker.java]"]
end

node_client(("Queue client"))
node_database[("Relational database")]

node_client -->|"submits jobs"| node_job_api
node_client -->|"registers workers"| node_worker_api
node_job_api -->|"delegates requests"| node_job_service
node_worker_api -->|"delegates requests"| node_worker_service
node_job_api -->|"accepts revive data"| node_job_dto
node_worker_api -->|"accepts registration"| node_worker_dto
node_job_service -->|"gets retry limit"| node_handler_registry
node_handler_registry -->|"indexes handlers"| node_job_handler
node_typed_handlers -->|"implements contract"| node_job_handler
node_worker_thread -->|"claims and updates jobs"| node_job_service
node_worker_thread -->|"dispatches job types"| node_handler_registry
node_worker_thread -->|"sends heartbeats"| node_worker_service
node_worker_manager -->|"registers worker"| node_worker_service
node_worker_manager -->|"starts worker loop"| node_worker_thread
node_worker_manager -->|"provides job service"| node_job_service
node_worker_manager -->|"provides handlers"| node_handler_registry
node_scaling_scheduler -->|"triggers evaluation"| node_scaling_service
node_scaling_service -->|"counts pending jobs"| node_job_repository
node_scaling_service -->|"checks worker capacity"| node_worker_repository
node_scaling_service -->|"starts workers"| node_worker_manager
node_recovery_scheduler -->|"triggers recovery"| node_recovery_service
node_recovery_service -->|"recovers jobs"| node_job_repository
node_recovery_service -->|"checks workers"| node_worker_repository
node_job_service -->|"reads and writes jobs"| node_job_repository
node_job_service -->|"loads worker for claim"| node_worker_repository
node_worker_service -->|"reads and writes workers"| node_worker_repository
node_job_repository -->|"persists job records"| node_job_model
node_worker_repository -->|"persists worker records"| node_worker_model
node_job_repository -->|"queries and stores"| node_database
node_worker_repository -->|"queries and stores"| node_database

click node_job_api "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/controller/JobController.java"
click node_worker_api "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/controller/WorkerController.java"
click node_job_service "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/service/JobService.java"
click node_job_dto "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/DTO/JobReviveRequest.java"
click node_handler_registry "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/handler/HandlerRegistry.java"
click node_job_handler "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/handler/JobHandler.java"
click node_typed_handlers "https://github.com/aryan9787/concurrent-job-queue-engine/tree/main/src/main/java/com/ayush/jobqueue/handler"
click node_worker_manager "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/Workers/WorkerManager.java"
click node_worker_thread "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/Workers/WorkerThread.java"
click node_worker_service "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/service/WorkerService.java"
click node_worker_dto "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/DTO/WorkerRegisterRequest.java"
click node_scaling_scheduler "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/scheduler/ScalingScheduler.java"
click node_scaling_service "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/service/ScalingService.java"
click node_recovery_scheduler "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/scheduler/RecoveryScheduler.java"
click node_recovery_service "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/service/RecoveryService.java"
click node_job_repository "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/repository/JobRepository.java"
click node_worker_repository "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/repository/WorkerRepository.java"
click node_job_model "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/entity/Job.java"
click node_worker_model "https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/entity/Worker.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_job_api,node_worker_api,node_job_dto,node_worker_dto toneBlue
class node_job_service,node_handler_registry,node_job_handler,node_typed_handlers,node_database toneAmber
class node_worker_manager,node_worker_thread,node_worker_service toneMint
class node_scaling_scheduler,node_scaling_service,node_recovery_scheduler,node_recovery_service,node_client toneRose
class node_job_repository,node_worker_repository,node_job_model,node_worker_model toneIndigo
```

## Components

### REST API

- [Job endpoints](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/controller/JobController.java): `src/main/java/com/ayush/jobqueue/controller/JobController.java`
- [Worker endpoints](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/controller/WorkerController.java): `src/main/java/com/ayush/jobqueue/controller/WorkerController.java`
- [Revive request](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/DTO/JobReviveRequest.java): `src/main/java/com/ayush/jobqueue/DTO/JobReviveRequest.java`
- [Registration request](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/DTO/WorkerRegisterRequest.java): `src/main/java/com/ayush/jobqueue/DTO/WorkerRegisterRequest.java`

### Job Lifecycle

- [Job service](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/service/JobService.java): `src/main/java/com/ayush/jobqueue/service/JobService.java`
- [Handler registry](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/handler/HandlerRegistry.java): `src/main/java/com/ayush/jobqueue/handler/HandlerRegistry.java`
- [Handler contract](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/handler/JobHandler.java): `src/main/java/com/ayush/jobqueue/handler/JobHandler.java`
- [Typed handlers](https://github.com/aryan9787/concurrent-job-queue-engine/tree/main/src/main/java/com/ayush/jobqueue/handler): `src/main/java/com/ayush/jobqueue/handler`

### Worker Runtime

- [Worker manager](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/Workers/WorkerManager.java): `src/main/java/com/ayush/jobqueue/Workers/WorkerManager.java`
- [Worker loop](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/Workers/WorkerThread.java): `src/main/java/com/ayush/jobqueue/Workers/WorkerThread.java`
- [Worker service](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/service/WorkerService.java): `src/main/java/com/ayush/jobqueue/service/WorkerService.java`

### Recovery and Scaling

- [Scaling scheduler](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/scheduler/ScalingScheduler.java): `src/main/java/com/ayush/jobqueue/scheduler/ScalingScheduler.java`
- [Scaling service](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/service/ScalingService.java): `src/main/java/com/ayush/jobqueue/service/ScalingService.java`
- [Recovery scheduler](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/scheduler/RecoveryScheduler.java): `src/main/java/com/ayush/jobqueue/scheduler/RecoveryScheduler.java`
- [Recovery service](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/service/RecoveryService.java): `src/main/java/com/ayush/jobqueue/service/RecoveryService.java`

### Persistence

- [Job repository](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/repository/JobRepository.java): `src/main/java/com/ayush/jobqueue/repository/JobRepository.java`
- [Worker repository](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/repository/WorkerRepository.java): `src/main/java/com/ayush/jobqueue/repository/WorkerRepository.java`
- [Job state](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/entity/Job.java): `src/main/java/com/ayush/jobqueue/entity/Job.java`
- [Worker state](https://github.com/aryan9787/concurrent-job-queue-engine/blob/main/src/main/java/com/ayush/jobqueue/entity/Worker.java): `src/main/java/com/ayush/jobqueue/entity/Worker.java`

### Other components

- **Queue client**
- **Relational database**

## Connections

- Queue client → Job endpoints: submits jobs (evidence: `src/main/java/com/ayush/jobqueue/controller/JobController.java`)
- Queue client → Worker endpoints: registers workers (evidence: `src/main/java/com/ayush/jobqueue/controller/WorkerController.java`)
- Job endpoints → Job service: delegates requests (evidence: `src/main/java/com/ayush/jobqueue/controller/JobController.java`)
- Worker endpoints → Worker service: delegates requests (evidence: `src/main/java/com/ayush/jobqueue/controller/WorkerController.java`)
- Job endpoints → Revive request: accepts revive data (evidence: `src/main/java/com/ayush/jobqueue/controller/JobController.java`)
- Worker endpoints → Registration request: accepts registration (evidence: `src/main/java/com/ayush/jobqueue/controller/WorkerController.java`)
- Job service → Handler registry: gets retry limit (evidence: `src/main/java/com/ayush/jobqueue/service/JobService.java`)
- Handler registry → Handler contract: indexes handlers (evidence: `src/main/java/com/ayush/jobqueue/handler/HandlerRegistry.java`)
- Typed handlers → Handler contract: implements contract (evidence: `src/main/java/com/ayush/jobqueue/handler/EmailJobHandler.java`)
- Worker loop → Job service: claims and updates jobs (evidence: `src/main/java/com/ayush/jobqueue/Workers/WorkerThread.java`)
- Worker loop → Handler registry: dispatches job types (evidence: `src/main/java/com/ayush/jobqueue/Workers/WorkerThread.java`)
- Worker loop → Worker service: sends heartbeats (evidence: `src/main/java/com/ayush/jobqueue/Workers/WorkerThread.java`)
- Worker manager → Worker service: registers worker (evidence: `src/main/java/com/ayush/jobqueue/Workers/WorkerManager.java`)
- Worker manager → Worker loop: starts worker loop (evidence: `src/main/java/com/ayush/jobqueue/Workers/WorkerManager.java`)
- Worker manager → Job service: provides job service (evidence: `src/main/java/com/ayush/jobqueue/Workers/WorkerManager.java`)
- Worker manager → Handler registry: provides handlers (evidence: `src/main/java/com/ayush/jobqueue/Workers/WorkerManager.java`)
- Scaling scheduler → Scaling service: triggers evaluation (evidence: `src/main/java/com/ayush/jobqueue/scheduler/ScalingScheduler.java`)
- Scaling service → Job repository: counts pending jobs (evidence: `src/main/java/com/ayush/jobqueue/service/ScalingService.java`)
- Scaling service → Worker repository: checks worker capacity (evidence: `src/main/java/com/ayush/jobqueue/service/ScalingService.java`)
- Scaling service → Worker manager: starts workers (evidence: `src/main/java/com/ayush/jobqueue/service/ScalingService.java`)
- Recovery scheduler → Recovery service: triggers recovery (evidence: `src/main/java/com/ayush/jobqueue/scheduler/RecoveryScheduler.java`)
- Recovery service → Job repository: recovers jobs (evidence: `src/main/java/com/ayush/jobqueue/service/RecoveryService.java`)
- Recovery service → Worker repository: checks workers (evidence: `src/main/java/com/ayush/jobqueue/service/RecoveryService.java`)
- Job service → Job repository: reads and writes jobs (evidence: `src/main/java/com/ayush/jobqueue/service/JobService.java`)
- Job service → Worker repository: loads worker for claim (evidence: `src/main/java/com/ayush/jobqueue/service/JobService.java`)
- Worker service → Worker repository: reads and writes workers (evidence: `src/main/java/com/ayush/jobqueue/service/WorkerService.java`)
- Job repository → Job state: persists job records (evidence: `src/main/java/com/ayush/jobqueue/repository/JobRepository.java`)
- Worker repository → Worker state: persists worker records (evidence: `src/main/java/com/ayush/jobqueue/repository/WorkerRepository.java`)
- Job repository → Relational database: queries and stores (evidence: `src/main/java/com/ayush/jobqueue/repository/JobRepository.java`)
- Worker repository → Relational database: queries and stores (evidence: `src/main/java/com/ayush/jobqueue/repository/WorkerRepository.java`)