# nicholas-fedor/watchtower architecture

> Architecture diagram of the GitHub repository nicholas-fedor/watchtower, 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/nicholas-fedor/watchtower
- Repository: https://github.com/nicholas-fedor/watchtower

## Overview

Watchtower automates Docker image updates: it discovers watched containers, checks registry digests or Git revisions, then replaces stale containers while preserving deployment settings. The CLI can run scans on a schedule or once; an HTTP API also exposes update, check, health, metrics, history, container, image, configuration, and event capabilities. Configuration and flags feed the runtime, while progress, metrics, and notifications report outcomes. Edges are limited to relationships visible in excerpts, the source index, or README; some API internals are documented but not sampled.

Main entry points: [`internal/actions/update.go`](https://github.com/nicholas-fedor/watchtower/blob/main/internal/actions/update.go) (Update action), [`cmd/root.go`](https://github.com/nicholas-fedor/watchtower/blob/main/cmd/root.go) (CLI orchestration), [`internal/api/routes/routes.go`](https://github.com/nicholas-fedor/watchtower/blob/main/internal/api/routes/routes.go) (API routing), [`pkg/registry/age.go`](https://github.com/nicholas-fedor/watchtower/blob/main/pkg/registry/age.go) (Registry checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_main["Process entry<br/>[main.go]"]
  node_cli["CLI orchestration<br/>[root.go]"]
  node_schedule["Scheduled scans<br/>[scheduling.go]"]
end

subgraph group_update["Update workflow"]
  node_update_action["Update action<br/>[update.go]"]
  node_container["Docker operations<br/>[client.go]"]
  node_lifecycle["Lifecycle hooks<br/>[lifecycle.go]"]
  node_compose["Compose apply<br/>[client.go]"]
  node_sorter["Dependency ordering<br/>[dependency.go]"]
  node_filters["Container filters<br/>[filters.go]"]
end

subgraph group_sources["Image and Git checks"]
  node_registry["Registry checks<br/>[age.go]"]
  node_auth["Registry authentication<br/>[auth.go]"]
  node_release["Digest resolution<br/>[resolver.go]"]
  node_git["Git revision checks<br/>[client.go]"]
end

subgraph group_api["HTTP API"]
  node_api_routes["API routing<br/>[routes.go]"]
  node_api_update["Update endpoint<br/>[handler.go]"]
  node_api_check["Check endpoint<br/>[handler.go]"]
  node_api_other["API capabilities"]
end

subgraph group_support["Configuration and reporting"]
  node_config["Resolved configuration"]
  node_flags["Flags and environment<br/>[flags.go]"]
  node_metrics["Metrics<br/>[metrics.go]"]
  node_session["Scan reporting<br/>[report.go]"]
  node_notifications["Notifications<br/>[shoutrrr.go]"]
end

node_operator(("Operator"))
node_docker["Docker Engine"]
node_image_registry["Image registry"]
node_git_host["Git host"]

node_operator -->|"starts"| node_main
node_main -->|"delegates to"| node_cli
node_cli -->|"resolves"| node_config
node_flags -->|"configures"| node_config
node_cli -->|"runs updates"| node_update_action
node_cli -->|"starts schedule"| node_schedule
node_schedule -->|"runs scans"| node_update_action
node_update_action -->|"filters containers"| node_filters
node_update_action -->|"orders dependencies"| node_sorter
node_update_action -->|"updates containers"| node_container
node_update_action -->|"runs hooks"| node_lifecycle
node_update_action -->|"uses Compose"| node_compose
node_update_action -->|"checks revisions"| node_git
node_update_action -->|"resolves releases"| node_release
node_release -->|"checks digests"| node_registry
node_registry -->|"authenticates"| node_auth
node_registry -.->|"queries"| node_image_registry
node_git -->|"resolves refs"| node_git_host
node_update_action -->|"records progress"| node_session
node_cli -.->|"registers API"| node_api_routes
node_api_routes -.->|"routes requests"| node_api_update
node_api_routes -.->|"routes requests"| node_api_check
node_api_routes -->|"mounts endpoints"| node_api_other
node_api_update -->|"invokes callback"| node_update_action
node_api_check -->|"sends results"| node_notifications
node_api_check -.->|"checks containers"| node_session
node_update_action -->|"updates metrics"| node_metrics
node_session -.->|"reports results"| node_notifications
node_container -->|"controls containers"| node_docker

click node_main "https://github.com/nicholas-fedor/watchtower/blob/main/main.go"
click node_cli "https://github.com/nicholas-fedor/watchtower/blob/main/cmd/root.go"
click node_schedule "https://github.com/nicholas-fedor/watchtower/blob/main/internal/scheduling/scheduling.go"
click node_config "https://github.com/nicholas-fedor/watchtower/tree/main/internal/config"
click node_flags "https://github.com/nicholas-fedor/watchtower/blob/main/internal/flags/flags.go"
click node_update_action "https://github.com/nicholas-fedor/watchtower/blob/main/internal/actions/update.go"
click node_container "https://github.com/nicholas-fedor/watchtower/blob/main/pkg/container/client.go"
click node_lifecycle "https://github.com/nicholas-fedor/watchtower/blob/main/pkg/lifecycle/lifecycle.go"
click node_compose "https://github.com/nicholas-fedor/watchtower/blob/main/internal/compose/client.go"
click node_sorter "https://github.com/nicholas-fedor/watchtower/blob/main/pkg/sorter/dependency.go"
click node_filters "https://github.com/nicholas-fedor/watchtower/blob/main/pkg/filters/filters.go"
click node_registry "https://github.com/nicholas-fedor/watchtower/blob/main/pkg/registry/age.go"
click node_auth "https://github.com/nicholas-fedor/watchtower/blob/main/pkg/registry/auth/auth.go"
click node_release "https://github.com/nicholas-fedor/watchtower/blob/main/internal/release/resolver.go"
click node_git "https://github.com/nicholas-fedor/watchtower/blob/main/internal/git/client.go"
click node_api_routes "https://github.com/nicholas-fedor/watchtower/blob/main/internal/api/routes/routes.go"
click node_api_update "https://github.com/nicholas-fedor/watchtower/blob/main/internal/api/handlers/update/handler.go"
click node_api_check "https://github.com/nicholas-fedor/watchtower/blob/main/internal/api/handlers/check/handler.go"
click node_api_other "https://github.com/nicholas-fedor/watchtower/tree/main/internal/api/handlers"
click node_metrics "https://github.com/nicholas-fedor/watchtower/blob/main/internal/metrics/metrics.go"
click node_session "https://github.com/nicholas-fedor/watchtower/blob/main/pkg/session/report.go"
click node_notifications "https://github.com/nicholas-fedor/watchtower/blob/main/pkg/notifications/shoutrrr.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_main,node_cli,node_schedule toneBlue
class node_update_action,node_container,node_lifecycle,node_compose,node_sorter,node_filters toneAmber
class node_registry,node_auth,node_release,node_git toneMint
class node_api_routes,node_api_update,node_api_check,node_api_other toneRose
class node_config,node_flags,node_metrics,node_session,node_notifications,node_operator,node_docker,node_image_registry,node_git_host toneIndigo
```

## Components

### Runtime orchestration

- [Process entry](https://github.com/nicholas-fedor/watchtower/blob/main/main.go): `main.go`
- [CLI orchestration](https://github.com/nicholas-fedor/watchtower/blob/main/cmd/root.go): `cmd/root.go`
- [Scheduled scans](https://github.com/nicholas-fedor/watchtower/blob/main/internal/scheduling/scheduling.go): `internal/scheduling/scheduling.go`

### Update workflow

- [Update action](https://github.com/nicholas-fedor/watchtower/blob/main/internal/actions/update.go): `internal/actions/update.go`
- [Docker operations](https://github.com/nicholas-fedor/watchtower/blob/main/pkg/container/client.go): `pkg/container/client.go`
- [Lifecycle hooks](https://github.com/nicholas-fedor/watchtower/blob/main/pkg/lifecycle/lifecycle.go): `pkg/lifecycle/lifecycle.go`
- [Compose apply](https://github.com/nicholas-fedor/watchtower/blob/main/internal/compose/client.go): `internal/compose/client.go`
- [Dependency ordering](https://github.com/nicholas-fedor/watchtower/blob/main/pkg/sorter/dependency.go): `pkg/sorter/dependency.go`
- [Container filters](https://github.com/nicholas-fedor/watchtower/blob/main/pkg/filters/filters.go): `pkg/filters/filters.go`

### Image and Git checks

- [Registry checks](https://github.com/nicholas-fedor/watchtower/blob/main/pkg/registry/age.go): `pkg/registry/age.go`
- [Registry authentication](https://github.com/nicholas-fedor/watchtower/blob/main/pkg/registry/auth/auth.go): `pkg/registry/auth/auth.go`
- [Digest resolution](https://github.com/nicholas-fedor/watchtower/blob/main/internal/release/resolver.go): `internal/release/resolver.go`
- [Git revision checks](https://github.com/nicholas-fedor/watchtower/blob/main/internal/git/client.go): `internal/git/client.go`

### HTTP API

- [API routing](https://github.com/nicholas-fedor/watchtower/blob/main/internal/api/routes/routes.go): `internal/api/routes/routes.go`
- [Update endpoint](https://github.com/nicholas-fedor/watchtower/blob/main/internal/api/handlers/update/handler.go): `internal/api/handlers/update/handler.go`
- [Check endpoint](https://github.com/nicholas-fedor/watchtower/blob/main/internal/api/handlers/check/handler.go): `internal/api/handlers/check/handler.go`
- [API capabilities](https://github.com/nicholas-fedor/watchtower/tree/main/internal/api/handlers): `internal/api/handlers`

### Configuration and reporting

- [Resolved configuration](https://github.com/nicholas-fedor/watchtower/tree/main/internal/config): `internal/config`
- [Flags and environment](https://github.com/nicholas-fedor/watchtower/blob/main/internal/flags/flags.go): `internal/flags/flags.go`
- [Metrics](https://github.com/nicholas-fedor/watchtower/blob/main/internal/metrics/metrics.go): `internal/metrics/metrics.go`
- [Scan reporting](https://github.com/nicholas-fedor/watchtower/blob/main/pkg/session/report.go): `pkg/session/report.go`
- [Notifications](https://github.com/nicholas-fedor/watchtower/blob/main/pkg/notifications/shoutrrr.go): `pkg/notifications/shoutrrr.go`

### Other components

- **Operator**
- **Docker Engine**
- **Image registry**
- **Git host**

## Connections

- Operator → Process entry: starts (evidence: `README.md`)
- Process entry → CLI orchestration: delegates to (evidence: `main.go`)
- CLI orchestration → Resolved configuration: resolves (evidence: `cmd/root.go`)
- Flags and environment → Resolved configuration: configures (evidence: `internal/flags/flags.go`)
- CLI orchestration → Update action: runs updates (evidence: `cmd/root.go`)
- CLI orchestration → Scheduled scans: starts schedule (evidence: `cmd/root.go`)
- Scheduled scans → Update action: runs scans (evidence: `internal/scheduling/scheduling.go`)
- Update action → Container filters: filters containers (evidence: `internal/actions/update.go`)
- Update action → Dependency ordering: orders dependencies (evidence: `internal/actions/update.go`)
- Update action → Docker operations: updates containers (evidence: `internal/actions/update.go`)
- Update action → Lifecycle hooks: runs hooks (evidence: `internal/actions/update.go`)
- Update action → Compose apply: uses Compose (evidence: `internal/actions/update.go`)
- Update action → Git revision checks: checks revisions (evidence: `internal/actions/update.go`)
- Update action → Digest resolution: resolves releases (evidence: `internal/actions/update.go`)
- Digest resolution → Registry checks: checks digests (evidence: `internal/release/resolver.go`)
- Registry checks → Registry authentication: authenticates (evidence: `pkg/registry/age.go`)
- Registry checks → Image registry: queries
- Git revision checks → Git host: resolves refs (evidence: `internal/git/client.go`)
- Update action → Scan reporting: records progress (evidence: `internal/actions/update.go`)
- CLI orchestration → API routing: registers API
- API routing → Update endpoint: routes requests
- API routing → Check endpoint: routes requests
- API routing → API capabilities: mounts endpoints (evidence: `internal/api/routes/routes.go`)
- Update endpoint → Update action: invokes callback (evidence: `internal/api/handlers/update/handler.go`)
- Check endpoint → Notifications: sends results (evidence: `internal/api/handlers/check/handler.go`)
- Check endpoint → Scan reporting: checks containers
- Update action → Metrics: updates metrics (evidence: `internal/actions/update.go`)
- Scan reporting → Notifications: reports results
- Docker operations → Docker Engine: controls containers (evidence: `README.md`)
