# kinncj/heimdall architecture

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

- Interactive diagram: https://gitdiagram.com/kinncj/heimdall
- Repository: https://github.com/kinncj/heimdall

## Overview

Heimdall collects host hardware and observability data with outbound-only daemons, sends it to a central hub, and presents the fleet through a terminal dashboard or JSON CLI. The hub also supports federation, alerts, durable and OpenMetrics export, discovery, and on-demand diagnostics. The principal flow is documented in the README and daemon excerpt; several secondary subsystem links are included only where the README explicitly describes them, since their implementation excerpts were not provided.

Main entry points: [`app/internal/hub/hub.go`](https://github.com/kinncj/heimdall/blob/main/app/internal/hub/hub.go) (Hub server), [`app/cmd/daemon/main.go`](https://github.com/kinncj/heimdall/blob/main/app/cmd/daemon/main.go) (Metrics daemon), [`app/cmd/dashboard/main.go`](https://github.com/kinncj/heimdall/blob/main/app/cmd/dashboard/main.go) (Dashboard client), [`app/internal/cli/cli.go`](https://github.com/kinncj/heimdall/blob/main/app/internal/cli/cli.go) (JSON CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collect["Host collection"]
  node_daemon["Metrics daemon<br/>[main.go]"]
  node_adapters["Metric adapters"]
  node_helper["Privileged helper<br/>[server.go]"]
  node_logs["Log streaming<br/>[server.go]"]
  node_process["Process view<br/>[proc.go]"]
end

subgraph group_hub["Hub services"]
  node_hubserver["Hub server<br/>[hub.go]"]
  node_alerts["Threshold alerts<br/>[engine.go]"]
  node_federation["Hub federation<br/>[relay.go]"]
  node_discovery["mDNS discovery<br/>[mdns.go]"]
  node_storage[("Metric storage<br/>[prometheus.go]")]
  node_observe["Metrics export<br/>[server.go]"]
end

subgraph group_present["Fleet presentation"]
  node_dashboard["Dashboard client<br/>[main.go]"]
  node_tui["Terminal interface<br/>[model.go]"]
  node_cli["JSON CLI<br/>[cli.go]"]
end

subgraph group_domain["Shared model"]
  node_protocol["Monitoring contract<br/>[monitoring.proto]"]
  node_registry["Host registry<br/>[hostregistry.go]"]
end

subgraph group_integrations["External interfaces"]
  node_scraper(("Prometheus scraper"))
  node_webhook(("Alert webhook"))
  node_parenthub(("Parent hub"))
end

node_operator(("Operator"))

node_operator -->|"starts"| node_daemon
node_daemon -->|"samples"| node_adapters
node_daemon -.->|"requests privileged data"| node_helper
node_daemon -.->|"pushes opted-in logs"| node_logs
node_daemon -.->|"pushes process table"| node_process
node_daemon -->|"streams snapshots"| node_protocol
node_daemon -->|"streams metrics"| node_hubserver
node_hubserver -.->|"updates host views"| node_registry
node_hubserver -->|"serves gRPC contract"| node_protocol
node_hubserver -->|"evaluates rules"| node_alerts
node_alerts -.->|"notifies transitions"| node_webhook
node_hubserver -.->|"relays upstream"| node_federation
node_federation -.->|"sends snapshots"| node_parenthub
node_hubserver -.->|"persists metrics"| node_storage
node_hubserver -.->|"exports fleet metrics"| node_observe
node_scraper -->|"scrapes metrics"| node_observe
node_operator -->|"opens fleet view"| node_dashboard
node_dashboard -->|"subscribes"| node_hubserver
node_dashboard -.->|"resolves hub"| node_discovery
node_dashboard -->|"renders fleet"| node_tui
node_operator -->|"runs queries"| node_cli
node_cli -->|"queries fleet"| node_hubserver
node_dashboard -.->|"routes commands"| node_hubserver
node_cli -.->|"runs commands"| node_hubserver

click node_daemon "https://github.com/kinncj/heimdall/blob/main/app/cmd/daemon/main.go"
click node_adapters "https://github.com/kinncj/heimdall/tree/main/app/internal/adapters"
click node_helper "https://github.com/kinncj/heimdall/blob/main/app/internal/helper/server.go"
click node_logs "https://github.com/kinncj/heimdall/blob/main/app/internal/logs/server.go"
click node_process "https://github.com/kinncj/heimdall/blob/main/app/internal/proc/proc.go"
click node_protocol "https://github.com/kinncj/heimdall/blob/main/common/proto/monitoring/v1/monitoring.proto"
click node_hubserver "https://github.com/kinncj/heimdall/blob/main/app/internal/hub/hub.go"
click node_registry "https://github.com/kinncj/heimdall/blob/main/app/internal/domain/hostregistry.go"
click node_alerts "https://github.com/kinncj/heimdall/blob/main/app/internal/alert/engine.go"
click node_federation "https://github.com/kinncj/heimdall/blob/main/app/internal/hub/relay.go"
click node_discovery "https://github.com/kinncj/heimdall/blob/main/app/internal/discovery/mdns.go"
click node_storage "https://github.com/kinncj/heimdall/blob/main/app/internal/store/prometheus.go"
click node_observe "https://github.com/kinncj/heimdall/blob/main/app/internal/observe/server.go"
click node_dashboard "https://github.com/kinncj/heimdall/blob/main/app/cmd/dashboard/main.go"
click node_tui "https://github.com/kinncj/heimdall/blob/main/app/internal/tui/dashboard/model.go"
click node_cli "https://github.com/kinncj/heimdall/blob/main/app/internal/cli/cli.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_daemon,node_adapters,node_helper,node_logs,node_process toneBlue
class node_hubserver,node_alerts,node_federation,node_discovery,node_storage,node_observe toneAmber
class node_dashboard,node_tui,node_cli toneMint
class node_protocol,node_registry toneRose
class node_scraper,node_webhook,node_parenthub,node_operator toneIndigo
```

## Components

### Host collection

- [Metrics daemon](https://github.com/kinncj/heimdall/blob/main/app/cmd/daemon/main.go): `app/cmd/daemon/main.go`
- [Metric adapters](https://github.com/kinncj/heimdall/tree/main/app/internal/adapters): `app/internal/adapters`
- [Privileged helper](https://github.com/kinncj/heimdall/blob/main/app/internal/helper/server.go): `app/internal/helper/server.go`
- [Log streaming](https://github.com/kinncj/heimdall/blob/main/app/internal/logs/server.go): `app/internal/logs/server.go`
- [Process view](https://github.com/kinncj/heimdall/blob/main/app/internal/proc/proc.go): `app/internal/proc/proc.go`

### Hub services

- [Hub server](https://github.com/kinncj/heimdall/blob/main/app/internal/hub/hub.go): `app/internal/hub/hub.go`
- [Threshold alerts](https://github.com/kinncj/heimdall/blob/main/app/internal/alert/engine.go): `app/internal/alert/engine.go`
- [Hub federation](https://github.com/kinncj/heimdall/blob/main/app/internal/hub/relay.go): `app/internal/hub/relay.go`
- [mDNS discovery](https://github.com/kinncj/heimdall/blob/main/app/internal/discovery/mdns.go): `app/internal/discovery/mdns.go`
- [Metric storage](https://github.com/kinncj/heimdall/blob/main/app/internal/store/prometheus.go): `app/internal/store/prometheus.go`
- [Metrics export](https://github.com/kinncj/heimdall/blob/main/app/internal/observe/server.go): `app/internal/observe/server.go`

### Fleet presentation

- [Dashboard client](https://github.com/kinncj/heimdall/blob/main/app/cmd/dashboard/main.go): `app/cmd/dashboard/main.go`
- [Terminal interface](https://github.com/kinncj/heimdall/blob/main/app/internal/tui/dashboard/model.go): `app/internal/tui/dashboard/model.go`
- [JSON CLI](https://github.com/kinncj/heimdall/blob/main/app/internal/cli/cli.go): `app/internal/cli/cli.go`

### Shared model

- [Monitoring contract](https://github.com/kinncj/heimdall/blob/main/common/proto/monitoring/v1/monitoring.proto): `common/proto/monitoring/v1/monitoring.proto`
- [Host registry](https://github.com/kinncj/heimdall/blob/main/app/internal/domain/hostregistry.go): `app/internal/domain/hostregistry.go`

### External interfaces

- **Prometheus scraper**
- **Alert webhook**
- **Parent hub**

### Other components

- **Operator**

## Connections

- Operator → Metrics daemon: starts
- Metrics daemon → Metric adapters: samples (evidence: `app/cmd/daemon/main.go`)
- Metrics daemon → Privileged helper: requests privileged data
- Metrics daemon → Log streaming: pushes opted-in logs
- Metrics daemon → Process view: pushes process table
- Metrics daemon → Monitoring contract: streams snapshots
- Metrics daemon → Hub server: streams metrics
- Hub server → Host registry: updates host views
- Hub server → Monitoring contract: serves gRPC contract
- Hub server → Threshold alerts: evaluates rules
- Threshold alerts → Alert webhook: notifies transitions
- Hub server → Hub federation: relays upstream
- Hub federation → Parent hub: sends snapshots
- Hub server → Metric storage: persists metrics
- Hub server → Metrics export: exports fleet metrics
- Prometheus scraper → Metrics export: scrapes metrics
- Operator → Dashboard client: opens fleet view
- Dashboard client → Hub server: subscribes
- Dashboard client → mDNS discovery: resolves hub
- Dashboard client → Terminal interface: renders fleet (evidence: `app/cmd/dashboard/main.go`)
- Operator → JSON CLI: runs queries
- JSON CLI → Hub server: queries fleet
- Dashboard client → Hub server: routes commands
- JSON CLI → Hub server: runs commands