# oban-bg/oban architecture

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

- Interactive diagram: https://gitdiagram.com/oban-bg/oban
- Repository: https://github.com/oban-bg/oban

## Overview

##### Main Components

a) Core System Components:
- Job Queue Management System
- Database Layer (PostgreSQL/MySQL/SQLite3)
- Queue Supervisors
- Plugin System
- Notification System
- Telemetry Integration

b) Key Architectural Elements:
- Multiple Engine Support
- Worker System
- Queue Management
- Job Processing Pipeline
- Plugin Architecture

**Application Code -> Oban.insert/1 -> Job Creation**

**Queue Supervision**
**Worker Execution**
**Plugin System**

**Database Engines**
**Notification System**

##### Component Relationships

a) Job Flow:
**Client -> Job Creation -> Queue Assignment -> Worker Execution -> Result Handling**

b) Supervision Tree:
**Oban.Supervisor**
- Queue.Supervisor
- Plugin.Supervisor
- Notification.Supervisor

##### Implementation Details

Implementation components:
- Engine Implementations (PostgreSQL, MySQL, SQLite)
- Queue Management (Producer, Executor, Watchman)
- Plugin System (Cron, Pruner, Repeater)
- Notification System (PG, Isolated)

##### Specific Features to Highlight

Create subsections showing:
- Job lifecycle states
- Priority handling
- Scheduling mechanisms
- Error handling and retries
- Monitoring and metrics

##### Integration Points

Clearly mark:
- Database connectivity
- Telemetry integration
- External system interfaces
- Plugin extension points

##### Scalability aspects

Remember to show both synchronous and asynchronous communication paths, and indicate where transactions and atomic operations are enforced.

This system design should reflect Oban's core principles of reliability, consistency, and observability while showing how it integrates with the broader Elixir/Erlang ecosystem.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client["Client Layer"]
        APP[Application Code]
        JOB[Job Creation]:::job
    end

    subgraph Core["Core Processing Layer"]
        QS[Queue Supervisor]:::supervisor
        WS[Worker System]:::worker
        PS[Plugin System]:::plugin
        
        subgraph Queues["Queue Management"]
            PROD[Producer]:::queue
            EXEC[Executor]:::queue
            WATCH[Watchman]:::queue
        end
        
        subgraph Workers["Worker Execution"]
            WORKER[Worker Core]:::worker
            JOBDEF[Job Definition]:::worker
        end
        
        subgraph Plugins["Plugin Components"]
            CRON[Cron Plugin]:::plugin
            PRUNER[Pruner Plugin]:::plugin
            REPEATER[Repeater Plugin]:::plugin
        end
    end

    subgraph Data["Data & Communication Layer"]
        subgraph DB["Database Engines"]
            PG[PostgreSQL]:::db
            MYSQL[MySQL]:::db
            SQLITE[SQLite]:::db
        end
        
        subgraph Notify["Notification System"]
            NOTCORE[Notifier Core]:::notify
            NOTPG[PG Notifier]:::notify
            NOTISO[Isolated Notifier]:::notify
        end
        
        TEL[Telemetry]:::telemetry
    end

    %% Connections
    APP --> JOB
    JOB --> QS
    QS --> Queues
    QS --> Workers
    QS --> Plugins
    PROD --> EXEC
    EXEC --> WATCH
    WORKER --> JOBDEF
    Queues --> DB
    Plugins --> DB
    Workers --> DB
    DB --> Notify
    Notify --> TEL

    %% Click Events
    click QS "https://github.com/oban-bg/oban/blob/main/lib/oban/queue/supervisor.ex"
    click PROD "https://github.com/oban-bg/oban/blob/main/lib/oban/queue/producer.ex"
    click EXEC "https://github.com/oban-bg/oban/blob/main/lib/oban/queue/executor.ex"
    click WATCH "https://github.com/oban-bg/oban/blob/main/lib/oban/queue/watchman.ex"
    click PG "https://github.com/oban-bg/oban/blob/main/lib/oban/engines/basic.ex"
    click MYSQL "https://github.com/oban-bg/oban/blob/main/lib/oban/engines/dolphin.ex"
    click SQLITE "https://github.com/oban-bg/oban/blob/main/lib/oban/engines/lite.ex"
    click PS "https://github.com/oban-bg/oban/blob/main/lib/oban/plugin.ex"
    click CRON "https://github.com/oban-bg/oban/blob/main/lib/oban/plugins/cron.ex"
    click PRUNER "https://github.com/oban-bg/oban/blob/main/lib/oban/plugins/pruner.ex"
    click REPEATER "https://github.com/oban-bg/oban/blob/main/lib/oban/plugins/repeater.ex"
    click NOTCORE "https://github.com/oban-bg/oban/blob/main/lib/oban/notifier.ex"
    click NOTPG "https://github.com/oban-bg/oban/blob/main/lib/oban/notifiers/pg.ex"
    click NOTISO "https://github.com/oban-bg/oban/blob/main/lib/oban/notifiers/isolated.ex"
    click TEL "https://github.com/oban-bg/oban/blob/main/lib/oban/telemetry.ex"
    click WORKER "https://github.com/oban-bg/oban/blob/main/lib/oban/worker.ex"
    click JOBDEF "https://github.com/oban-bg/oban/blob/main/lib/oban/job.ex"

    %% Styling
    classDef default fill:#fff,stroke:#333,stroke-width:2px
    classDef supervisor fill:#b8daff,stroke:#333
    classDef queue fill:#9ec5fe,stroke:#333
    classDef worker fill:#a3cfbb,stroke:#333
    classDef plugin fill:#ffd700,stroke:#333
    classDef db fill:#6c757d,stroke:#333,color:#fff
    classDef notify fill:#e0cffc,stroke:#333
    classDef telemetry fill:#20c997,stroke:#333
    classDef job fill:#ffc107,stroke:#333
```
