# agronholm/apscheduler architecture

> Architecture diagram of the GitHub repository agronholm/apscheduler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agronholm/apscheduler
- Repository: https://github.com/agronholm/apscheduler

## Overview

##### Main Components
a. Scheduler Core:
- This is the central engine that manages job scheduling, triggering, and execution.
b. Triggers:
- Various scheduling mechanisms – cron, interval, calendar interval, date and combinatorial triggers.
- As dedicated components or submodules that feed configuration into the scheduler.
c. Data Stores (Persistent Storage):
- In-memory (memory.py)
- SQL databases (sqlalchemy.py)
- MongoDB (mongodb.py)
- These modules are responsible for persisting the job schedules, allowing multiple scheduler instances to share the same job information and survive restarts.
d. Event Brokers (for Distributed Coordination):
- Event broker components that facilitate communication in multi-node setups:
- PostgreSQL, Redis, MQTT integration modules.
- API integration that allows the scheduler to send/receive events (job added, job executed, etc.) to these brokers.
e. Executors:
- These components manage how jobs are executed. Include:
- Thread-based (thread.py)
- Process/subprocess-based (subprocess.py)
- Asynchronous executors (async_.py, qt.py)
- The executors provide the bridge between scheduling and the actual execution of tasks.

##### Integration (API) Details for the 3 Key Areas
a. Datastores:
- How the scheduler core communicates with the datastore APIs to load, update, and persist job information.
- Abstraction layers (base API) that allow different datastore implementations to plug in seamlessly.
b. Event Brokers:
- That the scheduler connects with these brokers via a standardized event broker interface, which abstracts the differences between implementations (asyncpg, redis, mqtt).
c. Executors:
- That the executor layer adapts the scheduler’s job data into task execution, taking into account both synchronous and asynchronous paradigms.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly separate the core scheduling logic from the persistence (datastores), messaging (event brokers), and execution (executors) aspects.
- Pluggable Architecture: Use abstract base classes (e.g., in datastores and event brokers directories) to allow for multiple implementations.
- Modularity: Each component (or submodule) – schedulers, triggers, datastores, event brokers, executors – should be drawn as separate blocks with clear APIs that indicate how they integrate with the scheduler core.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Triggers Subgraph
    subgraph "Triggers"
        TR1["Cron Trigger"]:::trigger
        TR2["Date Trigger"]:::trigger
        TR3["Interval Trigger"]:::trigger
        TR4["Calendar Interval Trigger"]:::trigger
        TR5["Combining Trigger"]:::trigger
    end

    %% Scheduler Core Subgraph
    subgraph "Scheduler Core"
        SC1["Synchronous Scheduler"]:::scheduler
        SC2["Asynchronous Scheduler"]:::scheduler
    end

    %% Data Stores Subgraph
    subgraph "Data Stores"
        DS4["Datastore Base"]:::datastore
        DS1["Memory Store"]:::datastore
        DS2["SQLAlchemy Store"]:::datastore
        DS3["MongoDB Store"]:::datastore
    end

    %% Event Brokers Subgraph
    subgraph "Event Brokers"
        EB6["Event Broker Base"]:::eventbrokers
        EB1["Asyncpg Broker"]:::eventbrokers
        EB2["Psycopg Broker"]:::eventbrokers
        EB3["Redis Broker"]:::eventbrokers
        EB4["MQTT Broker"]:::eventbrokers
        EB5["Local Broker"]:::eventbrokers
    end

    %% Executors Subgraph
    subgraph "Executors"
        EX1["Thread Executor"]:::executor
        EX2["Subprocess Executor"]:::executor
        EX3["Async Executor"]:::executor
        EX4["QT Executor"]:::executor
    end

    %% Connections from Triggers to Scheduler Core
    TR1 -->|"configure"| SC1
    TR1 -->|"configure"| SC2

    %% Connections from Scheduler Core to Data Stores
    SC1 -->|"persist_job_data"| DS4
    SC2 -->|"persist_job_data"| DS4
    DS4 -->|"load/update_jobs"| DS1
    DS4 -->|"load/update_jobs"| DS2
    DS4 -->|"load/update_jobs"| DS3

    %% Connections from Scheduler Core to Event Brokers
    SC1 -->|"publish/subscribe"| EB6
    SC2 -->|"publish/subscribe"| EB6
    EB6 -->|"distribute_events"| EB1
    EB6 -->|"distribute_events"| EB2
    EB6 -->|"distribute_events"| EB3
    EB6 -->|"distribute_events"| EB4
    EB6 -->|"distribute_events"| EB5

    %% Connections from Scheduler Core to Executors
    SC1 -->|"dispatch_job"| EX1
    SC1 -->|"dispatch_job"| EX2
    SC1 -->|"dispatch_job"| EX3
    SC1 -->|"dispatch_job"| EX4
    SC2 -->|"dispatch_job"| EX1
    SC2 -->|"dispatch_job"| EX2
    SC2 -->|"dispatch_job"| EX3
    SC2 -->|"dispatch_job"| EX4

    %% Feedback arrow from Executors to Scheduler (example for one executor)
    EX1 -->|"execution_result"| SC1

    %% Click Events for Scheduler Core
    click SC1 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/_schedulers/sync.py"
    click SC2 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/_schedulers/async_.py"

    %% Click Events for Triggers
    click TR1 "https://github.com/agronholm/apscheduler/tree/master/src/apscheduler/triggers/cron"
    click TR2 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/triggers/date.py"
    click TR3 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/triggers/interval.py"
    click TR4 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/triggers/calendarinterval.py"
    click TR5 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/triggers/combining.py"

    %% Click Events for Data Stores
    click DS1 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/datastores/memory.py"
    click DS2 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/datastores/sqlalchemy.py"
    click DS3 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/datastores/mongodb.py"
    click DS4 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/datastores/base.py"

    %% Click Events for Event Brokers
    click EB1 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/eventbrokers/asyncpg.py"
    click EB2 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/eventbrokers/psycopg.py"
    click EB3 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/eventbrokers/redis.py"
    click EB4 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/eventbrokers/mqtt.py"
    click EB5 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/eventbrokers/local.py"
    click EB6 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/eventbrokers/base.py"

    %% Click Events for Executors
    click EX1 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/executors/thread.py"
    click EX2 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/executors/subprocess.py"
    click EX3 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/executors/async_.py"
    click EX4 "https://github.com/agronholm/apscheduler/blob/master/src/apscheduler/executors/qt.py"

    %% Styles
    classDef scheduler fill:#ffefc6,stroke:#b58900,stroke-width:2px;
    classDef trigger fill:#d1e8ff,stroke:#268bd2,stroke-width:2px;
    classDef datastore fill:#dff0d8,stroke:#859900,stroke-width:2px;
    classDef eventbrokers fill:#ffdddd,stroke:#dc322f,stroke-width:2px;
    classDef executor fill:#e0ffff,stroke:#2aa198,stroke-width:2px;
```
