# esdmitrii/kconmon-ng architecture

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

- Interactive diagram: https://gitdiagram.com/esdmitrii/kconmon-ng
- Repository: https://github.com/esdmitrii/kconmon-ng

## Overview

kconmon-ng measures connectivity between cluster nodes and presents the results for operators. Agents register with the controller, receive peer assignments, run protocol-specific probes, and report measurements; the console turns those results into matrices, topology, diagnostics, and incident history, with a CLI for controller diagnostics. The README documents the product workflow and capabilities; source excerpts and the index support the principal wiring shown here, while some unsampled subsystem links are intentionally omitted.

Main entry points: [`internal/controller/server.go`](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/controller/server.go) (Controller RPC), [`internal/controller/controller.go`](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/controller/controller.go) (Controller), [`internal/agent/grpc_client.go`](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/agent/grpc_client.go) (Agent RPC client), [`cmd/console/main.go`](https://github.com/esdmitrii/kconmon-ng/blob/main/cmd/console/main.go) (Console service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_measurement["Measurement"]
  node_agent_runtime["Node agent<br/>[agent.go]"]
  node_probe_tasks["Probe tasks<br/>[tasks.go]"]
  node_probe_engines["Protocol probes"]
  node_pmtu_search["PMTU search<br/>[pmtu_search.go]"]
  node_probe_server["Probe responder<br/>[probe_server.go]"]
end

subgraph group_control["Control plane"]
  node_agent_rpc["Agent RPC client<br/>[grpc_client.go]"]
  node_controller["Controller<br/>[controller.go]"]
  node_meshplan["Peer mesh planner<br/>[meshplan.go]"]
  node_controller_rpc["Controller RPC<br/>[server.go]"]
end

subgraph group_console["Console"]
  node_console_process["Console service<br/>[main.go]"]
  node_console_api["HTTP API<br/>[server.go]"]
  node_event_ingester["Event ingester<br/>[ingester.go]"]
  node_check_runner["Diagnostic runs<br/>[runner.go]"]
  node_event_store[("Event history<br/>[events.go]")]
end

subgraph group_presentation["Operator interfaces"]
  node_web_ui["Web console<br/>[overview.tsx]"]
  node_cli["kubectl plugin"]
end

subgraph group_telemetry["Telemetry"]
  node_prometheus(("Prometheus"))
  node_metrics["Prometheus metrics<br/>[prometheus.go]"]
end

node_operator(("Operator"))

node_operator -->|"investigates"| node_web_ui
node_operator -->|"runs diagnostics"| node_cli
node_web_ui -->|"requests data"| node_console_api
node_cli -->|"queries diagnostics"| node_controller_rpc
node_agent_runtime -.->|"runs checks"| node_probe_tasks
node_probe_tasks -->|"executes probes"| node_probe_engines
node_probe_engines -.->|"searches MTU"| node_pmtu_search
node_agent_rpc -->|"dispatches tasks"| node_probe_tasks
node_agent_runtime -->|"registers and reports"| node_agent_rpc
node_controller -->|"builds peer plan"| node_meshplan
node_controller -.->|"hosts service"| node_controller_rpc
node_agent_rpc -->|"registers agents"| node_controller
node_controller_rpc -->|"sends assignments"| node_agent_rpc
node_console_process -->|"mounts routes"| node_console_api
node_console_process -->|"starts ingestion"| node_event_ingester
node_console_process -->|"creates runner"| node_check_runner
node_event_ingester -->|"persists events"| node_event_store
node_event_ingester -->|"watches events"| node_controller_rpc
node_console_api -->|"requests topology"| node_controller_rpc
node_prometheus -->|"scrapes"| node_metrics
node_controller -->|"exports measurements"| node_metrics

click node_agent_runtime "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/agent/agent.go"
click node_probe_tasks "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/agent/tasks.go"
click node_probe_engines "https://github.com/esdmitrii/kconmon-ng/tree/main/internal/checker"
click node_pmtu_search "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/checker/pmtu_search.go"
click node_probe_server "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/agent/probe_server.go"
click node_agent_rpc "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/agent/grpc_client.go"
click node_controller "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/controller/controller.go"
click node_meshplan "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/controller/meshplan/meshplan.go"
click node_controller_rpc "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/controller/server.go"
click node_console_process "https://github.com/esdmitrii/kconmon-ng/blob/main/cmd/console/main.go"
click node_console_api "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/console/httpapi/server.go"
click node_event_ingester "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/console/events/ingester.go"
click node_check_runner "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/console/checks/runner.go"
click node_event_store "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/console/store/events.go"
click node_web_ui "https://github.com/esdmitrii/kconmon-ng/blob/main/web/src/pages/overview.tsx"
click node_cli "https://github.com/esdmitrii/kconmon-ng/tree/main/internal/cli"
click node_metrics "https://github.com/esdmitrii/kconmon-ng/blob/main/internal/metrics/prometheus.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_agent_runtime,node_probe_tasks,node_probe_engines,node_pmtu_search,node_probe_server toneBlue
class node_agent_rpc,node_controller,node_meshplan,node_controller_rpc toneAmber
class node_console_process,node_console_api,node_event_ingester,node_check_runner,node_event_store toneMint
class node_web_ui,node_cli toneRose
class node_prometheus,node_metrics,node_operator toneIndigo
```

## Components

### Measurement

- [Node agent](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/agent/agent.go): `internal/agent/agent.go`
- [Probe tasks](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/agent/tasks.go): `internal/agent/tasks.go`
- [Protocol probes](https://github.com/esdmitrii/kconmon-ng/tree/main/internal/checker): `internal/checker`
- [PMTU search](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/checker/pmtu_search.go): `internal/checker/pmtu_search.go`
- [Probe responder](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/agent/probe_server.go): `internal/agent/probe_server.go`

### Control plane

- [Agent RPC client](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/agent/grpc_client.go): `internal/agent/grpc_client.go`
- [Controller](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/controller/controller.go): `internal/controller/controller.go`
- [Peer mesh planner](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/controller/meshplan/meshplan.go): `internal/controller/meshplan/meshplan.go`
- [Controller RPC](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/controller/server.go): `internal/controller/server.go`

### Console

- [Console service](https://github.com/esdmitrii/kconmon-ng/blob/main/cmd/console/main.go): `cmd/console/main.go`
- [HTTP API](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/console/httpapi/server.go): `internal/console/httpapi/server.go`
- [Event ingester](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/console/events/ingester.go): `internal/console/events/ingester.go`
- [Diagnostic runs](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/console/checks/runner.go): `internal/console/checks/runner.go`
- [Event history](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/console/store/events.go): `internal/console/store/events.go`

### Operator interfaces

- [Web console](https://github.com/esdmitrii/kconmon-ng/blob/main/web/src/pages/overview.tsx): `web/src/pages/overview.tsx`
- [kubectl plugin](https://github.com/esdmitrii/kconmon-ng/tree/main/internal/cli): `internal/cli`

### Telemetry

- **Prometheus**
- [Prometheus metrics](https://github.com/esdmitrii/kconmon-ng/blob/main/internal/metrics/prometheus.go): `internal/metrics/prometheus.go`

### Other components

- **Operator**

## Connections

- Operator → Web console: investigates
- Operator → kubectl plugin: runs diagnostics
- Web console → HTTP API: requests data
- kubectl plugin → Controller RPC: queries diagnostics
- Node agent → Probe tasks: runs checks
- Probe tasks → Protocol probes: executes probes (evidence: `internal/agent/tasks.go`)
- Protocol probes → PMTU search: searches MTU
- Agent RPC client → Probe tasks: dispatches tasks (evidence: `internal/agent/grpc_client.go`)
- Node agent → Agent RPC client: registers and reports
- Controller → Peer mesh planner: builds peer plan (evidence: `internal/controller/controller.go`)
- Controller → Controller RPC: hosts service
- Agent RPC client → Controller: registers agents
- Controller RPC → Agent RPC client: sends assignments
- Console service → HTTP API: mounts routes (evidence: `cmd/console/main.go`)
- Console service → Event ingester: starts ingestion (evidence: `cmd/console/main.go`)
- Console service → Diagnostic runs: creates runner (evidence: `cmd/console/main.go`)
- Event ingester → Event history: persists events (evidence: `internal/console/events/ingester.go`)
- Event ingester → Controller RPC: watches events (evidence: `internal/console/events/ingester.go`)
- HTTP API → Controller RPC: requests topology (evidence: `internal/console/httpapi/server.go`)
- Prometheus → Prometheus metrics: scrapes
- Controller → Prometheus metrics: exports measurements (evidence: `internal/controller/controller.go`)
