# avivgt/keck architecture

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

## Overview

Keck meters workload power on Kubernetes nodes, enriches and attributes measurements, aggregates them cluster-wide, and exposes results through a console UI. Its documented flow runs from hardware and kernel observations through per-workload attribution to agent reports, controller aggregation, and dashboard queries. The repository also includes an operator for cluster deployment and a fleet manager for multi-cluster governance. Some subsystem details are documented but their implementation was not sampled, so those branches are shown only where the README or excerpts establish the relationship.

Main entry points: [`keck-agent/src/main.rs`](https://github.com/avivgt/keck/blob/main/keck-agent/src/main.rs) (Node agent), [`keck-ui/src/components/PowerManagementPage.tsx`](https://github.com/avivgt/keck/blob/main/keck-ui/src/components/PowerManagementPage.tsx) (Power console), [`keck-agent/src/hardware/collector.rs`](https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/collector.rs) (Hardware collection), [`keck-controller/src/api/mod.rs`](https://github.com/avivgt/keck/blob/main/keck-controller/src/api/mod.rs) (Controller REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_measurement["Node measurement"]
  node_agent["Node agent<br/>[main.rs]"]
  node_hardware["Hardware collection<br/>[collector.rs]"]
  node_rapl["RAPL energy<br/>[rapl.rs]"]
  node_hwmon["hwmon sensors<br/>[hwmon.rs]"]
  node_platform["PSU ground truth<br/>[platform.rs]"]
  node_gpu["GPU power<br/>[gpu.rs]"]
  node_ebpf_observer["eBPF observer<br/>[mod.rs]"]
  node_kernel_programs["Kernel programs<br/>[main.rs]"]
  node_perf_counters["Hardware counters<br/>[perf_counters.rs]"]
  node_attribution["Attribution engine<br/>[engine.rs]"]
  node_attribution_models["Attribution models<br/>[model.rs]"]
  node_workload_enrichment["Kubernetes enrichment<br/>[workload.rs]"]
  node_agent_store[("Agent ring buffer<br/>[mod.rs]")]
end

subgraph group_cluster["Cluster service"]
  node_controller_api["Controller REST API<br/>[mod.rs]"]
  node_aggregator[("Cluster aggregator<br/>[mod.rs]")]
  node_classification["Workload classification<br/>[application.rs]"]
  node_kepler["Kepler comparison<br/>[kepler_scraper.rs]"]
end

subgraph group_fleet["Fleet management"]
  node_fleet_api["Fleet API<br/>[mod.rs]"]
  node_fleet_registry[("Cluster registry<br/>[mod.rs]")]
  node_fleet_policy["Fleet policies<br/>[mod.rs]"]
  node_fleet_reporting["Fleet reporting<br/>[mod.rs]"]
end

subgraph group_deployment["Kubernetes deployment"]
  node_operator["Cluster operator"]
  node_cluster_resource["KeckCluster resource<br/>[types.go]"]
end

subgraph group_dashboard["Console dashboard"]
  node_console["Power console"]
  node_cluster_view["Cluster overview"]
  node_namespace_view["Namespace view<br/>[NamespaceView.tsx]"]
  node_application_view["Application view"]
  node_node_view["Node view<br/>[NodesView.tsx]"]
  node_pod_view["Pod view<br/>[PodView.tsx]"]
  node_kepler_view["Kepler comparison view"]
  node_ui_api["Dashboard API client<br/>[api.ts]"]
end

node_console_user(("Console user"))

node_operator -->|"reconciles"| node_cluster_resource
node_agent -->|"collects signals"| node_hardware
node_agent -->|"reads observations"| node_ebpf_observer
node_agent -->|"reads counters"| node_perf_counters
node_agent -->|"attributes power"| node_attribution
node_agent -->|"enriches workloads"| node_workload_enrichment
node_agent -.->|"stores measurements"| node_agent_store
node_hardware -.->|"reads energy"| node_rapl
node_hardware -.->|"reads sensors"| node_hwmon
node_hardware -.->|"reads PSU"| node_platform
node_hardware -.->|"reads GPU power"| node_gpu
node_ebpf_observer -.->|"loads programs"| node_kernel_programs
node_attribution -->|"uses models"| node_attribution_models
node_agent -->|"posts reports"| node_controller_api
node_controller_api -->|"updates state"| node_aggregator
node_controller_api -->|"uses classification"| node_classification
node_kepler -->|"adds comparison data"| node_aggregator
node_console_user -->|"opens"| node_console
node_console -.->|"shows overview"| node_cluster_view
node_console -.->|"shows namespaces"| node_namespace_view
node_console -.->|"shows applications"| node_application_view
node_console -.->|"shows nodes"| node_node_view
node_console -.->|"shows pods"| node_pod_view
node_console -.->|"compares Kepler"| node_kepler_view
node_cluster_view -->|"requests data"| node_ui_api
node_namespace_view -->|"requests data"| node_ui_api
node_ui_api -.->|"queries REST"| node_controller_api
node_fleet_api -.->|"ingests reports"| node_fleet_registry
node_fleet_policy -->|"evaluates registry"| node_fleet_registry
node_fleet_reporting -->|"reports registry"| node_fleet_registry

click node_operator "https://github.com/avivgt/keck/blob/main/keck-operator/controllers/keckcluster_controller.go"
click node_cluster_resource "https://github.com/avivgt/keck/blob/main/keck-operator/api/v1alpha1/types.go"
click node_agent "https://github.com/avivgt/keck/blob/main/keck-agent/src/main.rs"
click node_hardware "https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/collector.rs"
click node_rapl "https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/rapl.rs"
click node_hwmon "https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/hwmon.rs"
click node_platform "https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/platform.rs"
click node_gpu "https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/gpu.rs"
click node_ebpf_observer "https://github.com/avivgt/keck/blob/main/keck-agent/src/ebpf/mod.rs"
click node_kernel_programs "https://github.com/avivgt/keck/blob/main/keck-ebpf/src/main.rs"
click node_perf_counters "https://github.com/avivgt/keck/blob/main/keck-agent/src/perf_counters.rs"
click node_attribution "https://github.com/avivgt/keck/blob/main/keck-agent/src/attribution/engine.rs"
click node_attribution_models "https://github.com/avivgt/keck/blob/main/keck-agent/src/attribution/model.rs"
click node_workload_enrichment "https://github.com/avivgt/keck/blob/main/keck-agent/src/k8s/workload.rs"
click node_agent_store "https://github.com/avivgt/keck/blob/main/keck-agent/src/store/mod.rs"
click node_controller_api "https://github.com/avivgt/keck/blob/main/keck-controller/src/api/mod.rs"
click node_aggregator "https://github.com/avivgt/keck/blob/main/keck-controller/src/aggregator/mod.rs"
click node_classification "https://github.com/avivgt/keck/blob/main/keck-controller/src/application.rs"
click node_kepler "https://github.com/avivgt/keck/blob/main/keck-controller/src/kepler_scraper.rs"
click node_fleet_api "https://github.com/avivgt/keck/blob/main/keck-fleet/src/api/mod.rs"
click node_fleet_registry "https://github.com/avivgt/keck/blob/main/keck-fleet/src/registry/mod.rs"
click node_fleet_policy "https://github.com/avivgt/keck/blob/main/keck-fleet/src/policy/mod.rs"
click node_fleet_reporting "https://github.com/avivgt/keck/blob/main/keck-fleet/src/reporting/mod.rs"
click node_console "https://github.com/avivgt/keck/blob/main/keck-ui/src/components/PowerManagementPage.tsx"
click node_cluster_view "https://github.com/avivgt/keck/blob/main/keck-ui/src/components/cluster/ClusterOverview.tsx"
click node_namespace_view "https://github.com/avivgt/keck/blob/main/keck-ui/src/components/namespace/NamespaceView.tsx"
click node_application_view "https://github.com/avivgt/keck/blob/main/keck-ui/src/components/application/ApplicationsView.tsx"
click node_node_view "https://github.com/avivgt/keck/blob/main/keck-ui/src/components/node/NodesView.tsx"
click node_pod_view "https://github.com/avivgt/keck/blob/main/keck-ui/src/components/pod/PodView.tsx"
click node_kepler_view "https://github.com/avivgt/keck/blob/main/keck-ui/src/components/kepler/KeplerComparisonView.tsx"
click node_ui_api "https://github.com/avivgt/keck/blob/main/keck-ui/src/utils/api.ts"

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,node_hardware,node_rapl,node_hwmon,node_platform,node_gpu,node_ebpf_observer,node_kernel_programs,node_perf_counters,node_attribution,node_attribution_models,node_workload_enrichment,node_agent_store,node_console_user toneBlue
class node_controller_api,node_aggregator,node_classification,node_kepler toneAmber
class node_fleet_api,node_fleet_registry,node_fleet_policy,node_fleet_reporting toneMint
class node_operator,node_cluster_resource toneRose
class node_console,node_cluster_view,node_namespace_view,node_application_view,node_node_view,node_pod_view,node_kepler_view,node_ui_api toneIndigo
```

## Components

### Node measurement

- [Node agent](https://github.com/avivgt/keck/blob/main/keck-agent/src/main.rs): `keck-agent/src/main.rs`
- [Hardware collection](https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/collector.rs): `keck-agent/src/hardware/collector.rs`
- [RAPL energy](https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/rapl.rs): `keck-agent/src/hardware/rapl.rs`
- [hwmon sensors](https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/hwmon.rs): `keck-agent/src/hardware/hwmon.rs`
- [PSU ground truth](https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/platform.rs): `keck-agent/src/hardware/platform.rs`
- [GPU power](https://github.com/avivgt/keck/blob/main/keck-agent/src/hardware/gpu.rs): `keck-agent/src/hardware/gpu.rs`
- [eBPF observer](https://github.com/avivgt/keck/blob/main/keck-agent/src/ebpf/mod.rs): `keck-agent/src/ebpf/mod.rs`
- [Kernel programs](https://github.com/avivgt/keck/blob/main/keck-ebpf/src/main.rs): `keck-ebpf/src/main.rs`
- [Hardware counters](https://github.com/avivgt/keck/blob/main/keck-agent/src/perf_counters.rs): `keck-agent/src/perf_counters.rs`
- [Attribution engine](https://github.com/avivgt/keck/blob/main/keck-agent/src/attribution/engine.rs): `keck-agent/src/attribution/engine.rs`
- [Attribution models](https://github.com/avivgt/keck/blob/main/keck-agent/src/attribution/model.rs): `keck-agent/src/attribution/model.rs`
- [Kubernetes enrichment](https://github.com/avivgt/keck/blob/main/keck-agent/src/k8s/workload.rs): `keck-agent/src/k8s/workload.rs`
- [Agent ring buffer](https://github.com/avivgt/keck/blob/main/keck-agent/src/store/mod.rs): `keck-agent/src/store/mod.rs`

### Cluster service

- [Controller REST API](https://github.com/avivgt/keck/blob/main/keck-controller/src/api/mod.rs): `keck-controller/src/api/mod.rs`
- [Cluster aggregator](https://github.com/avivgt/keck/blob/main/keck-controller/src/aggregator/mod.rs): `keck-controller/src/aggregator/mod.rs`
- [Workload classification](https://github.com/avivgt/keck/blob/main/keck-controller/src/application.rs): `keck-controller/src/application.rs`
- [Kepler comparison](https://github.com/avivgt/keck/blob/main/keck-controller/src/kepler_scraper.rs): `keck-controller/src/kepler_scraper.rs`

### Fleet management

- [Fleet API](https://github.com/avivgt/keck/blob/main/keck-fleet/src/api/mod.rs): `keck-fleet/src/api/mod.rs`
- [Cluster registry](https://github.com/avivgt/keck/blob/main/keck-fleet/src/registry/mod.rs): `keck-fleet/src/registry/mod.rs`
- [Fleet policies](https://github.com/avivgt/keck/blob/main/keck-fleet/src/policy/mod.rs): `keck-fleet/src/policy/mod.rs`
- [Fleet reporting](https://github.com/avivgt/keck/blob/main/keck-fleet/src/reporting/mod.rs): `keck-fleet/src/reporting/mod.rs`

### Kubernetes deployment

- [Cluster operator](https://github.com/avivgt/keck/blob/main/keck-operator/controllers/keckcluster_controller.go): `keck-operator/controllers/keckcluster_controller.go`
- [KeckCluster resource](https://github.com/avivgt/keck/blob/main/keck-operator/api/v1alpha1/types.go): `keck-operator/api/v1alpha1/types.go`

### Console dashboard

- [Power console](https://github.com/avivgt/keck/blob/main/keck-ui/src/components/PowerManagementPage.tsx): `keck-ui/src/components/PowerManagementPage.tsx`
- [Cluster overview](https://github.com/avivgt/keck/blob/main/keck-ui/src/components/cluster/ClusterOverview.tsx): `keck-ui/src/components/cluster/ClusterOverview.tsx`
- [Namespace view](https://github.com/avivgt/keck/blob/main/keck-ui/src/components/namespace/NamespaceView.tsx): `keck-ui/src/components/namespace/NamespaceView.tsx`
- [Application view](https://github.com/avivgt/keck/blob/main/keck-ui/src/components/application/ApplicationsView.tsx): `keck-ui/src/components/application/ApplicationsView.tsx`
- [Node view](https://github.com/avivgt/keck/blob/main/keck-ui/src/components/node/NodesView.tsx): `keck-ui/src/components/node/NodesView.tsx`
- [Pod view](https://github.com/avivgt/keck/blob/main/keck-ui/src/components/pod/PodView.tsx): `keck-ui/src/components/pod/PodView.tsx`
- [Kepler comparison view](https://github.com/avivgt/keck/blob/main/keck-ui/src/components/kepler/KeplerComparisonView.tsx): `keck-ui/src/components/kepler/KeplerComparisonView.tsx`
- [Dashboard API client](https://github.com/avivgt/keck/blob/main/keck-ui/src/utils/api.ts): `keck-ui/src/utils/api.ts`

### Other components

- **Console user**

## Connections

- Cluster operator → KeckCluster resource: reconciles (evidence: `keck-operator/controllers/keckcluster_controller.go`)
- Node agent → Hardware collection: collects signals (evidence: `keck-agent/src/main.rs`)
- Node agent → eBPF observer: reads observations (evidence: `keck-agent/src/main.rs`)
- Node agent → Hardware counters: reads counters (evidence: `keck-agent/src/main.rs`)
- Node agent → Attribution engine: attributes power (evidence: `keck-agent/src/main.rs`)
- Node agent → Kubernetes enrichment: enriches workloads (evidence: `keck-agent/src/main.rs`)
- Node agent → Agent ring buffer: stores measurements
- Hardware collection → RAPL energy: reads energy
- Hardware collection → hwmon sensors: reads sensors
- Hardware collection → PSU ground truth: reads PSU
- Hardware collection → GPU power: reads GPU power
- eBPF observer → Kernel programs: loads programs
- Attribution engine → Attribution models: uses models (evidence: `keck-agent/src/attribution/engine.rs`)
- Node agent → Controller REST API: posts reports
- Controller REST API → Cluster aggregator: updates state (evidence: `keck-controller/src/api/mod.rs`)
- Controller REST API → Workload classification: uses classification (evidence: `keck-controller/src/api/mod.rs`)
- Kepler comparison → Cluster aggregator: adds comparison data (evidence: `keck-controller/src/kepler_scraper.rs`)
- Console user → Power console: opens
- Power console → Cluster overview: shows overview
- Power console → Namespace view: shows namespaces
- Power console → Application view: shows applications
- Power console → Node view: shows nodes
- Power console → Pod view: shows pods
- Power console → Kepler comparison view: compares Kepler
- Cluster overview → Dashboard API client: requests data (evidence: `keck-ui/src/components/cluster/ClusterOverview.tsx`)
- Namespace view → Dashboard API client: requests data (evidence: `keck-ui/src/components/namespace/NamespaceView.tsx`)
- Dashboard API client → Controller REST API: queries REST
- Fleet API → Cluster registry: ingests reports (evidence: `keck-fleet/src/api/mod.rs`)
- Fleet policies → Cluster registry: evaluates registry (evidence: `keck-fleet/src/main.rs`)
- Fleet reporting → Cluster registry: reports registry (evidence: `keck-fleet/src/main.rs`)
