# jzi96/tagwatch architecture

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

- Interactive diagram: https://gitdiagram.com/jzi96/tagwatch
- Repository: https://github.com/jzi96/tagwatch

## Overview

Tagwatch is a Go service that polls configured public container registries, tracks tag and digest changes in a persistent JSON baseline, optionally compares configured repositories with running Docker containers, and serves a server-rendered HTML report. The main workflow is configuration loading, registry snapshot collection and filtering, state/history updates, then report publication and HTTP rendering. Optional Docker inspection adds per-container comparisons. Edges reflect calls visible in the excerpts or capabilities explicitly documented in the README; unsampled implementation details are not inferred.

Main entry points: [`cmd/tagwatch/main.go`](https://github.com/jzi96/tagwatch/blob/main/cmd/tagwatch/main.go) (Service entry), [`internal/monitor/monitor.go`](https://github.com/jzi96/tagwatch/blob/main/internal/monitor/monitor.go) (Polling monitor), [`internal/web/web.go`](https://github.com/jzi96/tagwatch/blob/main/internal/web/web.go) (HTTP handler), [`internal/registry/registry.go`](https://github.com/jzi96/tagwatch/blob/main/internal/registry/registry.go) (Registry client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and configuration"]
  node_entry["Service entry<br/>[main.go]"]
  node_configuration["Configuration<br/>[config.go]"]
end

subgraph group_tracking["Registry tracking"]
  node_monitor["Polling monitor<br/>[monitor.go]"]
  node_registry["Registry client<br/>[registry.go]"]
  node_history["State and history<br/>[state.go]"]
  node_statefile[("JSON state file")]
end

subgraph group_runtime["Runtime comparison"]
  node_dockerclient["Docker inspector<br/>[docker.go]"]
  node_comparison["Running comparisons<br/>[monitor.go]"]
end

subgraph group_reporting["Report and web"]
  node_handler["HTTP handler<br/>[web.go]"]
  node_template["HTML report template<br/>[index.html]"]
end

node_operator(("Operator"))
node_dockerengine["Docker Engine"]
node_registries["OCI registries"]
node_viewer(("Report viewer"))

node_operator -->|"starts"| node_entry
node_entry -->|"loads settings"| node_configuration
node_entry -->|"creates and runs"| node_monitor
node_entry -->|"provides client"| node_registry
node_entry -->|"configures optionally"| node_dockerclient
node_entry -->|"serves"| node_handler
node_monitor -->|"parses and filters"| node_configuration
node_monitor -->|"lists and resolves"| node_registry
node_registry -->|"requests tags and manifests"| node_registries
node_monitor -->|"loads, applies, saves"| node_history
node_history -->|"reads and writes"| node_statefile
node_monitor -->|"builds report comparisons"| node_comparison
node_comparison -->|"lists running containers"| node_dockerclient
node_comparison -->|"resolves platform digest"| node_registry
node_dockerclient -->|"inspects over socket"| node_dockerengine
node_handler -->|"reads report"| node_monitor
node_handler -->|"renders"| node_template
node_viewer -->|"requests report"| node_handler

click node_entry "https://github.com/jzi96/tagwatch/blob/main/cmd/tagwatch/main.go"
click node_configuration "https://github.com/jzi96/tagwatch/blob/main/internal/config/config.go"
click node_monitor "https://github.com/jzi96/tagwatch/blob/main/internal/monitor/monitor.go"
click node_registry "https://github.com/jzi96/tagwatch/blob/main/internal/registry/registry.go"
click node_history "https://github.com/jzi96/tagwatch/blob/main/internal/monitor/state.go"
click node_dockerclient "https://github.com/jzi96/tagwatch/blob/main/internal/docker/docker.go"
click node_comparison "https://github.com/jzi96/tagwatch/blob/main/internal/monitor/monitor.go"
click node_handler "https://github.com/jzi96/tagwatch/blob/main/internal/web/web.go"
click node_template "https://github.com/jzi96/tagwatch/blob/main/internal/web/index.html"

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_entry,node_configuration,node_viewer toneBlue
class node_monitor,node_registry,node_history,node_statefile toneAmber
class node_dockerclient,node_comparison toneMint
class node_handler,node_template toneRose
class node_operator,node_dockerengine,node_registries toneIndigo
```

## Components

### Startup and configuration

- [Service entry](https://github.com/jzi96/tagwatch/blob/main/cmd/tagwatch/main.go): `cmd/tagwatch/main.go`
- [Configuration](https://github.com/jzi96/tagwatch/blob/main/internal/config/config.go): `internal/config/config.go`

### Registry tracking

- [Polling monitor](https://github.com/jzi96/tagwatch/blob/main/internal/monitor/monitor.go): `internal/monitor/monitor.go`
- [Registry client](https://github.com/jzi96/tagwatch/blob/main/internal/registry/registry.go): `internal/registry/registry.go`
- [State and history](https://github.com/jzi96/tagwatch/blob/main/internal/monitor/state.go): `internal/monitor/state.go`
- **JSON state file**

### Runtime comparison

- [Docker inspector](https://github.com/jzi96/tagwatch/blob/main/internal/docker/docker.go): `internal/docker/docker.go`
- [Running comparisons](https://github.com/jzi96/tagwatch/blob/main/internal/monitor/monitor.go): `internal/monitor/monitor.go`

### Report and web

- [HTTP handler](https://github.com/jzi96/tagwatch/blob/main/internal/web/web.go): `internal/web/web.go`
- [HTML report template](https://github.com/jzi96/tagwatch/blob/main/internal/web/index.html): `internal/web/index.html`

### Other components

- **Operator**
- **Docker Engine**
- **OCI registries**
- **Report viewer**

## Connections

- Operator → Service entry: starts (evidence: `README.md`)
- Service entry → Configuration: loads settings (evidence: `cmd/tagwatch/main.go`)
- Service entry → Polling monitor: creates and runs (evidence: `cmd/tagwatch/main.go`)
- Service entry → Registry client: provides client (evidence: `cmd/tagwatch/main.go`)
- Service entry → Docker inspector: configures optionally (evidence: `cmd/tagwatch/main.go`)
- Service entry → HTTP handler: serves (evidence: `cmd/tagwatch/main.go`)
- Polling monitor → Configuration: parses and filters (evidence: `internal/monitor/monitor.go`)
- Polling monitor → Registry client: lists and resolves (evidence: `internal/monitor/monitor.go`)
- Registry client → OCI registries: requests tags and manifests (evidence: `internal/registry/registry.go`)
- Polling monitor → State and history: loads, applies, saves (evidence: `internal/monitor/monitor.go`)
- State and history → JSON state file: reads and writes (evidence: `internal/monitor/state.go`)
- Polling monitor → Running comparisons: builds report comparisons (evidence: `internal/monitor/monitor.go`)
- Running comparisons → Docker inspector: lists running containers (evidence: `internal/monitor/monitor.go`)
- Running comparisons → Registry client: resolves platform digest (evidence: `internal/monitor/monitor.go`)
- Docker inspector → Docker Engine: inspects over socket (evidence: `internal/docker/docker.go`)
- HTTP handler → Polling monitor: reads report (evidence: `internal/web/web.go`)
- HTTP handler → HTML report template: renders (evidence: `internal/web/web.go`)
- Report viewer → HTTP handler: requests report (evidence: `README.md`)
