# abhasbali/distributed-job-scheduler architecture

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

- Interactive diagram: https://gitdiagram.com/abhasbali/distributed-job-scheduler
- Repository: https://github.com/abhasbali/distributed-job-scheduler

## Overview

Orbital is a distributed job-scheduling platform: users manage organizations, projects, queues and jobs through a dashboard and API; worker processes claim and execute jobs, while scheduling, retries, heartbeats and dead-letter handling support recurring and crash-recoverable execution. The graph separates API, domain services, execution, persistence and dashboard concerns. Several controllers and the scheduler are represented at their exact enclosing directories because their source was not excerpted; their detailed internal calls are therefore omitted.

Main entry points: [`backend/src/config/prisma.ts`](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/config/prisma.ts) (Prisma client), [`backend/src/workers/WorkerRuntime.ts`](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/workers/WorkerRuntime.ts) (Worker runtime), [`backend/src/api/controllers`](https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/api/controllers) (API controllers), [`backend/src/repositories`](https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/repositories) (Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_server["HTTP server<br/>[server.ts]"]
  node_app["Express app<br/>[app.ts]"]
  node_routes["API routes<br/>[index.ts]"]
  node_controllers["API controllers"]
  node_auth["Authentication<br/>[AuthService.ts]"]
  node_auth_middleware["Token middleware<br/>[authMiddleware.ts]"]
end

subgraph group_domain["Scheduling domain"]
  node_job_service["Job service<br/>[JobService.ts]"]
  node_queue_service["Queue service<br/>[QueueService.ts]"]
  node_domain_services["Domain services"]
  node_scheduler["Recurring scheduler"]
end

subgraph group_execution["Job execution"]
  node_worker["Worker runtime<br/>[WorkerRuntime.ts]"]
  node_claim["Atomic job claims<br/>[JobClaimService.ts]"]
  node_retry["Retry strategy<br/>[RetryStrategy.ts]"]
  node_dead_letter["Dead-letter handling"]
  node_heartbeat["Worker heartbeats"]
end

subgraph group_data["Persistence and infrastructure"]
  node_repositories["Repositories"]
  node_prisma["Prisma client<br/>[prisma.ts]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

subgraph group_ui["Dashboard"]
  node_dashboard["Dashboard views"]
  node_login["Login view<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

node_user(("Platform user"))

node_user -->|"uses"| node_dashboard
node_user -->|"signs in"| node_login
node_dashboard -.->|"requests data"| node_api_client
node_login -.->|"requests tokens"| node_api_client
node_api_client -.->|"calls API"| node_server
node_server -->|"creates"| node_app
node_app -->|"mounts"| node_routes
node_routes -->|"routes to"| node_controllers
node_controllers -->|"invokes"| node_auth
node_controllers -->|"invokes"| node_job_service
node_controllers -->|"invokes"| node_queue_service
node_routes -->|"applies"| node_auth_middleware
node_auth_middleware -->|"verifies access token"| node_auth
node_job_service -->|"uses job repository"| node_repositories
node_queue_service -->|"uses queue repository"| node_repositories
node_auth -->|"uses user repository"| node_repositories
node_job_service -->|"accesses database"| node_prisma
node_worker -->|"claims jobs"| node_claim
node_worker -->|"computes retry delay"| node_retry
node_worker -->|"moves exhausted jobs"| node_dead_letter
node_worker -->|"starts heartbeat"| node_heartbeat
node_worker -->|"records execution"| node_prisma
node_claim -->|"claims in database"| node_prisma
node_dead_letter -->|"updates job records"| node_prisma
node_heartbeat -->|"updates worker state"| node_prisma
node_repositories -->|"uses client"| node_prisma
node_prisma -->|"persists data"| node_postgres
node_app -.->|"rate limiting"| node_redis
node_scheduler -.->|"scheduling state"| node_prisma
node_domain_services -.->|"domain persistence"| node_prisma

click node_dashboard "https://github.com/abhasbali/distributed-job-scheduler/tree/main/frontend/src/app/(dashboard)"
click node_login "https://github.com/abhasbali/distributed-job-scheduler/blob/main/frontend/src/app/login/page.tsx"
click node_api_client "https://github.com/abhasbali/distributed-job-scheduler/blob/main/frontend/src/lib/api.ts"
click node_server "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/server.ts"
click node_app "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/app.ts"
click node_routes "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/api/routes/index.ts"
click node_controllers "https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/api/controllers"
click node_auth "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/services/AuthService.ts"
click node_auth_middleware "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/api/middleware/authMiddleware.ts"
click node_job_service "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/services/JobService.ts"
click node_queue_service "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/services/QueueService.ts"
click node_domain_services "https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/services"
click node_scheduler "https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/scheduler"
click node_worker "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/workers/WorkerRuntime.ts"
click node_claim "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/queues/JobClaimService.ts"
click node_retry "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/retry/RetryStrategy.ts"
click node_dead_letter "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/queues/DeadLetterService.ts"
click node_heartbeat "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/heartbeat/HeartbeatEmitter.ts"
click node_repositories "https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/repositories"
click node_prisma "https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/config/prisma.ts"

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_server,node_app,node_routes,node_controllers,node_auth,node_auth_middleware,node_user toneBlue
class node_job_service,node_queue_service,node_domain_services,node_scheduler toneAmber
class node_worker,node_claim,node_retry,node_dead_letter,node_heartbeat toneMint
class node_repositories,node_prisma,node_postgres,node_redis toneRose
class node_dashboard,node_login,node_api_client toneIndigo
```

## Components

### API and identity

- [HTTP server](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Express app](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [API routes](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/api/routes/index.ts): `backend/src/api/routes/index.ts`
- [API controllers](https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/api/controllers): `backend/src/api/controllers`
- [Authentication](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/services/AuthService.ts): `backend/src/services/AuthService.ts`
- [Token middleware](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/api/middleware/authMiddleware.ts): `backend/src/api/middleware/authMiddleware.ts`

### Scheduling domain

- [Job service](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/services/JobService.ts): `backend/src/services/JobService.ts`
- [Queue service](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/services/QueueService.ts): `backend/src/services/QueueService.ts`
- [Domain services](https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/services): `backend/src/services`
- [Recurring scheduler](https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/scheduler): `backend/src/scheduler`

### Job execution

- [Worker runtime](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/workers/WorkerRuntime.ts): `backend/src/workers/WorkerRuntime.ts`
- [Atomic job claims](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/queues/JobClaimService.ts): `backend/src/queues/JobClaimService.ts`
- [Retry strategy](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/retry/RetryStrategy.ts): `backend/src/retry/RetryStrategy.ts`
- [Dead-letter handling](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/queues/DeadLetterService.ts): `backend/src/queues/DeadLetterService.ts`
- [Worker heartbeats](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/heartbeat/HeartbeatEmitter.ts): `backend/src/heartbeat/HeartbeatEmitter.ts`

### Persistence and infrastructure

- [Repositories](https://github.com/abhasbali/distributed-job-scheduler/tree/main/backend/src/repositories): `backend/src/repositories`
- [Prisma client](https://github.com/abhasbali/distributed-job-scheduler/blob/main/backend/src/config/prisma.ts): `backend/src/config/prisma.ts`
- **PostgreSQL**
- **Redis**

### Dashboard

- [Dashboard views](https://github.com/abhasbali/distributed-job-scheduler/tree/main/frontend/src/app/(dashboard)): `frontend/src/app/(dashboard)`
- [Login view](https://github.com/abhasbali/distributed-job-scheduler/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [API client](https://github.com/abhasbali/distributed-job-scheduler/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Other components

- **Platform user**

## Connections

- Platform user → Dashboard views: uses (evidence: `README.md`)
- Platform user → Login view: signs in (evidence: `README.md`)
- Dashboard views → API client: requests data
- Login view → API client: requests tokens
- API client → HTTP server: calls API
- HTTP server → Express app: creates (evidence: `backend/src/server.ts`)
- Express app → API routes: mounts (evidence: `backend/src/app.ts`)
- API routes → API controllers: routes to (evidence: `backend/src/api/routes/index.ts`)
- API controllers → Authentication: invokes (evidence: `backend/src/api/controllers/authController.ts`)
- API controllers → Job service: invokes (evidence: `backend/src/api/controllers/jobController.ts`)
- API controllers → Queue service: invokes (evidence: `backend/src/api/controllers/queueController.ts`)
- API routes → Token middleware: applies (evidence: `backend/src/api/routes/index.ts`)
- Token middleware → Authentication: verifies access token (evidence: `backend/src/api/middleware/authMiddleware.ts`)
- Job service → Repositories: uses job repository (evidence: `backend/src/services/JobService.ts`)
- Queue service → Repositories: uses queue repository (evidence: `backend/src/services/QueueService.ts`)
- Authentication → Repositories: uses user repository (evidence: `backend/src/services/AuthService.ts`)
- Job service → Prisma client: accesses database (evidence: `backend/src/services/JobService.ts`)
- Worker runtime → Atomic job claims: claims jobs (evidence: `backend/src/workers/WorkerRuntime.ts`)
- Worker runtime → Retry strategy: computes retry delay (evidence: `backend/src/workers/WorkerRuntime.ts`)
- Worker runtime → Dead-letter handling: moves exhausted jobs (evidence: `backend/src/workers/WorkerRuntime.ts`)
- Worker runtime → Worker heartbeats: starts heartbeat (evidence: `backend/src/workers/WorkerRuntime.ts`)
- Worker runtime → Prisma client: records execution (evidence: `backend/src/workers/WorkerRuntime.ts`)
- Atomic job claims → Prisma client: claims in database (evidence: `backend/src/queues/JobClaimService.ts`)
- Dead-letter handling → Prisma client: updates job records (evidence: `backend/src/queues/DeadLetterService.ts`)
- Worker heartbeats → Prisma client: updates worker state (evidence: `backend/src/heartbeat/HeartbeatEmitter.ts`)
- Repositories → Prisma client: uses client (evidence: `backend/src/repositories/JobRepository.ts`)
- Prisma client → PostgreSQL: persists data (evidence: `README.md`)
- Express app → Redis: rate limiting (evidence: `backend/src/app.ts`)
- Recurring scheduler → Prisma client: scheduling state (evidence: `README.md`)
- Domain services → Prisma client: domain persistence (evidence: `README.md`)
