# tivix/django-cron architecture

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

- Interactive diagram: https://gitdiagram.com/tivix/django-cron
- Repository: https://github.com/tivix/django-cron

## Overview

django-cron provides configurable recurring Django/Python jobs, with management-command entry points, schedule and lock checks, execution, and persistent run history. The principal flow is an operator or loop invoking runcrons, which resolves configured jobs and delegates each to CronJobManager; the manager decides eligibility, acquires a configurable lock, runs job code, and records outcomes. Logs and locks are also exposed through Django admin. README confirms the broad purpose; sampled source supports the command, manager, models, and cache/database lock relationships, while file locking and notification details are only represented at subsystem level.

Main entry points: [`django_cron/core.py`](https://github.com/tivix/django-cron/blob/master/django_cron/core.py) (Job manager), [`django_cron/management/commands/runcrons.py`](https://github.com/tivix/django-cron/blob/master/django_cron/management/commands/runcrons.py) (Run crons), [`django_cron/models.py`](https://github.com/tivix/django-cron/blob/master/django_cron/models.py) (Run logs), [`django_cron/backends/lock`](https://github.com/tivix/django-cron/tree/master/django_cron/backends/lock) (Lock backends)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Invocation"]
  node_loop["Cron loop<br/>[cronloop.py]"]
  node_runcrons["Run crons<br/>[runcrons.py]"]
  node_configured["Configured jobs"]
end

subgraph group_runtime["Scheduling and execution"]
  node_manager["Job manager<br/>[core.py]"]
  node_schedule["Schedule rules<br/>[core.py]"]
  node_jobcode["Job code"]
  node_lockselect["Lock selection<br/>[core.py]"]
  node_lockbackends["Lock backends"]
  node_notifications["Failure notifications<br/>[cron.py]"]
end

subgraph group_state["Run state"]
  node_cache[("Django cache")]
  node_database[("Django database")]
  node_logs[("Run logs<br/>[models.py]")]
  node_locks[("Job locks<br/>[models.py]")]
  node_cleanup["Log cleanup<br/>[runcrons.py]"]
end

subgraph group_ops["Operations"]
  node_admin["Django admin<br/>[admin.py]"]
  node_humanize["Duration formatting<br/>[helpers.py]"]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_runcrons
node_operator -->|"starts"| node_loop
node_loop -->|"dispatches"| node_runcrons
node_runcrons -->|"resolves"| node_configured
node_runcrons -->|"creates"| node_manager
node_configured -->|"supplies jobs"| node_manager
node_manager -->|"checks eligibility"| node_schedule
node_manager -->|"selects lock"| node_lockselect
node_lockselect -->|"loads backend"| node_lockbackends
node_manager -->|"runs job"| node_jobcode
node_manager -->|"writes outcomes"| node_logs
node_manager -->|"acquires/releases"| node_lockbackends
node_lockbackends -.->|"uses cache"| node_cache
node_lockbackends -.->|"uses database locks"| node_locks
node_logs -->|"persists"| node_database
node_locks -->|"persists"| node_database
node_runcrons -->|"triggers cleanup"| node_cleanup
node_cleanup -->|"deletes old entries"| node_logs
node_notifications -->|"checks failures"| node_logs
node_admin -->|"browses"| node_logs
node_admin -->|"administers"| node_locks
node_admin -->|"formats duration"| node_humanize

click node_loop "https://github.com/tivix/django-cron/blob/master/django_cron/management/commands/cronloop.py"
click node_runcrons "https://github.com/tivix/django-cron/blob/master/django_cron/management/commands/runcrons.py"
click node_manager "https://github.com/tivix/django-cron/blob/master/django_cron/core.py"
click node_schedule "https://github.com/tivix/django-cron/blob/master/django_cron/core.py"
click node_lockselect "https://github.com/tivix/django-cron/blob/master/django_cron/core.py"
click node_lockbackends "https://github.com/tivix/django-cron/tree/master/django_cron/backends/lock"
click node_logs "https://github.com/tivix/django-cron/blob/master/django_cron/models.py"
click node_locks "https://github.com/tivix/django-cron/blob/master/django_cron/models.py"
click node_cleanup "https://github.com/tivix/django-cron/blob/master/django_cron/management/commands/runcrons.py"
click node_notifications "https://github.com/tivix/django-cron/blob/master/django_cron/cron.py"
click node_admin "https://github.com/tivix/django-cron/blob/master/django_cron/admin.py"
click node_humanize "https://github.com/tivix/django-cron/blob/master/django_cron/helpers.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_loop,node_runcrons,node_configured toneBlue
class node_manager,node_schedule,node_jobcode,node_lockselect,node_lockbackends,node_notifications toneAmber
class node_cache,node_database,node_logs,node_locks,node_cleanup toneMint
class node_admin,node_humanize toneRose
class node_operator toneIndigo
```

## Components

### Invocation

- [Cron loop](https://github.com/tivix/django-cron/blob/master/django_cron/management/commands/cronloop.py): `django_cron/management/commands/cronloop.py`
- [Run crons](https://github.com/tivix/django-cron/blob/master/django_cron/management/commands/runcrons.py): `django_cron/management/commands/runcrons.py`
- **Configured jobs**

### Scheduling and execution

- [Job manager](https://github.com/tivix/django-cron/blob/master/django_cron/core.py): `django_cron/core.py`
- [Schedule rules](https://github.com/tivix/django-cron/blob/master/django_cron/core.py): `django_cron/core.py`
- **Job code**
- [Lock selection](https://github.com/tivix/django-cron/blob/master/django_cron/core.py): `django_cron/core.py`
- [Lock backends](https://github.com/tivix/django-cron/tree/master/django_cron/backends/lock): `django_cron/backends/lock`
- [Failure notifications](https://github.com/tivix/django-cron/blob/master/django_cron/cron.py): `django_cron/cron.py`

### Run state

- **Django cache**
- **Django database**
- [Run logs](https://github.com/tivix/django-cron/blob/master/django_cron/models.py): `django_cron/models.py`
- [Job locks](https://github.com/tivix/django-cron/blob/master/django_cron/models.py): `django_cron/models.py`
- [Log cleanup](https://github.com/tivix/django-cron/blob/master/django_cron/management/commands/runcrons.py): `django_cron/management/commands/runcrons.py`

### Operations

- [Django admin](https://github.com/tivix/django-cron/blob/master/django_cron/admin.py): `django_cron/admin.py`
- [Duration formatting](https://github.com/tivix/django-cron/blob/master/django_cron/helpers.py): `django_cron/helpers.py`

### Other components

- **Operator**

## Connections

- Operator → Run crons: invokes
- Operator → Cron loop: starts
- Cron loop → Run crons: dispatches
- Run crons → Configured jobs: resolves
- Run crons → Job manager: creates
- Configured jobs → Job manager: supplies jobs
- Job manager → Schedule rules: checks eligibility
- Job manager → Lock selection: selects lock
- Lock selection → Lock backends: loads backend
- Job manager → Job code: runs job
- Job manager → Run logs: writes outcomes
- Job manager → Lock backends: acquires/releases
- Lock backends → Django cache: uses cache
- Lock backends → Job locks: uses database locks
- Run logs → Django database: persists
- Job locks → Django database: persists
- Run crons → Log cleanup: triggers cleanup
- Log cleanup → Run logs: deletes old entries
- Failure notifications → Run logs: checks failures
- Django admin → Run logs: browses
- Django admin → Job locks: administers
- Django admin → Duration formatting: formats duration