How distribworks/dkron works
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