# go-co-op/gocron architecture

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

- Interactive diagram: https://gitdiagram.com/go-co-op/gocron
- Repository: https://github.com/go-co-op/gocron

## Overview

gocron is a Go scheduling library. A caller creates jobs from task functions and schedule definitions, registers them with a scheduler, starts it, and later shuts it down. The scheduler tracks run times and dispatches ready jobs to an executor, which runs tasks while enforcing concurrency rules. The README documents duration, random, cron, calendar, and one-time schedules, plus events, metrics, logging, and distributed coordination. Source excerpts show core dispatch and integration points; unsampled implementations are represented only where documented.

Main entry points: [`executor.go`](https://github.com/go-co-op/gocron/blob/v2/executor.go) (Executor), [`scheduler.go`](https://github.com/go-co-op/gocron/blob/v2/scheduler.go) (Scheduler), [`job.go`](https://github.com/go-co-op/gocron/blob/v2/job.go) (Schedule Definitions), [`distributed.go`](https://github.com/go-co-op/gocron/blob/v2/distributed.go) (Elector & Lock APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scheduling["Job Scheduling"]
  node_scheduler["Scheduler<br/>[scheduler.go]"]
  node_jobdefs["Schedule Definitions<br/>[job.go]"]
  node_job["Job &amp; Task<br/>[job.go]"]
end

subgraph group_runtime["Execution Runtime"]
  node_executor["Executor<br/>[executor.go]"]
  node_concurrency["Concurrency Controls<br/>[executor.go]"]
end

subgraph group_integrations["Monitoring &amp; Integrations"]
  node_distributed["Elector &amp; Lock APIs<br/>[distributed.go]"]
  node_monitor["Job Metrics<br/>[monitor.go]"]
  node_schedmonitor["Scheduler Events"]
  node_logger["Logger<br/>[logger.go]"]
end

node_caller(("Library Caller"))

node_caller -->|"creates and controls"| node_scheduler
node_caller -->|"selects schedule"| node_jobdefs
node_caller -->|"provides task"| node_job
node_scheduler -->|"configures job"| node_jobdefs
node_scheduler -->|"starts executor"| node_executor
node_scheduler -->|"dispatches runs"| node_executor
node_executor -->|"runs task"| node_job
node_executor -->|"applies limits"| node_concurrency
node_executor -->|"checks leadership"| node_distributed
node_executor -->|"acquires job lock"| node_distributed
node_executor -->|"records metrics"| node_monitor
node_scheduler -->|"notifies lifecycle"| node_schedmonitor
node_executor -->|"reports job events"| node_schedmonitor
node_executor -->|"writes logs"| node_logger
node_scheduler -->|"writes logs"| node_logger

click node_scheduler "https://github.com/go-co-op/gocron/blob/v2/scheduler.go"
click node_jobdefs "https://github.com/go-co-op/gocron/blob/v2/job.go"
click node_job "https://github.com/go-co-op/gocron/blob/v2/job.go"
click node_executor "https://github.com/go-co-op/gocron/blob/v2/executor.go"
click node_concurrency "https://github.com/go-co-op/gocron/blob/v2/executor.go"
click node_distributed "https://github.com/go-co-op/gocron/blob/v2/distributed.go"
click node_monitor "https://github.com/go-co-op/gocron/blob/v2/monitor.go"
click node_schedmonitor "https://github.com/go-co-op/gocron/blob/v2/scheduler_monitor.go"
click node_logger "https://github.com/go-co-op/gocron/blob/v2/logger.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_scheduler,node_jobdefs,node_job toneBlue
class node_executor,node_concurrency toneAmber
class node_distributed,node_monitor,node_schedmonitor,node_logger toneMint
class node_caller toneIndigo
```

## Components

### Job Scheduling

- [Scheduler](https://github.com/go-co-op/gocron/blob/v2/scheduler.go): `scheduler.go`
- [Schedule Definitions](https://github.com/go-co-op/gocron/blob/v2/job.go): `job.go`
- [Job & Task](https://github.com/go-co-op/gocron/blob/v2/job.go): `job.go`

### Execution Runtime

- [Executor](https://github.com/go-co-op/gocron/blob/v2/executor.go): `executor.go`
- [Concurrency Controls](https://github.com/go-co-op/gocron/blob/v2/executor.go): `executor.go`

### Monitoring & Integrations

- [Elector & Lock APIs](https://github.com/go-co-op/gocron/blob/v2/distributed.go): `distributed.go`
- [Job Metrics](https://github.com/go-co-op/gocron/blob/v2/monitor.go): `monitor.go`
- [Scheduler Events](https://github.com/go-co-op/gocron/blob/v2/scheduler_monitor.go): `scheduler_monitor.go`
- [Logger](https://github.com/go-co-op/gocron/blob/v2/logger.go): `logger.go`

### Other components

- **Library Caller**

## Connections

- Library Caller → Scheduler: creates and controls (evidence: `README.md`)
- Library Caller → Schedule Definitions: selects schedule (evidence: `README.md`)
- Library Caller → Job & Task: provides task (evidence: `README.md`)
- Scheduler → Schedule Definitions: configures job (evidence: `scheduler.go`)
- Scheduler → Executor: starts executor (evidence: `scheduler.go`)
- Scheduler → Executor: dispatches runs (evidence: `README.md`)
- Executor → Job & Task: runs task (evidence: `README.md`)
- Executor → Concurrency Controls: applies limits (evidence: `executor.go`)
- Executor → Elector & Lock APIs: checks leadership (evidence: `executor.go`)
- Executor → Elector & Lock APIs: acquires job lock (evidence: `distributed.go`)
- Executor → Job Metrics: records metrics (evidence: `executor.go`)
- Scheduler → Scheduler Events: notifies lifecycle (evidence: `scheduler.go`)
- Executor → Scheduler Events: reports job events (evidence: `executor.go`)
- Executor → Logger: writes logs (evidence: `executor.go`)
- Scheduler → Logger: writes logs (evidence: `scheduler.go`)
