# atifh/clj-scheduler architecture

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

- Interactive diagram: https://gitdiagram.com/atifh/clj-scheduler
- Repository: https://github.com/atifh/clj-scheduler

## Overview

##### Project Type and Purpose
- Type: Back‐end scheduling service (demo) with a lightweight web view
- Purpose: Integrate Quartz Scheduler in Clojure to run one-time, periodic, persistent, and cron tasks, backed by Postgres, with a Ring‐based UI for listing jobs.

##### File Structure
- Top-level directories:
– config/ : profile-specific config EDN files
– resources/ : Quartz properties, Logback config, SQL schema
– src/clj_scheduler/ : Clojure namespaces (core, db, log, various task modules)
– templates/ : HTML template for web view
– test/ : unit tests
- Key files:
– project.clj : dependencies (Quartz, JDBC, Ring, Hiccup/Selmer)
– setup_db.sh + quartz_tables_postgres.sql: Postgres job store setup
– resources/quartz.properties: Quartz engine config
– resources/logback.xml: logging config

##### README for Additional Insights
- Dependencies: Postgres, Leiningen, Clojure
- Usage flows:
– Running one-time, periodic, persistent, cron jobs via REPL API
– Running Ring server to serve an HTML page listing scheduled jobs

##### Main Components
a. Configuration Layer
- EDN files (dev/test/prod) and quartz.properties
- Injects DB connection info, scheduler properties, logging path
b. Scheduler Engine
- Quartz Scheduler embedded inside the Clojure app
- Uses a JDBC JobStore (Postgres) for persistence
c. Database
- Postgres instance with Quartz tables
- Populated via setup_db.sh + SQL script
d. Task Modules
- Namespaces: one_time_tasks, periodic_tasks, persistent_tasks, persistent_cron_tasks
- Each exposes a (schedule-job) function to register jobs with Quartz
e. Core & DB Access
- core.clj: initializes the scheduler, handles lifecycle
- db.clj: wraps JDBC calls (reads/writes Quartz meta-tables if needed)
f. Logging
- log.clj + logback.xml: routes scheduler and application logs to file
g. Web UI
- Ring server (in core.clj via “lein run server”)
- templates/tasks.html rendered via Hiccup or Selmer
- HTTP endpoint: GET / --> lists jobs by querying the Quartz store

##### Relationships & Data Flow
– App startup reads config → initializes Quartz with quartz.properties & DB credentials
– Task module calls → scheduler.scheduleJob() → Quartz enqueues job into JobStore
– Quartz thread pool executes jobs → task logic runs → logs emitted to file
– Web request → Ring handler → queries JobStore via core/db → renders tasks.html → HTTP response

##### Architectural Patterns & Tech
– Layered design: Config → Infrastructure (Quartz, DB, Logging) → Application logic (task modules, core) → Presentation (Ring + templates)
– Externalized configuration (EDN + properties)
– JDBC JobStore pattern for persistence
– REPL‐driven execution of task registration

##### Putting It All Together
1. Config Layer
2. Scheduler Engine
3. Task Modules
4. Core/DB Access
5. Web UI
6. Logging
– Connect Config → Scheduler Engine
– Connect Scheduler Engine ↔ Postgres DB
– Connect Scheduler Engine → Task Modules
– Connect Task Modules → Logging subsystem
– Connect Client Browser → Web UI → Core/DB Access → Postgres DB
– At the edge, show external tools: Leiningen, Postgres CLI, setup_db.sh

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Tools
    Leiningen["Leiningen CLI"]:::external
    PostgresCLI["Postgres CLI"]:::external
    SetupScript["setup_db.sh"]:::external
    QuartzSQL["quartz_tables_postgres.sql"]:::external

    %% Clojure App
    subgraph "Clojure App"
        subgraph "Configuration Layer"
            ConfigDev["config/dev/config-sample.edn"]:::config
            ConfigTest["config/test/config-sample.edn"]:::config
            ConfigProd["config/prod/config.edn"]:::config
            QuartzProps["resources/quartz.properties"]:::config
        end

        subgraph "Infrastructure"
            Scheduler["Quartz Scheduler\n(Thread Pool)"]:::infra
            PostgresDB[(Postgres JobStore)]:::db
        end

        subgraph "Application Logic"
            Core["core.clj\n(init & lifecycle)"]:::app
            DBAccess["db.clj\n(DB Access)"]:::app
            OneTime["one_time_tasks.clj"]:::app
            Periodic["periodic_tasks.clj"]:::app
            Persistent["persistent_tasks.clj"]:::app
            CronTasks["persistent_cron_tasks.clj"]:::app
        end

        subgraph "Presentation/UI"
            RingServer["Ring Server\n(GET /)"]:::ui
            Template["templates/tasks.html"]:::ui
        end

        subgraph "Logging"
            LogNS["log.clj"]:::logging
            LogConfig["resources/logback.xml"]:::config
        end
    end

    %% External relationships
    Leiningen -->|runs| Core
    PostgresCLI -->|initializes| PostgresDB
    SetupScript -->|executes| QuartzSQL
    QuartzSQL -->|creates tables| PostgresDB

    %% Config to Scheduler
    ConfigDev -->|injects| Scheduler
    ConfigTest -->|injects| Scheduler
    ConfigProd -->|injects| Scheduler
    QuartzProps -->|configures| Scheduler

    %% Core to Scheduler and Web
    Core -->|initializes| Scheduler
    Core -->|starts| RingServer

    %% Scheduler and DB
    Scheduler -->|JDBC| PostgresDB
    Scheduler -->|executes jobs| OneTime
    Scheduler -->|executes jobs| Periodic
    Scheduler -->|executes jobs| Persistent
    Scheduler -->|executes jobs| CronTasks

    %% Task Modules to Logging
    OneTime -->|logs| LogNS
    Periodic -->|logs| LogNS
    Persistent -->|logs| LogNS
    CronTasks -->|logs| LogNS

    %% Web UI flow
    RingServer -->|renders| Template
    RingServer -->|queries via JDBC| PostgresDB
    Template -->|delivers HTML| ClientBrowser["Client Browser"]:::external
    ClientBrowser -->|HTTP| RingServer

    %% DB Access usage
    DBAccess -->|wraps JDBC| PostgresDB
    RingServer -->|uses| DBAccess

    %% Click Events
    click ConfigDev "https://github.com/atifh/clj-scheduler/blob/master/config/dev/config-sample.edn"
    click ConfigTest "https://github.com/atifh/clj-scheduler/blob/master/config/test/config-sample.edn"
    click ConfigProd "https://github.com/atifh/clj-scheduler/blob/master/config/prod/config.edn"
    click QuartzProps "https://github.com/atifh/clj-scheduler/blob/master/resources/quartz.properties"
    click Core "https://github.com/atifh/clj-scheduler/blob/master/src/clj_scheduler/core.clj"
    click DBAccess "https://github.com/atifh/clj-scheduler/blob/master/src/clj_scheduler/db.clj"
    click OneTime "https://github.com/atifh/clj-scheduler/blob/master/src/clj_scheduler/one_time_tasks.clj"
    click Periodic "https://github.com/atifh/clj-scheduler/blob/master/src/clj_scheduler/periodic_tasks.clj"
    click Persistent "https://github.com/atifh/clj-scheduler/blob/master/src/clj_scheduler/persistent_tasks.clj"
    click CronTasks "https://github.com/atifh/clj-scheduler/blob/master/src/clj_scheduler/persistent_cron_tasks.clj"
    click LogNS "https://github.com/atifh/clj-scheduler/blob/master/src/clj_scheduler/log.clj"
    click LogConfig "https://github.com/atifh/clj-scheduler/blob/master/resources/logback.xml"
    click Template "https://github.com/atifh/clj-scheduler/blob/master/templates/tasks.html"
    click SetupScript "https://github.com/atifh/clj-scheduler/blob/master/setup_db.sh"
    click QuartzSQL "https://github.com/atifh/clj-scheduler/blob/master/resources/quartz_tables_postgres.sql"

    %% Styles
    classDef config fill:#D0E6FF,stroke:#0366d6
    classDef infra fill:#D0E6FF,stroke:#0366d6
    classDef app fill:#DFFFE0,stroke:#2E8B57
    classDef db fill:#FFEFD5,stroke:#FFA500
    classDef ui fill:#F3E6FF,stroke:#800080
    classDef logging fill:#F0F0F0,stroke:#808080
    classDef external fill:#E8E8E8,stroke:#A9A9A9
```
