# yt-koike/dify-cron architecture

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

- Interactive diagram: https://gitdiagram.com/yt-koike/dify-cron
- Repository: https://github.com/yt-koike/dify-cron

## Overview

##### Project type and purpose
- This is a Dify “extension” plugin named “Cron” (see README: **Type:** extension).
- Its purpose is to let Dify users schedule and trigger workflows at specified times or intervals using cron syntax and, in the cloud version, the external service cron-job.org.

##### File structure
- Top-level files:
- main.py           → plugin entry point
- manifest.yaml     → plugin metadata and endpoint definitions
- requirements.txt, .env.example, ruff.toml → dependencies and linting
- endpoints/        → Python code + YAML for each HTTP endpoint
- /cron.yaml   → group definition for permissions or routing
- tests/            → unit tests (e.g., test_cron.py)
- endpoints directory:
- cron.py + cron.yaml    → handles scheduling start/stop calls
- entry.py + entry.yaml  → handles incoming cron callback and triggers the workflow
- GUIDE.md, README.md, PRIVACY.md, OWNERSHIP.md, etc., provide docs and policies.

##### README for additional insights
- Describes two operational modes: self-hosted (pure plugin) vs. cloud (needs cron-job.org API).
- Workflow:
1. User adds an “endpoint” via Dify UI.
2. Plugin registers a cron job (via cron-job.org in cloud mode).
3. cron-job.org calls back the plugin’s entry endpoint.
4. Plugin invokes the Dify Workflow or Chatflow API to run the user’s logic.
- No database; state is managed by cron-job.org for cloud or in-memory for self-hosted.

a. Main components
- Dify Core / Plugin Host
- Cron Plugin Service
– HTTP endpoints: /cron (start/stop), /entry (webhook)
– Scheduling logic (cron syntax parsing)
- External Scheduler Service (cron-job.org) [cloud only]
- Dify Workflow Engine API
- User Interface (Dify Admin UI)

b. Relationships and interactions
1. User configures a new Cron endpoint in Dify Admin UI →
plugin Host reads manifest.yaml → loads cron endpoint definitions.
2. Plugin receives “start” request → parses cron string →
if cloud: calls cron-job.org API to register schedule
if self-hosted: spins up an internal timer.
3. At scheduled time, external service (or internal timer) makes HTTP POST to plugin’s /entry endpoint.
4. Plugin’s entry handler receives callback → sets `is_cron = yes` → calls Dify Workflow Engine API to trigger the user’s workflow.
5. Workflow Engine executes the workflow; responses flow back via plugin.

c. Architectural patterns and design principles
- Event-driven / webhook-based scheduling
- Minimal internal state (stateless plugin, relies on external scheduler)
- Clear separation of concerns:
- Endpoint definitions (YAML) vs. handler logic (Python)
- Plugin host vs. external scheduler vs. workflow engine
- Extensibility: adding new endpoints just means adding new .py + .yaml pairs under endpoints/

d. Key technologies
- Python (cron.py, entry.py)
- Dify plugin framework (manifest.yaml, group definitions)
- cron-job.org REST API (cloud)
- Standard cron format libraries or custom parser
- Dify Workflow Engine REST API

##### Essential elements to capture
- Labels: name each endpoint (/cron, /entry) and each service.
- Annotations: note “cloud mode” vs. “self-hosted” paths.
- Plugin’s two handlers together under a single Plugin Service boundary.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User & UI"
        User["User"]:::external
        AdminUI["Dify Admin UI"]:::external
    end

    subgraph "Plugin Host"
        Main["main.py"]:::internal
        Manifest["manifest.yaml"]:::internal
    end

    subgraph "Cron Plugin Service"
        CronEP["/cron Endpoint"]:::internal
        EntryEP["/entry Endpoint"]:::internal
        Scheduler["Internal Scheduler (Self-Hosted)"]:::internal
    end

    ExternalCron["cron-job.org (Cloud Scheduler)"]:::external
    WorkflowAPI["Dify Workflow Engine API"]:::internal

    User -->|"configures endpoint"| AdminUI
    AdminUI -->|"loads definitions"| Main
    Main --> Manifest
    Main --> CronEP
    Main --> EntryEP
    CronEP -->|"start/stop (cloud mode)"| ExternalCron
    CronEP -->|"start/stop (self-hosted)"| Scheduler
    ExternalCron -->|"callback (HTTP POST)"| EntryEP
    Scheduler -->|"internal trigger"| EntryEP
    EntryEP -->|"trigger workflow"| WorkflowAPI

    click Main "https://github.com/yt-koike/dify-cron/blob/main/main.py"
    click Manifest "https://github.com/yt-koike/dify-cron/blob/main/manifest.yaml"
    click CronEP "https://github.com/yt-koike/dify-cron/blob/main/endpoints/cron.py"
    click CronEP "https://github.com/yt-koike/dify-cron/blob/main/endpoints/cron.yaml"
    click EntryEP "https://github.com/yt-koike/dify-cron/blob/main/endpoints/entry.py"
    click EntryEP "https://github.com/yt-koike/dify-cron/blob/main/endpoints/entry.yaml"
    click Scheduler "https://github.com/yt-koike/dify-cron/blob/main/group/cron.yaml"
    click WorkflowAPI "https://github.com/yt-koike/dify-cron/blob/main/tests/test_cron.py"
    click User "https://github.com/yt-koike/dify-cron/blob/main/requirements.txt"
    click AdminUI "https://github.com/yt-koike/dify-cron/blob/main/.env.example"
    click Manifest "https://github.com/yt-koike/dify-cron/blob/main/ruff.toml"
    click Main "https://github.com/yt-koike/dify-cron/blob/main/.github/workflows/plugin-publish.yml"
    click AdminUI "https://github.com/yt-koike/dify-cron/blob/main/README.md"
    click AdminUI "https://github.com/yt-koike/dify-cron/blob/main/GUIDE.md"
    click AdminUI "https://github.com/yt-koike/dify-cron/blob/main/PRIVACY.md"
    click AdminUI "https://github.com/yt-koike/dify-cron/blob/main/OWNERSHIP.md"

    classDef internal fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px

    linkStyle 0 stroke:#0f0,stroke-width:2px
    linkStyle 1 stroke:#0f0,stroke-width:2px
    linkStyle 2 stroke:#0f0,stroke-width:2px
    linkStyle 3 stroke:#0f0,stroke-width:2px
    linkStyle 4 stroke:#0f0,stroke-width:2px
    linkStyle 5 stroke:#0f0,stroke-width:2px
    linkStyle 6 stroke:#0f0,stroke-width:2px
    linkStyle 7 stroke:#f00,stroke-width:2px
    linkStyle 8 stroke:#f00,stroke-width:2px
    linkStyle 9 stroke:#f00,stroke-width:2px
```
