# burhaanashraf/job-scheduler-platform architecture

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

- Interactive diagram: https://gitdiagram.com/burhaanashraf/job-scheduler-platform
- Repository: https://github.com/burhaanashraf/job-scheduler-platform

## Overview

This is a distributed job-scheduling platform: clients submit and manage jobs through an authenticated API, Redis carries queued and scheduled work, workers invoke callback URLs and record outcomes, and a separate scheduler promotes delayed and recurring jobs. The graph also captures API-key provisioning, retry/dead-letter handling, persistence, and metrics. Relationships are limited to calls shown in excerpts or references in the source index; the README is empty, so some subsystem capabilities and wiring remain unverified.

Main entry points: [`internal/worker/processor.go`](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/worker/processor.go) (Job processor), [`cmd/api/handlers.go`](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/api/handlers.go) (Job handlers), [`internal/scheduler/scheduler.go`](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/scheduler/scheduler.go) (Cron and due dispatch), [`internal/stream/group.go`](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/stream/group.go) (Queue and schedule operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Job API"]
  node_api_service["HTTP API<br/>[main.go]"]
  node_routes["Routes and middleware<br/>[router.go]"]
  node_handlers["Job handlers<br/>[handlers.go]"]
  node_auth["Key authentication<br/>[auth.go]"]
end

subgraph group_dispatch["Scheduling"]
  node_stream["Queue and schedule operations<br/>[group.go]"]
  node_schedule_script["Schedule promotion script<br/>[schedule.lua.go]"]
  node_scheduler_service["Scheduler process<br/>[main.go]"]
  node_scheduler["Cron and due dispatch<br/>[scheduler.go]"]
  node_cron_calc["Cron calculation<br/>[cron.go]"]
  node_leader["Leader lock<br/>[leader.go]"]
end

subgraph group_execution["Job execution"]
  node_worker_service["Worker process<br/>[main.go]"]
  node_worker["Queue consumer<br/>[worker.go]"]
  node_processor["Job processor<br/>[processor.go]"]
  node_http_executor["HTTP callback executor<br/>[http.go]"]
  node_retry["Retry backoff<br/>[retry.go]"]
end

subgraph group_state["State and observability"]
  node_api_keys[("Key records<br/>[api_keys.go]")]
  node_job_repo[("Job repository<br/>[jobs.go]")]
  node_cron_repo[("Cron repository<br/>[cron_jobs.go]")]
  node_execution_repo[("Execution records<br/>[executions.go]")]
  node_metrics["Metrics collector<br/>[metrics.go]"]
end

subgraph group_provision["Key provisioning"]
  node_apikey_command["Key provisioning command<br/>[main.go]"]
  node_key_generator["Key generation<br/>[generate.go]"]
end

node_client(("API client"))
node_redis[("Redis service")]
node_callback(("Job callback"))

node_client -->|"sends requests"| node_routes
node_api_service -->|"serves routes"| node_routes
node_routes -->|"authenticates"| node_auth
node_routes -->|"dispatches requests"| node_handlers
node_auth -->|"looks up key"| node_api_keys
node_handlers -->|"reads and changes jobs"| node_job_repo
node_handlers -->|"manages cron jobs"| node_cron_repo
node_handlers -->|"enqueues jobs"| node_stream
node_handlers -->|"increments submissions"| node_metrics
node_api_service -->|"registers collector"| node_metrics
node_scheduler_service -->|"runs scheduler"| node_scheduler
node_scheduler_service -->|"provides repository"| node_cron_repo
node_scheduler_service -->|"configures leadership"| node_leader
node_scheduler -->|"loads and creates instances"| node_cron_repo
node_scheduler -->|"promotes and enqueues"| node_stream
node_scheduler -->|"checks leadership"| node_leader
node_scheduler -->|"calculates next run"| node_cron_calc
node_stream -.->|"runs promotion script"| node_schedule_script
node_worker_service -->|"runs consumer"| node_worker
node_worker_service -->|"provides processor"| node_processor
node_worker -->|"reads messages"| node_stream
node_worker -->|"processes messages"| node_processor
node_processor -->|"loads and updates jobs"| node_job_repo
node_processor -->|"records attempts"| node_execution_repo
node_processor -->|"executes callback"| node_http_executor
node_http_executor -.->|"sends HTTP request"| node_callback
node_processor -->|"retries and acknowledges"| node_stream
node_processor -->|"gets backoff"| node_retry
node_processor -->|"counts outcomes"| node_metrics
node_apikey_command -->|"generates key"| node_key_generator
node_apikey_command -->|"stores hashed key"| node_api_keys

click node_api_service "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/api/main.go"
click node_routes "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/api/router.go"
click node_handlers "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/api/handlers.go"
click node_auth "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/api/auth.go"
click node_api_keys "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/repository/api_keys.go"
click node_job_repo "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/repository/jobs.go"
click node_cron_repo "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/repository/cron_jobs.go"
click node_execution_repo "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/repository/executions.go"
click node_stream "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/stream/group.go"
click node_schedule_script "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/stream/schedule.lua.go"
click node_scheduler_service "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/scheduler/main.go"
click node_scheduler "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/scheduler/scheduler.go"
click node_cron_calc "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/scheduler/cron.go"
click node_leader "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/scheduler/leader.go"
click node_worker_service "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/worker/main.go"
click node_worker "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/worker/worker.go"
click node_processor "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/worker/processor.go"
click node_http_executor "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/executor/http.go"
click node_retry "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/retry/retry.go"
click node_metrics "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/metrics/metrics.go"
click node_apikey_command "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/apikey/main.go"
click node_key_generator "https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/apikey/generate.go"

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_api_service,node_routes,node_handlers,node_auth,node_client toneBlue
class node_stream,node_schedule_script,node_scheduler_service,node_scheduler,node_cron_calc,node_leader,node_redis toneAmber
class node_worker_service,node_worker,node_processor,node_http_executor,node_retry toneMint
class node_api_keys,node_job_repo,node_cron_repo,node_execution_repo,node_metrics toneRose
class node_apikey_command,node_key_generator,node_callback toneIndigo
```

## Components

### Job API

- [HTTP API](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Routes and middleware](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/api/router.go): `cmd/api/router.go`
- [Job handlers](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/api/handlers.go): `cmd/api/handlers.go`
- [Key authentication](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/api/auth.go): `internal/api/auth.go`

### Scheduling

- [Queue and schedule operations](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/stream/group.go): `internal/stream/group.go`
- [Schedule promotion script](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/stream/schedule.lua.go): `internal/stream/schedule.lua.go`
- [Scheduler process](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/scheduler/main.go): `cmd/scheduler/main.go`
- [Cron and due dispatch](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/scheduler/scheduler.go): `internal/scheduler/scheduler.go`
- [Cron calculation](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/scheduler/cron.go): `internal/scheduler/cron.go`
- [Leader lock](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/scheduler/leader.go): `internal/scheduler/leader.go`

### Job execution

- [Worker process](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/worker/main.go): `cmd/worker/main.go`
- [Queue consumer](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/worker/worker.go): `internal/worker/worker.go`
- [Job processor](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/worker/processor.go): `internal/worker/processor.go`
- [HTTP callback executor](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/executor/http.go): `internal/executor/http.go`
- [Retry backoff](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/retry/retry.go): `internal/retry/retry.go`

### State and observability

- [Key records](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/repository/api_keys.go): `internal/repository/api_keys.go`
- [Job repository](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/repository/jobs.go): `internal/repository/jobs.go`
- [Cron repository](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/repository/cron_jobs.go): `internal/repository/cron_jobs.go`
- [Execution records](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/repository/executions.go): `internal/repository/executions.go`
- [Metrics collector](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`

### Key provisioning

- [Key provisioning command](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/cmd/apikey/main.go): `cmd/apikey/main.go`
- [Key generation](https://github.com/burhaanashraf/job-scheduler-platform/blob/main/internal/apikey/generate.go): `internal/apikey/generate.go`

### Other components

- **API client**
- **Redis service**
- **Job callback**

## Connections

- API client → Routes and middleware: sends requests (evidence: `cmd/api/router.go`)
- HTTP API → Routes and middleware: serves routes (evidence: `cmd/api/main.go`)
- Routes and middleware → Key authentication: authenticates (evidence: `cmd/api/router.go`)
- Routes and middleware → Job handlers: dispatches requests (evidence: `cmd/api/router.go`)
- Key authentication → Key records: looks up key (evidence: `internal/api/auth.go`)
- Job handlers → Job repository: reads and changes jobs (evidence: `cmd/api/handlers.go`)
- Job handlers → Cron repository: manages cron jobs (evidence: `cmd/api/handlers.go`)
- Job handlers → Queue and schedule operations: enqueues jobs (evidence: `cmd/api/handlers.go`)
- Job handlers → Metrics collector: increments submissions (evidence: `cmd/api/handlers.go`)
- HTTP API → Metrics collector: registers collector (evidence: `cmd/api/main.go`)
- Scheduler process → Cron and due dispatch: runs scheduler (evidence: `cmd/scheduler/main.go`)
- Scheduler process → Cron repository: provides repository (evidence: `cmd/scheduler/main.go`)
- Scheduler process → Leader lock: configures leadership (evidence: `cmd/scheduler/main.go`)
- Cron and due dispatch → Cron repository: loads and creates instances (evidence: `internal/scheduler/scheduler.go`)
- Cron and due dispatch → Queue and schedule operations: promotes and enqueues (evidence: `internal/scheduler/scheduler.go`)
- Cron and due dispatch → Leader lock: checks leadership (evidence: `internal/scheduler/scheduler.go`)
- Cron and due dispatch → Cron calculation: calculates next run (evidence: `internal/scheduler/scheduler.go`)
- Queue and schedule operations → Schedule promotion script: runs promotion script
- Worker process → Queue consumer: runs consumer (evidence: `cmd/worker/main.go`)
- Worker process → Job processor: provides processor (evidence: `cmd/worker/main.go`)
- Queue consumer → Queue and schedule operations: reads messages (evidence: `internal/worker/worker.go`)
- Queue consumer → Job processor: processes messages (evidence: `internal/worker/worker.go`)
- Job processor → Job repository: loads and updates jobs (evidence: `internal/worker/processor.go`)
- Job processor → Execution records: records attempts (evidence: `internal/worker/processor.go`)
- Job processor → HTTP callback executor: executes callback (evidence: `internal/worker/processor.go`)
- HTTP callback executor → Job callback: sends HTTP request
- Job processor → Queue and schedule operations: retries and acknowledges (evidence: `internal/worker/processor.go`)
- Job processor → Retry backoff: gets backoff (evidence: `internal/worker/processor.go`)
- Job processor → Metrics collector: counts outcomes (evidence: `internal/worker/processor.go`)
- Key provisioning command → Key generation: generates key (evidence: `cmd/apikey/main.go`)
- Key provisioning command → Key records: stores hashed key (evidence: `cmd/apikey/main.go`)