# devanshm15/healkube architecture

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

- Interactive diagram: https://gitdiagram.com/devanshm15/healkube
- Repository: https://github.com/devanshm15/healkube

## Overview

HealKube is an autonomous Kubernetes controller that detects application-level degradation and applies guarded remediation. Its principal workflow collects cluster and application telemetry, detects sustained anomalies, diagnoses causes, evaluates safety policy, executes a permitted action, and verifies recovery; it also records audit history. The demo workload exposes probes, metrics, and controlled fault injection, while the controller provides a status API and dashboard. The README documents the full workflow; several finer implementation details are unsampled, so unsupported connections are omitted.

Main entry points: [`healkube/controller/main.py`](https://github.com/devanshm15/healkube/blob/main/healkube/controller/main.py) (Reconciliation & API), [`healkube/controller/monitor.py`](https://github.com/devanshm15/healkube/blob/main/healkube/controller/monitor.py) (Cluster Monitor), [`healkube/controller/models.py`](https://github.com/devanshm15/healkube/blob/main/healkube/controller/models.py) (Domain Models), [`healkube/controller/diagnosis.py`](https://github.com/devanshm15/healkube/blob/main/healkube/controller/diagnosis.py) (Diagnosis Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_controller["Controller"]
  node_config["Controller Config<br/>[config.py]"]
  node_loop["Reconciliation &amp; API<br/>[main.py]"]
  node_models["Domain Models<br/>[models.py]"]
  node_detector["Anomaly Detector<br/>[detector.py]"]
  node_diagnosis["Diagnosis Engine<br/>[diagnosis.py]"]
  node_policy["Safety Policy<br/>[policy.py]"]
  node_remediation["Remediation Executor<br/>[remediation.py]"]
  node_verifier["Recovery Verifier<br/>[verifier.py]"]
  node_audit[("Audit Logger<br/>[audit.py]")]
end

subgraph group_observability["Observability"]
  node_monitor["Cluster Monitor<br/>[monitor.py]"]
  node_promclient["Prometheus Client"]
  node_prometheus["Prometheus"]
  node_k8sapi["Kubernetes API"]
  node_dependency["Dependency Probe"]
end

subgraph group_workload["Managed Workload"]
  node_demoapp["Demo Workload<br/>[main.py]"]
end

subgraph group_operations["Operations UI"]
  node_dashboard["Terminal Dashboard"]
  node_statusui["Status Dashboard Page<br/>[index.html]"]
end

node_operator(("Operator"))

node_loop -->|"loads settings"| node_config
node_loop -->|"collects snapshots"| node_monitor
node_loop -->|"detects anomalies"| node_detector
node_loop -->|"classifies cause"| node_diagnosis
node_loop -->|"checks safeguards"| node_policy
node_loop -->|"executes decision"| node_remediation
node_loop -->|"verifies recovery"| node_verifier
node_loop -->|"records events"| node_audit
node_monitor -->|"queries metrics"| node_promclient
node_promclient -->|"queries PromQL"| node_prometheus
node_monitor -->|"reads cluster state"| node_k8sapi
node_monitor -->|"probes health"| node_dependency
node_monitor -->|"builds snapshots"| node_models
node_detector -->|"evaluates snapshots"| node_models
node_diagnosis -->|"uses anomaly report"| node_detector
node_diagnosis -->|"returns diagnosis"| node_models
node_policy -->|"returns decision"| node_models
node_remediation -->|"mutates workload"| node_k8sapi
node_verifier -->|"rechecks health"| node_monitor
node_verifier -->|"returns outcome"| node_models
node_audit -->|"stores audit records"| node_models
node_demoapp -->|"exposes metrics"| node_prometheus
node_loop -->|"serves dashboard page"| node_statusui
node_operator -.->|"uses status API"| node_loop
node_operator -.->|"views mission control"| node_dashboard
node_operator -.->|"injects demo faults"| node_demoapp

click node_config "https://github.com/devanshm15/healkube/blob/main/healkube/controller/config.py"
click node_loop "https://github.com/devanshm15/healkube/blob/main/healkube/controller/main.py"
click node_models "https://github.com/devanshm15/healkube/blob/main/healkube/controller/models.py"
click node_monitor "https://github.com/devanshm15/healkube/blob/main/healkube/controller/monitor.py"
click node_promclient "https://github.com/devanshm15/healkube/blob/main/healkube/controller/prometheus_client.py"
click node_detector "https://github.com/devanshm15/healkube/blob/main/healkube/controller/detector.py"
click node_diagnosis "https://github.com/devanshm15/healkube/blob/main/healkube/controller/diagnosis.py"
click node_policy "https://github.com/devanshm15/healkube/blob/main/healkube/controller/policy.py"
click node_remediation "https://github.com/devanshm15/healkube/blob/main/healkube/controller/remediation.py"
click node_verifier "https://github.com/devanshm15/healkube/blob/main/healkube/controller/verifier.py"
click node_audit "https://github.com/devanshm15/healkube/blob/main/healkube/controller/audit.py"
click node_demoapp "https://github.com/devanshm15/healkube/blob/main/healkube/app/main.py"
click node_dashboard "https://github.com/devanshm15/healkube/blob/main/healkube/controller/static/HealKubeTerminalDashboard.jsx"
click node_statusui "https://github.com/devanshm15/healkube/blob/main/healkube/controller/static/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_config,node_loop,node_models,node_detector,node_diagnosis,node_policy,node_remediation,node_verifier,node_audit toneBlue
class node_monitor,node_promclient,node_prometheus,node_k8sapi,node_dependency toneAmber
class node_demoapp toneMint
class node_dashboard,node_statusui toneRose
class node_operator toneIndigo
```

## Components

### Controller

- [Controller Config](https://github.com/devanshm15/healkube/blob/main/healkube/controller/config.py): `healkube/controller/config.py`
- [Reconciliation & API](https://github.com/devanshm15/healkube/blob/main/healkube/controller/main.py): `healkube/controller/main.py`
- [Domain Models](https://github.com/devanshm15/healkube/blob/main/healkube/controller/models.py): `healkube/controller/models.py`
- [Anomaly Detector](https://github.com/devanshm15/healkube/blob/main/healkube/controller/detector.py): `healkube/controller/detector.py`
- [Diagnosis Engine](https://github.com/devanshm15/healkube/blob/main/healkube/controller/diagnosis.py): `healkube/controller/diagnosis.py`
- [Safety Policy](https://github.com/devanshm15/healkube/blob/main/healkube/controller/policy.py): `healkube/controller/policy.py`
- [Remediation Executor](https://github.com/devanshm15/healkube/blob/main/healkube/controller/remediation.py): `healkube/controller/remediation.py`
- [Recovery Verifier](https://github.com/devanshm15/healkube/blob/main/healkube/controller/verifier.py): `healkube/controller/verifier.py`
- [Audit Logger](https://github.com/devanshm15/healkube/blob/main/healkube/controller/audit.py): `healkube/controller/audit.py`

### Observability

- [Cluster Monitor](https://github.com/devanshm15/healkube/blob/main/healkube/controller/monitor.py): `healkube/controller/monitor.py`
- [Prometheus Client](https://github.com/devanshm15/healkube/blob/main/healkube/controller/prometheus_client.py): `healkube/controller/prometheus_client.py`
- **Prometheus**
- **Kubernetes API**
- **Dependency Probe**

### Managed Workload

- [Demo Workload](https://github.com/devanshm15/healkube/blob/main/healkube/app/main.py): `healkube/app/main.py`

### Operations UI

- [Terminal Dashboard](https://github.com/devanshm15/healkube/blob/main/healkube/controller/static/HealKubeTerminalDashboard.jsx): `healkube/controller/static/HealKubeTerminalDashboard.jsx`
- [Status Dashboard Page](https://github.com/devanshm15/healkube/blob/main/healkube/controller/static/index.html): `healkube/controller/static/index.html`

### Other components

- **Operator**

## Connections

- Reconciliation & API → Controller Config: loads settings (evidence: `healkube/controller/main.py`)
- Reconciliation & API → Cluster Monitor: collects snapshots (evidence: `README.md`)
- Reconciliation & API → Anomaly Detector: detects anomalies (evidence: `README.md`)
- Reconciliation & API → Diagnosis Engine: classifies cause (evidence: `README.md`)
- Reconciliation & API → Safety Policy: checks safeguards (evidence: `README.md`)
- Reconciliation & API → Remediation Executor: executes decision (evidence: `README.md`)
- Reconciliation & API → Recovery Verifier: verifies recovery (evidence: `README.md`)
- Reconciliation & API → Audit Logger: records events (evidence: `README.md`)
- Cluster Monitor → Prometheus Client: queries metrics (evidence: `healkube/controller/monitor.py`)
- Prometheus Client → Prometheus: queries PromQL (evidence: `healkube/controller/prometheus_client.py`)
- Cluster Monitor → Kubernetes API: reads cluster state (evidence: `README.md`)
- Cluster Monitor → Dependency Probe: probes health (evidence: `healkube/controller/monitor.py`)
- Cluster Monitor → Domain Models: builds snapshots (evidence: `healkube/controller/monitor.py`)
- Anomaly Detector → Domain Models: evaluates snapshots (evidence: `healkube/controller/detector.py`)
- Diagnosis Engine → Anomaly Detector: uses anomaly report (evidence: `healkube/controller/diagnosis.py`)
- Diagnosis Engine → Domain Models: returns diagnosis (evidence: `healkube/controller/diagnosis.py`)
- Safety Policy → Domain Models: returns decision (evidence: `healkube/controller/policy.py`)
- Remediation Executor → Kubernetes API: mutates workload (evidence: `README.md`)
- Recovery Verifier → Cluster Monitor: rechecks health (evidence: `healkube/controller/verifier.py`)
- Recovery Verifier → Domain Models: returns outcome (evidence: `healkube/controller/verifier.py`)
- Audit Logger → Domain Models: stores audit records (evidence: `healkube/controller/audit.py`)
- Demo Workload → Prometheus: exposes metrics (evidence: `README.md`)
- Reconciliation & API → Status Dashboard Page: serves dashboard page (evidence: `healkube/controller/main.py`)
- Operator → Reconciliation & API: uses status API
- Operator → Terminal Dashboard: views mission control
- Operator → Demo Workload: injects demo faults