# procrastinate-org/procrastinate architecture

> Architecture diagram of the GitHub repository procrastinate-org/procrastinate, 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/procrastinate-org/procrastinate
- Repository: https://github.com/procrastinate-org/procrastinate

## Overview

Procrastinate is a Python task queue backed by PostgreSQL. Applications register tasks, defer jobs for immediate or scheduled execution, and workers fetch and execute them while persisting job status. The runtime also supports retries, periodic scheduling, middleware, and Django integration. The graph follows the documented workflow and SOURCE INDEX references; where implementation excerpts were unavailable, it omits uncertain relationships rather than inferring calls.

Main entry points: [`procrastinate/worker.py`](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/worker.py) (Worker), [`procrastinate/manager.py`](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/manager.py) (Job manager), [`procrastinate/app.py`](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/app.py) (Application), [`procrastinate/tasks.py`](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/tasks.py) (Task API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_definition["Task Definition"]
  node_app["Application<br/>[app.py]"]
  node_blueprints["Task registry<br/>[blueprints.py]"]
  node_tasks["Task API<br/>[tasks.py]"]
  node_jobs["Job model<br/>[jobs.py]"]
end

subgraph group_execution["Job Execution"]
  node_worker["Worker<br/>[worker.py]"]
  node_context["Job context<br/>[job_context.py]"]
  node_middleware["Task middleware<br/>[middleware.py]"]
  node_retry["Retry policy<br/>[retry.py]"]
  node_periodic["Periodic scheduling<br/>[periodic.py]"]
end

subgraph group_persistence["Queue Persistence"]
  node_manager["Job manager<br/>[manager.py]"]
  node_connector["Connector interface<br/>[connector.py]"]
  node_sql["SQL queries<br/>[__init__.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_interfaces["Interfaces &amp; Integrations"]
  node_cli["Command line<br/>[cli.py]"]
  node_django["Django integration"]
  node_django_settings["Django settings<br/>[settings.py]"]
  node_sync_connector["Sync PostgreSQL"]
  node_async_connector["Async PostgreSQL"]
end

node_producer(("Application code"))

node_producer -->|"configures"| node_app
node_app -->|"registers tasks"| node_blueprints
node_blueprints -->|"creates tasks"| node_tasks
node_producer -->|"defers jobs"| node_tasks
node_tasks -->|"configures jobs"| node_jobs
node_tasks -->|"submits jobs"| node_manager
node_app -->|"starts worker"| node_worker
node_worker -->|"fetches and updates"| node_manager
node_worker -->|"builds context"| node_context
node_worker -->|"composes middleware"| node_middleware
node_worker -->|"uses retry policy"| node_retry
node_worker -->|"runs periodic deferrer"| node_periodic
node_manager -->|"executes queries"| node_connector
node_manager -->|"uses queries"| node_sql
node_connector -->|"accesses database"| node_postgres
node_cli -->|"manages jobs"| node_manager
node_django -->|"adapts connector"| node_sync_connector
node_django -->|"adapts connector"| node_async_connector
node_django_settings -->|"configures"| node_app
node_sync_connector -->|"implements interface"| node_connector
node_async_connector -->|"implements interface"| node_connector

click node_app "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/app.py"
click node_blueprints "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/blueprints.py"
click node_tasks "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/tasks.py"
click node_jobs "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/jobs.py"
click node_worker "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/worker.py"
click node_context "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/job_context.py"
click node_middleware "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/middleware.py"
click node_retry "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/retry.py"
click node_periodic "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/periodic.py"
click node_manager "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/manager.py"
click node_connector "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/connector.py"
click node_sql "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/sql/__init__.py"
click node_cli "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/cli.py"
click node_django "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/contrib/django/django_connector.py"
click node_django_settings "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/contrib/django/settings.py"
click node_sync_connector "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/sync_psycopg_connector.py"
click node_async_connector "https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/psycopg_connector.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_app,node_blueprints,node_tasks,node_jobs toneBlue
class node_worker,node_context,node_middleware,node_retry,node_periodic toneAmber
class node_manager,node_connector,node_sql,node_postgres toneMint
class node_cli,node_django,node_django_settings,node_sync_connector,node_async_connector toneRose
class node_producer toneIndigo
```

## Components

### Task Definition

- [Application](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/app.py): `procrastinate/app.py`
- [Task registry](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/blueprints.py): `procrastinate/blueprints.py`
- [Task API](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/tasks.py): `procrastinate/tasks.py`
- [Job model](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/jobs.py): `procrastinate/jobs.py`

### Job Execution

- [Worker](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/worker.py): `procrastinate/worker.py`
- [Job context](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/job_context.py): `procrastinate/job_context.py`
- [Task middleware](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/middleware.py): `procrastinate/middleware.py`
- [Retry policy](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/retry.py): `procrastinate/retry.py`
- [Periodic scheduling](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/periodic.py): `procrastinate/periodic.py`

### Queue Persistence

- [Job manager](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/manager.py): `procrastinate/manager.py`
- [Connector interface](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/connector.py): `procrastinate/connector.py`
- [SQL queries](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/sql/__init__.py): `procrastinate/sql/__init__.py`
- **PostgreSQL**

### Interfaces & Integrations

- [Command line](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/cli.py): `procrastinate/cli.py`
- [Django integration](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/contrib/django/django_connector.py): `procrastinate/contrib/django/django_connector.py`
- [Django settings](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/contrib/django/settings.py): `procrastinate/contrib/django/settings.py`
- [Sync PostgreSQL](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/sync_psycopg_connector.py): `procrastinate/sync_psycopg_connector.py`
- [Async PostgreSQL](https://github.com/procrastinate-org/procrastinate/blob/main/procrastinate/psycopg_connector.py): `procrastinate/psycopg_connector.py`

### Other components

- **Application code**

## Connections

- Application code → Application: configures
- Application → Task registry: registers tasks (evidence: `procrastinate/app.py`)
- Task registry → Task API: creates tasks (evidence: `procrastinate/blueprints.py`)
- Application code → Task API: defers jobs
- Task API → Job model: configures jobs (evidence: `procrastinate/tasks.py`)
- Task API → Job manager: submits jobs (evidence: `procrastinate/tasks.py`)
- Application → Worker: starts worker (evidence: `procrastinate/app.py`)
- Worker → Job manager: fetches and updates (evidence: `procrastinate/worker.py`)
- Worker → Job context: builds context (evidence: `procrastinate/worker.py`)
- Worker → Task middleware: composes middleware (evidence: `procrastinate/worker.py`)
- Worker → Retry policy: uses retry policy (evidence: `procrastinate/worker.py`)
- Worker → Periodic scheduling: runs periodic deferrer (evidence: `procrastinate/worker.py`)
- Job manager → Connector interface: executes queries (evidence: `procrastinate/manager.py`)
- Job manager → SQL queries: uses queries (evidence: `procrastinate/manager.py`)
- Connector interface → PostgreSQL: accesses database
- Command line → Job manager: manages jobs (evidence: `procrastinate/cli.py`)
- Django integration → Sync PostgreSQL: adapts connector (evidence: `procrastinate/contrib/django/django_connector.py`)
- Django integration → Async PostgreSQL: adapts connector (evidence: `procrastinate/contrib/django/django_connector.py`)
- Django settings → Application: configures (evidence: `procrastinate/contrib/django/settings.py`)
- Sync PostgreSQL → Connector interface: implements interface (evidence: `procrastinate/sync_psycopg_connector.py`)
- Async PostgreSQL → Connector interface: implements interface (evidence: `procrastinate/psycopg_connector.py`)