# distribworks/dkron architecture

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

- Interactive diagram: https://gitdiagram.com/distribworks/dkron
- Repository: https://github.com/distribworks/dkron

## Overview

##### Project type and purpose
- Dkron is a distributed, fault-tolerant cron scheduling system written in Go, comprising a cluster of server nodes (Raft + Serf), agent processes, a REST/GRPC API, a React-based UI, built-in and pluggable executors/processors, CLI tools, and optional external services (Kafka, NATS, GCP PubSub, RabbitMQ, HTTP, shell). It targets cloud-native environments and emphasizes reliability, scalability, and ease of use.

##### File structure
- Top-level directories:
- cmd/ – CLI commands (dkron server, agent, keygen, shell, plugins)
- dkron/ – core server logic (Raft consensus, Serf gossip, scheduling, execution, storage, tracing, API handlers)
- client/ – Go client library for API consumption
- ui/ – React Admin single-page application for the dashboard
- builtin/ – baked-in executors and processors (gRPC, HTTP, Kafka, NATS, GCP PubSub, RabbitMQ, file, syslog, etc.)
- plugin/ – plugin framework for custom executors/processors or HTTP extensions
- proto/, types/ – Protobuf definitions and generated Go types for internal GRPC contracts
- Dockerfiles, docker-compose, Makefile, goreleaser – containerization and CI/CD tooling
- docs/, website/ – user documentation and marketing site

##### README insights
- Confirms cluster mode via Docker Compose, UI served at /ui, API docs available, scaling instructions, development workflow for both Go backend and React UI, and that Serf is used for membership/gossip while Raft ensures leader election and state replication.

- Browser/UI (React Admin)
- API Gateway / Load Balancer (optional reverse proxy)
- Dkron Server Cluster (multiple Go server instances)
- Cluster internals:
- Serf gossip mesh (peer discovery & failure detection)
- Raft consensus group (leader election & replicated state machine)
- Job Scheduler & Dispatcher
- Agent Workers (if run separately)
- Executors (built-in & plugin-based)
- Processors (built-in & plugin-based)
- Storage Backend (embedded BoltDB or external KV store if configured)
- External systems: Kafka, NATS, GCP PubSub, RabbitMQ, HTTP endpoints, Shell environment
- CLI & Client SDKs (Go client, scripts)
- Observability: Metrics (Prometheus), Tracing (OpenTelemetry), Logs

b. Relationships and interactions
- UI ↔ HTTP/JSON API on server cluster
- CLI/SDK ↔ gRPC/HTTP API
- Server instances ↔ Serf (UDP gossip) for membership
- Server leader ↔ Raft followers for state replication
- Scheduler on leader pushes job events to agents via gRPC or Serf event hooks
- Agents invoke executors, collect exit codes, then call processors
- Processors write logs/metrics, possibly forward to external sinks
- Storage writes go through the consensus layer to ensure consistency

c. Architectural patterns and design principles
- Master/Worker: leader schedules, workers execute
- Event-driven: job events flow via internal message bus (Serf events or gRPC streams)
- Pluggable modules: executors & processors via plugin framework (Go interfaces + gRPC/protobuf)
- Single binary with role switch (agent vs. server)
- Infrastructure as code: Docker, Compose, Ansible scripts, Goreleaser pipelines

d. Key technologies, frameworks, libraries
- Go for core services
- Hashicorp Serf for gossip
- Hashicorp Raft for consensus
- Protobuf + gRPC for plugin & internal RPC
- React Admin + TypeScript for UI
- BoltDB (default) / optional external KV store
- Prometheus metrics, OpenTelemetry tracing

##### Be exhaustive but organized
- Cluster internals (Serf vs. Raft)
- Execution pipeline (scheduler → agent → executor → processor)
- Plugin extension points
- Build/deploy artifacts: Docker images, Compose stacks, CI/CD pipeline

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI & CLI
    subgraph "UI & CLI Layer"
        direction TB
        Browser["Browser (React UI)"]:::frontend
        CLI["CLI Commands"]:::frontend
    end
    click Browser "https://github.com/distribworks/dkron/tree/main/ui/"
    click CLI "https://github.com/distribworks/dkron/tree/main/cmd/"

    %% Cluster Core
    subgraph "Cluster Core"
        direction TB
        APIGateway["API Gateway / Load Balancer"]:::core
        APIHTTP["HTTP/JSON & gRPC API"]:::core
        Scheduler["Job Scheduler & Dispatcher"]:::core
        Servers["Dkron Server Cluster"]:::core
        Serf["Serf Gossip (UDP)"]:::core
        Raft["Raft Consensus"]:::core
        Storage["Storage Backend (BoltDB/KV)"]:::storageObs
        Metrics["Metrics (Prometheus)"]:::storageObs
        Tracing["Tracing (OpenTelemetry)"]:::storageObs
    end
    click APIGateway "https://github.com/distribworks/dkron/blob/main/dkron/api.go"
    click APIHTTP "https://github.com/distribworks/dkron/blob/main/dkron/grpc.go"
    click Scheduler "https://github.com/distribworks/dkron/blob/main/dkron/scheduler.go"
    click Servers "https://github.com/distribworks/dkron/tree/main/dkron/"
    click Serf "https://github.com/distribworks/dkron/blob/main/dkron/serf.go"
    click Raft "https://github.com/distribworks/dkron/blob/main/dkron/fsm.go"
    click Storage "https://github.com/distribworks/dkron/blob/main/dkron/storage.go"
    click Metrics "https://github.com/distribworks/dkron/blob/main/dkron/metrics.go"
    click Tracing "https://github.com/distribworks/dkron/blob/main/dkron/tracing.go"

    %% Agents & Execution
    subgraph "Agents & Execution"
        direction TB
        Agents["Agent Processes"]:::agentExec
        Executors["Built-in Executors"]:::agentExec
        Processors["Built-in Processors"]:::agentExec
    end
    click Agents "https://github.com/distribworks/dkron/blob/main/dkron/agent.go"
    click Executors "https://github.com/distribworks/dkron/tree/main/builtin/bins/"
    click Processors "https://github.com/distribworks/dkron/tree/main/builtin/bins/"

    %% Plugin Framework
    subgraph "Plugin Framework"
        direction TB
        Plugins["Plugin Framework"]:::agentExec
    end
    click Plugins "https://github.com/distribworks/dkron/tree/main/plugin/"

    %% External Systems
    subgraph "External Systems"
        direction TB
        Kafka["Kafka"]:::external
        NATS["NATS"]:::external
        GCPPubSub["GCP PubSub"]:::external
        RabbitMQ["RabbitMQ"]:::external
        HTTP["HTTP Endpoints"]:::external
        ShellExt["Shell Environment"]:::external
    end

    %% Client SDK & Docs
    subgraph "Client & Documentation"
        direction TB
        GoClient["Go Client SDK"]:::frontend
        Documentation["User Docs & Marketing Site"]:::frontend
    end
    click GoClient "https://github.com/distribworks/dkron/tree/main/client/"
    click Documentation "https://github.com/distribworks/dkron/tree/main/docs/"
    click Documentation "https://github.com/distribworks/dkron/tree/main/website/"

    %% Connections
    Browser -->|HTTP| APIHTTP
    CLI -->|HTTP/gRPC| APIHTTP
    GoClient -->|gRPC| APIHTTP
    APIGateway -->|forwards| APIHTTP
    APIHTTP -->|invokes| Scheduler
    Scheduler -->|schedules jobs to| Agents
    Agents -->|invoke| Executors
    Agents -->|invoke| Plugins
    Executors -->|produce events| Processors
    Processors -->|forward to| Kafka
    Processors -->|forward to| NATS
    Processors -->|forward to| GCPPubSub
    Processors -->|forward to| RabbitMQ
    Processors -->|call| HTTP
    Processors -->|log to| ShellExt
    Plugins -->|interact with| Kafka
    Plugins -->|interact with| ShellExt
    Servers -->|gossip| Serf
    Servers -->|replicate state| Raft
    Raft -->|writes| Storage
    Storage -->|read/write via| Raft
    APIHTTP -->|exposes metrics| Metrics
    APIHTTP -->|exposes tracing| Tracing

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef agentExec fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef storageObs fill:#D3D3D3,stroke:#333,stroke-width:1px
```
