# telekom/sparrow architecture

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

- Interactive diagram: https://gitdiagram.com/telekom/sparrow
- Repository: https://github.com/telekom/sparrow

## Overview

Sparrow periodically runs configurable infrastructure and network checks, then exposes their results and Prometheus metrics through an HTTP API. The graph follows the documented workflow and sampled controller, loader, API, target-manager, and traceroute code; some wiring in the unsampled run and check implementations is necessarily represented only where the tree or README supports it.

Main entry points: [`pkg/sparrow/controller.go`](https://github.com/telekom/sparrow/blob/main/pkg/sparrow/controller.go) (Checks controller), [`pkg/sparrow/run.go`](https://github.com/telekom/sparrow/blob/main/pkg/sparrow/run.go) (Instance runtime), [`pkg/sparrow/handlers.go`](https://github.com/telekom/sparrow/blob/main/pkg/sparrow/handlers.go) (API handlers), [`cmd/run.go`](https://github.com/telekom/sparrow/blob/main/cmd/run.go) (Run command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and config"]
  node_cli["Run command<br/>[run.go]"]
  node_config["Startup config<br/>[config.go]"]
  node_loader["Config loaders<br/>[loader.go]"]
  node_fileloader["File loader<br/>[file.go]"]
  node_httploader["HTTP loader<br/>[http.go]"]
end

subgraph group_runtime["Runtime orchestration"]
  node_runtimecfg["Checks config<br/>[config.go]"]
  node_sparrow["Instance runtime<br/>[run.go]"]
  node_controller["Checks controller<br/>[controller.go]"]
  node_factory["Check factory<br/>[factory.go]"]
  node_results[("Results store<br/>[db.go]")]
end

subgraph group_checks["Monitoring checks"]
  node_health["Health check<br/>[health.go]"]
  node_latency["Latency check<br/>[latency.go]"]
  node_dns["DNS check<br/>[dns.go]"]
  node_traceroute["Traceroute check<br/>[traceroute.go]"]
end

subgraph group_service["API and telemetry"]
  node_api["HTTP API<br/>[api.go]"]
  node_handlers["API handlers<br/>[handlers.go]"]
  node_metrics["Prometheus metrics<br/>[exporter.go]"]
end

subgraph group_targets["Global targets"]
  node_targetmanager["Target manager<br/>[manager.go]"]
  node_interactor["Target interactor<br/>[config.go]"]
end

node_operator(("Operator"))
node_monitored(("Monitored endpoints"))
node_peer(("Sparrow peers"))
node_dnsservice(("DNS service"))
node_network(("Network targets"))
node_client(("Metrics consumers"))
node_gitlab(("GitLab"))

node_operator -->|"starts"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts instance"| node_sparrow
node_sparrow -->|"starts loader"| node_loader
node_loader -->|"selects file"| node_fileloader
node_loader -->|"selects HTTP"| node_httploader
node_fileloader -->|"loads YAML"| node_runtimecfg
node_httploader -->|"fetches YAML"| node_runtimecfg
node_httploader -.->|"fetches config"| node_monitored
node_sparrow -->|"reconciles checks"| node_controller
node_runtimecfg -->|"configures"| node_controller
node_controller -->|"creates checks"| node_factory
node_controller -->|"stores results"| node_results
node_controller -->|"registers collectors"| node_metrics
node_health -->|"checks HTTP"| node_monitored
node_latency -->|"measures round trip"| node_peer
node_dns -->|"resolves names"| node_dnsservice
node_traceroute -->|"traces route"| node_network
node_health -->|"emits results"| node_controller
node_latency -->|"emits results"| node_controller
node_dns -->|"emits results"| node_controller
node_traceroute -->|"emits results"| node_controller
node_sparrow -->|"starts API"| node_api
node_api -->|"dispatches requests"| node_handlers
node_handlers -->|"gets check schemas"| node_controller
node_handlers -->|"reads results"| node_results
node_handlers -->|"serves metrics"| node_metrics
node_metrics -->|"exposes metrics"| node_client
node_sparrow -->|"starts manager"| node_targetmanager
node_targetmanager -->|"uses interactor"| node_interactor
node_interactor -.->|"reads and writes targets"| node_gitlab

click node_cli "https://github.com/telekom/sparrow/blob/main/cmd/run.go"
click node_config "https://github.com/telekom/sparrow/blob/main/pkg/config/config.go"
click node_loader "https://github.com/telekom/sparrow/blob/main/pkg/config/loader.go"
click node_fileloader "https://github.com/telekom/sparrow/blob/main/pkg/config/file.go"
click node_httploader "https://github.com/telekom/sparrow/blob/main/pkg/config/http.go"
click node_runtimecfg "https://github.com/telekom/sparrow/blob/main/pkg/checks/runtime/config.go"
click node_sparrow "https://github.com/telekom/sparrow/blob/main/pkg/sparrow/run.go"
click node_controller "https://github.com/telekom/sparrow/blob/main/pkg/sparrow/controller.go"
click node_factory "https://github.com/telekom/sparrow/blob/main/pkg/factory/factory.go"
click node_health "https://github.com/telekom/sparrow/blob/main/pkg/checks/health/health.go"
click node_latency "https://github.com/telekom/sparrow/blob/main/pkg/checks/latency/latency.go"
click node_dns "https://github.com/telekom/sparrow/blob/main/pkg/checks/dns/dns.go"
click node_traceroute "https://github.com/telekom/sparrow/blob/main/pkg/checks/traceroute/traceroute.go"
click node_results "https://github.com/telekom/sparrow/blob/main/pkg/db/db.go"
click node_api "https://github.com/telekom/sparrow/blob/main/pkg/api/api.go"
click node_handlers "https://github.com/telekom/sparrow/blob/main/pkg/sparrow/handlers.go"
click node_metrics "https://github.com/telekom/sparrow/blob/main/pkg/sparrow/metrics/exporter.go"
click node_targetmanager "https://github.com/telekom/sparrow/blob/main/pkg/sparrow/targets/manager.go"
click node_interactor "https://github.com/telekom/sparrow/blob/main/pkg/sparrow/targets/interactor/config.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_cli,node_config,node_loader,node_fileloader,node_httploader toneBlue
class node_runtimecfg,node_sparrow,node_controller,node_factory,node_results toneAmber
class node_health,node_latency,node_dns,node_traceroute toneMint
class node_api,node_handlers,node_metrics toneRose
class node_targetmanager,node_interactor,node_operator,node_monitored,node_peer,node_dnsservice,node_network,node_client,node_gitlab toneIndigo
```

## Components

### Startup and config

- [Run command](https://github.com/telekom/sparrow/blob/main/cmd/run.go): `cmd/run.go`
- [Startup config](https://github.com/telekom/sparrow/blob/main/pkg/config/config.go): `pkg/config/config.go`
- [Config loaders](https://github.com/telekom/sparrow/blob/main/pkg/config/loader.go): `pkg/config/loader.go`
- [File loader](https://github.com/telekom/sparrow/blob/main/pkg/config/file.go): `pkg/config/file.go`
- [HTTP loader](https://github.com/telekom/sparrow/blob/main/pkg/config/http.go): `pkg/config/http.go`

### Runtime orchestration

- [Checks config](https://github.com/telekom/sparrow/blob/main/pkg/checks/runtime/config.go): `pkg/checks/runtime/config.go`
- [Instance runtime](https://github.com/telekom/sparrow/blob/main/pkg/sparrow/run.go): `pkg/sparrow/run.go`
- [Checks controller](https://github.com/telekom/sparrow/blob/main/pkg/sparrow/controller.go): `pkg/sparrow/controller.go`
- [Check factory](https://github.com/telekom/sparrow/blob/main/pkg/factory/factory.go): `pkg/factory/factory.go`
- [Results store](https://github.com/telekom/sparrow/blob/main/pkg/db/db.go): `pkg/db/db.go`

### Monitoring checks

- [Health check](https://github.com/telekom/sparrow/blob/main/pkg/checks/health/health.go): `pkg/checks/health/health.go`
- [Latency check](https://github.com/telekom/sparrow/blob/main/pkg/checks/latency/latency.go): `pkg/checks/latency/latency.go`
- [DNS check](https://github.com/telekom/sparrow/blob/main/pkg/checks/dns/dns.go): `pkg/checks/dns/dns.go`
- [Traceroute check](https://github.com/telekom/sparrow/blob/main/pkg/checks/traceroute/traceroute.go): `pkg/checks/traceroute/traceroute.go`

### API and telemetry

- [HTTP API](https://github.com/telekom/sparrow/blob/main/pkg/api/api.go): `pkg/api/api.go`
- [API handlers](https://github.com/telekom/sparrow/blob/main/pkg/sparrow/handlers.go): `pkg/sparrow/handlers.go`
- [Prometheus metrics](https://github.com/telekom/sparrow/blob/main/pkg/sparrow/metrics/exporter.go): `pkg/sparrow/metrics/exporter.go`

### Global targets

- [Target manager](https://github.com/telekom/sparrow/blob/main/pkg/sparrow/targets/manager.go): `pkg/sparrow/targets/manager.go`
- [Target interactor](https://github.com/telekom/sparrow/blob/main/pkg/sparrow/targets/interactor/config.go): `pkg/sparrow/targets/interactor/config.go`

### Other components

- **Operator**
- **Monitored endpoints**
- **Sparrow peers**
- **DNS service**
- **Network targets**
- **Metrics consumers**
- **GitLab**

## Connections

- Operator → Run command: starts
- Run command → Startup config: loads settings
- Run command → Instance runtime: starts instance
- Instance runtime → Config loaders: starts loader
- Config loaders → File loader: selects file
- Config loaders → HTTP loader: selects HTTP
- File loader → Checks config: loads YAML
- HTTP loader → Checks config: fetches YAML
- HTTP loader → Monitored endpoints: fetches config
- Instance runtime → Checks controller: reconciles checks
- Checks config → Checks controller: configures
- Checks controller → Check factory: creates checks
- Checks controller → Results store: stores results
- Checks controller → Prometheus metrics: registers collectors
- Health check → Monitored endpoints: checks HTTP
- Latency check → Sparrow peers: measures round trip
- DNS check → DNS service: resolves names
- Traceroute check → Network targets: traces route
- Health check → Checks controller: emits results
- Latency check → Checks controller: emits results
- DNS check → Checks controller: emits results
- Traceroute check → Checks controller: emits results
- Instance runtime → HTTP API: starts API
- HTTP API → API handlers: dispatches requests
- API handlers → Checks controller: gets check schemas
- API handlers → Results store: reads results
- API handlers → Prometheus metrics: serves metrics
- Prometheus metrics → Metrics consumers: exposes metrics
- Instance runtime → Target manager: starts manager
- Target manager → Target interactor: uses interactor
- Target interactor → GitLab: reads and writes targets