# kshitij7498/codity.ai_distributed-job-scheduler. architecture

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

- Interactive diagram: https://gitdiagram.com/kshitij7498/codity.ai_distributed-job-scheduler.
- Repository: https://github.com/kshitij7498/codity.ai_distributed-job-scheduler.

## Overview

Distributed Job Scheduler is a multi-tenant platform for submitting immediate, delayed, scheduled, recurring, and batch jobs, then executing them across workers with retries, leases, heartbeats, execution history, and DLQ recovery. Users configure organizations, projects, queues, and retry policies through the REST API and dashboard; workers claim and execute jobs against PostgreSQL, while API endpoints expose fleet and job monitoring. Edges reflect the README, source excerpts, and SOURCE INDEX references; unsampled subsystem connections are omitted where their runtime wiring is not shown.

Main entry points: [`backend/app/api/router.py`](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/router.py) (REST Router), [`backend/app/db/session.py`](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/db/session.py) (Database Sessions), [`backend/app/workers/service.py`](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/service.py) (Worker Lifecycle and Execution), [`backend/app/api/routes/auth.py`](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/auth.py) (Authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Dashboard and API"]
  node_dashboard["Control Dashboard<br/>[main.jsx]"]
  node_api_router["REST Router<br/>[router.py]"]
end

subgraph group_tenancy["Identity and Tenancy"]
  node_auth_routes["Authentication API<br/>[auth.py]"]
  node_auth_security["JWT Security<br/>[security.py]"]
  node_auth_dependencies["User Authentication<br/>[dependencies.py]"]
  node_auth_schemas["Auth Schemas<br/>[schemas.py]"]
  node_organizations["Organizations API<br/>[organizations.py]"]
  node_projects["Projects API<br/>[projects.py]"]
end

subgraph group_jobs["Job Management"]
  node_queues["Queues and Retry Policies<br/>[queues.py]"]
  node_jobs_api["Jobs API<br/>[jobs.py]"]
  node_job_service["Job Creation and Scheduling<br/>[service.py]"]
  node_job_schemas["Job Schemas<br/>[schemas.py]"]
  node_dlq_api["DLQ Recovery API<br/>[dlq.py]"]
end

subgraph group_execution["Worker Runtime"]
  node_worker_api["Worker Fleet API<br/>[workers.py]"]
  node_monitoring_api["Monitoring API<br/>[monitoring.py]"]
  node_worker_runner["Worker Process<br/>[runner.py]"]
  node_worker_service["Worker Lifecycle and Execution<br/>[service.py]"]
  node_job_claimer["Atomic Job Claiming<br/>[claimer.py]"]
  node_job_executor["Payload Executor<br/>[executor.py]"]
  node_scheduler["Schedule Dispatcher<br/>[scheduler.py]"]
end

subgraph group_data["Persistence and State"]
  node_models["Scheduler Data Model<br/>[models.py]"]
  node_enums["Lifecycle and Type Enums<br/>[enums.py]"]
  node_db_session["Database Sessions<br/>[session.py]"]
  node_config["Runtime Configuration<br/>[config.py]"]
  node_postgres[("PostgreSQL")]
end

node_user(("Scheduler User"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"calls REST API"| node_api_router
node_api_router -->|"registers"| node_auth_routes
node_api_router -->|"registers"| node_organizations
node_api_router -->|"registers"| node_projects
node_api_router -->|"registers"| node_queues
node_api_router -->|"registers"| node_jobs_api
node_api_router -->|"registers"| node_worker_api
node_api_router -->|"registers"| node_monitoring_api
node_api_router -->|"registers"| node_dlq_api
node_auth_routes -->|"hashes and signs"| node_auth_security
node_auth_routes -->|"validates with"| node_auth_schemas
node_auth_dependencies -->|"decodes token"| node_auth_security
node_auth_routes -->|"uses session"| node_db_session
node_organizations -->|"uses session"| node_db_session
node_projects -->|"uses session"| node_db_session
node_queues -->|"checks project access"| node_projects
node_queues -->|"uses session"| node_db_session
node_jobs_api -->|"creates jobs"| node_job_service
node_jobs_api -->|"validates with"| node_job_schemas
node_job_service -->|"accepts payloads"| node_job_schemas
node_job_service -->|"creates job records"| node_models
node_worker_runner -->|"runs worker"| node_worker_service
node_worker_runner -->|"starts scheduler"| node_scheduler
node_worker_service -->|"claims and marks running"| node_job_claimer
node_worker_service -->|"executes payload"| node_job_executor
node_worker_service -->|"opens sessions"| node_db_session
node_worker_api -->|"uses session"| node_db_session
node_monitoring_api -->|"uses session"| node_db_session
node_dlq_api -->|"uses session"| node_db_session
node_db_session -->|"configures connection"| node_config
node_db_session -->|"connects"| node_postgres
node_models -->|"defines state with"| node_enums
node_job_claimer -->|"claims transactionally"| node_postgres
node_worker_service -->|"persists execution and heartbeats"| node_postgres

click node_dashboard "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/frontend/src/main.jsx"
click node_api_router "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/router.py"
click node_auth_routes "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/auth.py"
click node_auth_security "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/auth/security.py"
click node_auth_dependencies "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/auth/dependencies.py"
click node_auth_schemas "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/auth/schemas.py"
click node_organizations "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/organizations.py"
click node_projects "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/projects.py"
click node_queues "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/queues.py"
click node_jobs_api "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/jobs.py"
click node_job_service "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/jobs/service.py"
click node_job_schemas "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/jobs/schemas.py"
click node_dlq_api "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/dlq.py"
click node_worker_api "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/workers.py"
click node_monitoring_api "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/monitoring.py"
click node_worker_runner "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/runner.py"
click node_worker_service "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/service.py"
click node_job_claimer "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/claimer.py"
click node_job_executor "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/executor.py"
click node_scheduler "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/scheduler.py"
click node_models "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/models/models.py"
click node_enums "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/models/enums.py"
click node_db_session "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/db/session.py"
click node_config "https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/core/config.py"

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_api_router toneBlue
class node_auth_routes,node_auth_security,node_auth_dependencies,node_auth_schemas,node_organizations,node_projects toneAmber
class node_queues,node_jobs_api,node_job_service,node_job_schemas,node_dlq_api toneMint
class node_worker_api,node_monitoring_api,node_worker_runner,node_worker_service,node_job_claimer,node_job_executor,node_scheduler,node_user toneRose
class node_models,node_enums,node_db_session,node_config,node_postgres toneIndigo
```

## Components

### Dashboard and API

- [Control Dashboard](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [REST Router](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/router.py): `backend/app/api/router.py`

### Identity and Tenancy

- [Authentication API](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/auth.py): `backend/app/api/routes/auth.py`
- [JWT Security](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/auth/security.py): `backend/app/auth/security.py`
- [User Authentication](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/auth/dependencies.py): `backend/app/auth/dependencies.py`
- [Auth Schemas](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/auth/schemas.py): `backend/app/auth/schemas.py`
- [Organizations API](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/organizations.py): `backend/app/api/routes/organizations.py`
- [Projects API](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/projects.py): `backend/app/api/routes/projects.py`

### Job Management

- [Queues and Retry Policies](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/queues.py): `backend/app/api/routes/queues.py`
- [Jobs API](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/jobs.py): `backend/app/api/routes/jobs.py`
- [Job Creation and Scheduling](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/jobs/service.py): `backend/app/jobs/service.py`
- [Job Schemas](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/jobs/schemas.py): `backend/app/jobs/schemas.py`
- [DLQ Recovery API](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/dlq.py): `backend/app/api/routes/dlq.py`

### Worker Runtime

- [Worker Fleet API](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/workers.py): `backend/app/api/routes/workers.py`
- [Monitoring API](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/api/routes/monitoring.py): `backend/app/api/routes/monitoring.py`
- [Worker Process](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/runner.py): `backend/app/workers/runner.py`
- [Worker Lifecycle and Execution](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/service.py): `backend/app/workers/service.py`
- [Atomic Job Claiming](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/claimer.py): `backend/app/workers/claimer.py`
- [Payload Executor](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/executor.py): `backend/app/workers/executor.py`
- [Schedule Dispatcher](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/workers/scheduler.py): `backend/app/workers/scheduler.py`

### Persistence and State

- [Scheduler Data Model](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/models/models.py): `backend/app/models/models.py`
- [Lifecycle and Type Enums](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/models/enums.py): `backend/app/models/enums.py`
- [Database Sessions](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Runtime Configuration](https://github.com/kshitij7498/codity.ai_distributed-job-scheduler./blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- **PostgreSQL**

### Other components

- **Scheduler User**

## Connections

- Scheduler User → Control Dashboard: uses (evidence: `README.md`)
- Control Dashboard → REST Router: calls REST API (evidence: `README.md`)
- REST Router → Authentication API: registers (evidence: `backend/app/api/router.py`)
- REST Router → Organizations API: registers (evidence: `backend/app/api/router.py`)
- REST Router → Projects API: registers (evidence: `backend/app/api/router.py`)
- REST Router → Queues and Retry Policies: registers (evidence: `backend/app/api/router.py`)
- REST Router → Jobs API: registers (evidence: `backend/app/api/router.py`)
- REST Router → Worker Fleet API: registers (evidence: `backend/app/api/router.py`)
- REST Router → Monitoring API: registers (evidence: `backend/app/api/router.py`)
- REST Router → DLQ Recovery API: registers (evidence: `backend/app/api/router.py`)
- Authentication API → JWT Security: hashes and signs (evidence: `backend/app/api/routes/auth.py`)
- Authentication API → Auth Schemas: validates with (evidence: `backend/app/api/routes/auth.py`)
- User Authentication → JWT Security: decodes token (evidence: `backend/app/auth/dependencies.py`)
- Authentication API → Database Sessions: uses session (evidence: `backend/app/api/routes/auth.py`)
- Organizations API → Database Sessions: uses session (evidence: `backend/app/api/routes/organizations.py`)
- Projects API → Database Sessions: uses session (evidence: `backend/app/api/routes/projects.py`)
- Queues and Retry Policies → Projects API: checks project access (evidence: `backend/app/api/routes/queues.py`)
- Queues and Retry Policies → Database Sessions: uses session (evidence: `backend/app/api/routes/queues.py`)
- Jobs API → Job Creation and Scheduling: creates jobs (evidence: `backend/app/api/routes/jobs.py`)
- Jobs API → Job Schemas: validates with (evidence: `backend/app/api/routes/jobs.py`)
- Job Creation and Scheduling → Job Schemas: accepts payloads (evidence: `backend/app/jobs/service.py`)
- Job Creation and Scheduling → Scheduler Data Model: creates job records (evidence: `backend/app/jobs/service.py`)
- Worker Process → Worker Lifecycle and Execution: runs worker (evidence: `backend/app/workers/runner.py`)
- Worker Process → Schedule Dispatcher: starts scheduler (evidence: `backend/app/workers/runner.py`)
- Worker Lifecycle and Execution → Atomic Job Claiming: claims and marks running (evidence: `backend/app/workers/service.py`)
- Worker Lifecycle and Execution → Payload Executor: executes payload (evidence: `backend/app/workers/service.py`)
- Worker Lifecycle and Execution → Database Sessions: opens sessions (evidence: `backend/app/workers/service.py`)
- Worker Fleet API → Database Sessions: uses session (evidence: `backend/app/api/routes/workers.py`)
- Monitoring API → Database Sessions: uses session (evidence: `backend/app/api/routes/monitoring.py`)
- DLQ Recovery API → Database Sessions: uses session (evidence: `backend/app/api/routes/dlq.py`)
- Database Sessions → Runtime Configuration: configures connection (evidence: `backend/app/db/session.py`)
- Database Sessions → PostgreSQL: connects (evidence: `README.md`)
- Scheduler Data Model → Lifecycle and Type Enums: defines state with (evidence: `backend/app/models/models.py`)
- Atomic Job Claiming → PostgreSQL: claims transactionally (evidence: `README.md`)
- Worker Lifecycle and Execution → PostgreSQL: persists execution and heartbeats (evidence: `backend/app/workers/service.py`)
