# dagu-org/dagu architecture

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

- Interactive diagram: https://gitdiagram.com/dagu-org/dagu
- Repository: https://github.com/dagu-org/dagu

## Overview

##### Main Components
- Backend Engine: Represent the core “engine” (the binary started from cmd/main.go) which includes several subcomponents:
- Workflow Parser & Executor: The modules under internal/digraph and internal/config that read DAG YAML files, build dependency graphs, and manage execution flows.
- Task Executors: Components in internal/digraph/executor (for Docker, SSH, HTTP, jq, mail, etc.) that provide different execution mechanisms.
- Scheduler: The scheduling logic (see internal/scheduler and scheduler jobs) that determines when tasks should run based on cron schedules.
- Persistence & Logging: File-based storage components (internal/persistence/jsondb, internal/persistence/local, internal/logger) managing state, logs, and output.
- Agent & Command Interface: Modules for handling CLI commands (cmd and internal/cmd) and interactions with the agent (internal/agent) that monitors workflow state.
- Web UI: The frontend served from the “ui” directory, built with TypeScript/React. It handles rendering of workflows, live updates of logs/status (using routes defined in internal/frontend/server and assets under ui/src).
- API Layer: The REST API (generated in internal/frontend/gen/restapi) provides endpoints that the UI consumes to show real-time status, logs, and configuration details.
- Supporting Tools & Configuration: Tools such as the Dockerfile, docker-compose.yaml, and various configuration files support deployment and containerization, while docs and examples help users understand the system.

##### Relationships and Interactions
- The Web UI communicates with the backend’s API endpoints to fetch real-time DAG statuses, execution logs, and to submit new workflow requests.
- When a user initiates a DAG via the UI or CLI, the engine reads the YAML configuration, builds the DAG (using components in internal/digraph), and triggers the appropriate executors.
- The Scheduler component periodically checks for scheduled workflows and triggers execution.
- Outputs from one step are passed into subsequent tasks via a well-defined “data passing” mechanism (note the use of output variables).
- Notification and logging components (mailer, logger) record execution details and may interact externally (e.g., sending email notifications or HTTP requests).

##### Architectural Patterns & Design Principles
- Monolithic Single Binary: Despite having distinct logical modules, everything is compiled into one executable without an external dependency, contributing to a “local-first” design.
- Declarative Configuration: The system is built around YAML-defined workflows, making the execution flow clear and maintainable.
- Modular Design: Though in one binary, the code is well separated into packages (scheduler, executor, persistence, logger), each responsible for a specific function.

##### Relevant Technologies and Frameworks
- Backend is implemented in Go. Note the use of Go’s package structure (cmd, internal packages) and tools like Goreleaser for builds.
- The UI is built with React (TypeScript/TSX files) and bundled with Webpack.
- Configuration parsers and workflow engines (YAML processing, JSON databases) are integral parts of how workflows are executed.
- Tools such as Docker and docker-compose are also featured for containerized deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User/CLI"]:::external
    UI["React Web UI"]:::frontend
    API["API Server"]:::backend
    BE["Backend Engine"]:::backend
    WPE["Workflow Parser & Executor"]:::backend
    TE["Task Executors"]:::backend
    SCH["Scheduler"]:::scheduler
    CLI_C["CLI Commands"]:::agent
    AM["Agent Monitor"]:::agent
    
    subgraph "Persistence & Logging"
        JSON["JSONDB"]:::persistence
        LS["Local Storage"]:::persistence
        LOG["Logger"]:::persistence
    end
    
    DT["Deployment Tools<br/>(Docker & Config)"]:::backend

    %% Relationships
    U --> CLI_C
    U --> UI
    UI -->|"calls"| API
    API -->|"forwards to"| BE
    BE -->|"initializes"| WPE
    BE --> SCH
    BE --> TE
    BE --> CLI_C
    BE --> AM
    API -->|"invokes"| WPE
    CLI_C -->|"triggers"| WPE
    SCH -->|"schedules"| WPE
    SCH --> TE
    SCH --> AM
    WPE --> TE
    WPE -->|"logs to"| JSON
    WPE --> LS
    WPE --> LOG
    TE -->|"stores logs in"| JSON
    TE --> LS
    TE --> LOG
    AM -->|"reports to"| JSON
    AM --> LS
    AM --> LOG
    BE --> DT

    %% Styles
    classDef external fill:#F5DEB3,stroke:#000,stroke-width:2px;
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef scheduler fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef persistence fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef agent fill:#DDA0DD,stroke:#000,stroke-width:2px;

    %% Click Events
    click BE "https://github.com/dagu-org/dagu/blob/main/cmd/main.go"
    click WPE "https://github.com/dagu-org/dagu/tree/main/internal/digraph and internal/config"
    click TE "https://github.com/dagu-org/dagu/tree/main/internal/digraph/executor"
    click SCH "https://github.com/dagu-org/dagu/tree/main/internal/scheduler and internal/digraph/scheduler"
    click JSON "https://github.com/dagu-org/dagu/tree/main/internal/persistence/jsondb"
    click LS "https://github.com/dagu-org/dagu/tree/main/internal/persistence/local"
    click LOG "https://github.com/dagu-org/dagu/tree/main/internal/logger"
    click CLI_C "https://github.com/dagu-org/dagu/tree/main/cmd"
    click AM "https://github.com/dagu-org/dagu/tree/main/internal/agent"
    click API "https://github.com/dagu-org/dagu/tree/main/internal/frontend/gen/restapi"
    click UI "https://github.com/dagu-org/dagu/tree/main/ui"
```
