# kimdre/doco-cd architecture

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

- Interactive diagram: https://gitdiagram.com/kimdre/doco-cd
- Repository: https://github.com/kimdre/doco-cd

## Overview

Doco-CD is a GitOps continuous-delivery service for Docker Compose projects and Swarm stacks. Its primary workflow begins with a poll or provider webhook, prepares a Git or OCI source, then reconciles and deploys the resulting configuration to Docker. The repository also exposes REST and MCP automation, scheduled jobs, sync windows, secret handling, notifications, metrics, and self-update support. Relationships beyond the excerpted calls are limited to capabilities and connections explicitly documented in the README; unsampled implementation details are not asserted.

Main entry points: [`internal/controlplane`](https://github.com/kimdre/doco-cd/tree/main/internal/controlplane) (Run control), [`internal/docker`](https://github.com/kimdre/doco-cd/tree/main/internal/docker) (Docker deployment), [`cmd/doco-cd/handler_webhook.go`](https://github.com/kimdre/doco-cd/blob/main/cmd/doco-cd/handler_webhook.go) (Webhooks), [`internal/source`](https://github.com/kimdre/doco-cd/tree/main/internal/source) (Source preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Triggers and APIs"]
  node_poll["Polling<br/>[handler_poll.go]"]
  node_webhook["Webhooks<br/>[handler_webhook.go]"]
  node_rest["REST API"]
  node_mcp["MCP server"]
end

subgraph group_delivery["Delivery workflow"]
  node_control["Run control"]
  node_source["Source preparation"]
  node_git["Git operations"]
  node_oci["OCI artifacts<br/>[service.go]"]
  node_config["Deploy configuration<br/>[deploy.go]"]
  node_stages["Deployment stages"]
  node_reconcile["Reconciliation<br/>[manager.go]"]
end

subgraph group_runtime["Docker runtime"]
  node_docker["Docker deployment"]
  node_swarm["Swarm stacks<br/>[service.go]"]
end

subgraph group_operations["Operations and integrations"]
  node_scheduler["Job scheduling"]
  node_sync["Sync windows<br/>[syncwindow.go]"]
  node_secrets["Secrets and encryption"]
  node_notifications["Notifications<br/>[notification.go]"]
  node_metrics["Prometheus metrics"]
  node_selfupdate["Self update<br/>[journal.go]"]
end

node_provider(("Git provider"))
node_dockerhost(("Docker host"))

node_provider -->|"sends events"| node_webhook
node_poll -->|"starts poll run"| node_control
node_webhook -->|"executes run"| node_control
node_poll -->|"triggers deployment"| node_control
node_webhook -->|"triggers deployment"| node_control
node_control -.->|"prepares source"| node_source
node_source -->|"fetches repository"| node_git
node_source -->|"resolves artifact"| node_oci
node_source -->|"loads configuration"| node_config
node_control -.->|"runs stages"| node_stages
node_stages -.->|"requests deployment"| node_reconcile
node_reconcile -->|"reconciles services"| node_docker
node_docker -->|"deploys projects"| node_dockerhost
node_docker -->|"supports stacks"| node_swarm
node_rest -.->|"manages runs"| node_control
node_mcp -->|"automates runs"| node_control
node_scheduler -->|"runs scheduled jobs"| node_docker
node_control -->|"honors windows"| node_sync
node_stages -->|"resolves secrets"| node_secrets
node_webhook -->|"sends failure notice"| node_notifications
node_scheduler -.->|"notifies failures"| node_notifications
node_docker -->|"reports metrics"| node_metrics
node_stages -->|"checks update state"| node_selfupdate

click node_poll "https://github.com/kimdre/doco-cd/blob/main/cmd/doco-cd/handler_poll.go"
click node_webhook "https://github.com/kimdre/doco-cd/blob/main/cmd/doco-cd/handler_webhook.go"
click node_rest "https://github.com/kimdre/doco-cd/tree/main/internal/api"
click node_mcp "https://github.com/kimdre/doco-cd/tree/main/internal/mcp"
click node_control "https://github.com/kimdre/doco-cd/tree/main/internal/controlplane"
click node_source "https://github.com/kimdre/doco-cd/tree/main/internal/source"
click node_git "https://github.com/kimdre/doco-cd/tree/main/internal/git"
click node_oci "https://github.com/kimdre/doco-cd/blob/main/internal/source/oci/service.go"
click node_config "https://github.com/kimdre/doco-cd/blob/main/internal/config/deploy/deploy.go"
click node_stages "https://github.com/kimdre/doco-cd/tree/main/internal/stages"
click node_reconcile "https://github.com/kimdre/doco-cd/blob/main/internal/reconciliation/manager.go"
click node_docker "https://github.com/kimdre/doco-cd/tree/main/internal/docker"
click node_swarm "https://github.com/kimdre/doco-cd/blob/main/internal/docker/swarm/service.go"
click node_scheduler "https://github.com/kimdre/doco-cd/tree/main/internal/scheduler"
click node_sync "https://github.com/kimdre/doco-cd/blob/main/internal/syncwindow/syncwindow.go"
click node_secrets "https://github.com/kimdre/doco-cd/tree/main/internal/encryption"
click node_notifications "https://github.com/kimdre/doco-cd/blob/main/internal/notification/notification.go"
click node_metrics "https://github.com/kimdre/doco-cd/tree/main/internal/prometheus"
click node_selfupdate "https://github.com/kimdre/doco-cd/blob/main/internal/selfupdate/journal.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_poll,node_webhook,node_rest,node_mcp toneBlue
class node_control,node_source,node_git,node_oci,node_config,node_stages,node_reconcile toneAmber
class node_docker,node_swarm toneMint
class node_scheduler,node_sync,node_secrets,node_notifications,node_metrics,node_selfupdate toneRose
class node_provider,node_dockerhost toneIndigo
```

## Components

### Triggers and APIs

- [Polling](https://github.com/kimdre/doco-cd/blob/main/cmd/doco-cd/handler_poll.go): `cmd/doco-cd/handler_poll.go`
- [Webhooks](https://github.com/kimdre/doco-cd/blob/main/cmd/doco-cd/handler_webhook.go): `cmd/doco-cd/handler_webhook.go`
- [REST API](https://github.com/kimdre/doco-cd/tree/main/internal/api): `internal/api`
- [MCP server](https://github.com/kimdre/doco-cd/tree/main/internal/mcp): `internal/mcp`

### Delivery workflow

- [Run control](https://github.com/kimdre/doco-cd/tree/main/internal/controlplane): `internal/controlplane`
- [Source preparation](https://github.com/kimdre/doco-cd/tree/main/internal/source): `internal/source`
- [Git operations](https://github.com/kimdre/doco-cd/tree/main/internal/git): `internal/git`
- [OCI artifacts](https://github.com/kimdre/doco-cd/blob/main/internal/source/oci/service.go): `internal/source/oci/service.go`
- [Deploy configuration](https://github.com/kimdre/doco-cd/blob/main/internal/config/deploy/deploy.go): `internal/config/deploy/deploy.go`
- [Deployment stages](https://github.com/kimdre/doco-cd/tree/main/internal/stages): `internal/stages`
- [Reconciliation](https://github.com/kimdre/doco-cd/blob/main/internal/reconciliation/manager.go): `internal/reconciliation/manager.go`

### Docker runtime

- [Docker deployment](https://github.com/kimdre/doco-cd/tree/main/internal/docker): `internal/docker`
- [Swarm stacks](https://github.com/kimdre/doco-cd/blob/main/internal/docker/swarm/service.go): `internal/docker/swarm/service.go`

### Operations and integrations

- [Job scheduling](https://github.com/kimdre/doco-cd/tree/main/internal/scheduler): `internal/scheduler`
- [Sync windows](https://github.com/kimdre/doco-cd/blob/main/internal/syncwindow/syncwindow.go): `internal/syncwindow/syncwindow.go`
- [Secrets and encryption](https://github.com/kimdre/doco-cd/tree/main/internal/encryption): `internal/encryption`
- [Notifications](https://github.com/kimdre/doco-cd/blob/main/internal/notification/notification.go): `internal/notification/notification.go`
- [Prometheus metrics](https://github.com/kimdre/doco-cd/tree/main/internal/prometheus): `internal/prometheus`
- [Self update](https://github.com/kimdre/doco-cd/blob/main/internal/selfupdate/journal.go): `internal/selfupdate/journal.go`

### Other components

- **Git provider**
- **Docker host**

## Connections

- Git provider → Webhooks: sends events (evidence: `README.md`)
- Polling → Run control: starts poll run (evidence: `cmd/doco-cd/handler_poll.go`)
- Webhooks → Run control: executes run (evidence: `cmd/doco-cd/handler_webhook.go`)
- Polling → Run control: triggers deployment (evidence: `README.md`)
- Webhooks → Run control: triggers deployment (evidence: `README.md`)
- Run control → Source preparation: prepares source
- Source preparation → Git operations: fetches repository (evidence: `internal/source/prepare.go`)
- Source preparation → OCI artifacts: resolves artifact (evidence: `internal/source/prepare.go`)
- Source preparation → Deploy configuration: loads configuration (evidence: `internal/config/deploy/deploy.go`)
- Run control → Deployment stages: runs stages
- Deployment stages → Reconciliation: requests deployment (evidence: `internal/reconciliation/manager.go`)
- Reconciliation → Docker deployment: reconciles services (evidence: `internal/reconciliation/manager.go`)
- Docker deployment → Docker host: deploys projects (evidence: `README.md`)
- Docker deployment → Swarm stacks: supports stacks (evidence: `README.md`)
- REST API → Run control: manages runs (evidence: `internal/api/handler.go`)
- MCP server → Run control: automates runs (evidence: `internal/mcp/handler.go`)
- Job scheduling → Docker deployment: runs scheduled jobs (evidence: `internal/scheduler/scheduler_manager.go`)
- Run control → Sync windows: honors windows
- Deployment stages → Secrets and encryption: resolves secrets (evidence: `internal/stages/stage_2_pre-deploy.go`)
- Webhooks → Notifications: sends failure notice (evidence: `cmd/doco-cd/handler_webhook.go`)
- Job scheduling → Notifications: notifies failures
- Docker deployment → Prometheus metrics: reports metrics (evidence: `internal/prometheus/collectors.go`)
- Deployment stages → Self update: checks update state (evidence: `internal/stages/stage_2_pre-deploy.go`)
