# aryannehe/klarnova architecture

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

- Interactive diagram: https://gitdiagram.com/aryannehe/klarnova
- Repository: https://github.com/aryannehe/klarnova

## Overview

Klarnova turns monitoring alerts into incidents, investigates them with a staged agent workflow, gates and executes remediation, then records outcomes for learning and knowledge-base updates. Operators can review incidents and approvals through the dashboard or API. The graph preserves README-documented capabilities even where their implementation was not sampled; edges without source-level evidence are limited to relationships explicitly described in the README.

Main entry points: [`backend/app/agents/graph.py`](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/graph.py) (Graph Orchestrator), [`backend/app/api/webhooks.py`](https://github.com/aryannehe/klarnova/blob/main/backend/app/api/webhooks.py) (Alert Webhook), [`backend/app/main.py`](https://github.com/aryannehe/klarnova/blob/main/backend/app/main.py) (Backend API Routing), [`backend/app/api/approval.py`](https://github.com/aryannehe/klarnova/blob/main/backend/app/api/approval.py) (Approval API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Alert Intake"]
  node_webhook["Alert Webhook<br/>[webhooks.py]"]
  node_incident_store[("Incident Records<br/>[domain.py]")]
  node_api_router["Backend API Routing<br/>[main.py]"]
  node_database[("Application Database<br/>[database.py]")]
end

subgraph group_agents["Agent Workflows"]
  node_graph["Graph Orchestrator<br/>[graph.py]"]
  node_investigation["Evidence Gathering<br/>[investigation.py]"]
  node_retrieval["Runbook Retrieval<br/>[retrieval.py]"]
  node_root_cause["Root Cause Diagnosis<br/>[root_cause.py]"]
  node_planning["Action Planning<br/>[planning.py]"]
  node_reporting["Incident Reporting<br/>[reporting.py]"]
end

subgraph group_operations["Safety and Remediation"]
  node_safety["Safety Gate<br/>[safety.py]"]
  node_policy["Risk Policy Engine<br/>[engine.py]"]
  node_remediation["Kubernetes Remediation<br/>[remediation.py]"]
  node_k8s_actions["Kubernetes Actions<br/>[actions.py]"]
  node_k8s_client["Kubernetes Client<br/>[client.py]"]
  node_validation["Recovery Validation<br/>[validation.py]"]
end

subgraph group_learning["Learning and Knowledge"]
  node_rag_store[("Vector Knowledge Store<br/>[store.py]")]
  node_rag_ingest["Knowledge Ingestion<br/>[ingest.py]"]
  node_writeback["Incident Write-back<br/>[writeback.py]"]
  node_bandit["Contextual Bandit<br/>[learning.py]"]
end

subgraph group_operator["Operator Experience"]
  node_approval_api["Approval API<br/>[approval.py]"]
  node_notify["Notifications<br/>[notify.py]"]
  node_dashboard["Operator Dashboard<br/>[page.tsx]"]
  node_api["Dashboard API Client<br/>[api.ts]"]
end

node_prometheus(("Prometheus / Alertmanager"))
node_operator(("Operator"))

node_prometheus -->|"posts alerts"| node_webhook
node_webhook -->|"creates incident"| node_incident_store
node_webhook -->|"invokes investigation"| node_graph
node_graph -->|"runs first"| node_investigation
node_graph -->|"runs next"| node_retrieval
node_graph -->|"runs next"| node_root_cause
node_graph -->|"runs next"| node_planning
node_graph -->|"runs last"| node_safety
node_investigation -->|"collects evidence"| node_k8s_client
node_retrieval -->|"searches documents"| node_rag_store
node_safety -.->|"checks risk"| node_policy
node_operator -->|"approves actions"| node_approval_api
node_approval_api -->|"resumes remediation"| node_graph
node_webhook -->|"invokes remediation"| node_graph
node_graph -->|"executes approved action"| node_remediation
node_remediation -.->|"applies action"| node_k8s_actions
node_k8s_actions -.->|"uses cluster client"| node_k8s_client
node_graph -->|"checks recovery"| node_validation
node_graph -->|"reports outcome"| node_reporting
node_webhook -->|"persists results"| node_database
node_webhook -->|"records outcome"| node_bandit
node_bandit -->|"uses policy"| node_policy
node_webhook -->|"writes resolved incidents"| node_writeback
node_writeback -.->|"adds knowledge"| node_rag_store
node_rag_ingest -->|"seeds collections"| node_rag_store
node_webhook -->|"sends notifications"| node_notify
node_operator -->|"reviews incidents"| node_dashboard
node_dashboard -.->|"requests data"| node_api
node_api -.->|"calls backend"| node_api_router
node_api_router -->|"routes webhook"| node_webhook
node_api_router -->|"routes approvals"| node_approval_api

click node_webhook "https://github.com/aryannehe/klarnova/blob/main/backend/app/api/webhooks.py"
click node_incident_store "https://github.com/aryannehe/klarnova/blob/main/backend/app/models/domain.py"
click node_graph "https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/graph.py"
click node_investigation "https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/investigation.py"
click node_retrieval "https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/retrieval.py"
click node_root_cause "https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/root_cause.py"
click node_planning "https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/planning.py"
click node_safety "https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/safety.py"
click node_policy "https://github.com/aryannehe/klarnova/blob/main/backend/app/policy/engine.py"
click node_approval_api "https://github.com/aryannehe/klarnova/blob/main/backend/app/api/approval.py"
click node_remediation "https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/remediation.py"
click node_k8s_actions "https://github.com/aryannehe/klarnova/blob/main/backend/app/k8s/actions.py"
click node_k8s_client "https://github.com/aryannehe/klarnova/blob/main/backend/app/k8s/client.py"
click node_validation "https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/validation.py"
click node_reporting "https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/reporting.py"
click node_rag_store "https://github.com/aryannehe/klarnova/blob/main/backend/app/rag/store.py"
click node_rag_ingest "https://github.com/aryannehe/klarnova/blob/main/backend/app/rag/ingest.py"
click node_writeback "https://github.com/aryannehe/klarnova/blob/main/backend/app/rag/writeback.py"
click node_bandit "https://github.com/aryannehe/klarnova/blob/main/backend/app/bandit/learning.py"
click node_notify "https://github.com/aryannehe/klarnova/blob/main/backend/app/services/notify.py"
click node_dashboard "https://github.com/aryannehe/klarnova/blob/main/frontend/app/(dashboard)/incidents/page.tsx"
click node_api "https://github.com/aryannehe/klarnova/blob/main/frontend/lib/api.ts"
click node_api_router "https://github.com/aryannehe/klarnova/blob/main/backend/app/main.py"
click node_database "https://github.com/aryannehe/klarnova/blob/main/backend/app/core/database.py"

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_webhook,node_incident_store,node_api_router,node_database toneBlue
class node_graph,node_investigation,node_retrieval,node_root_cause,node_planning,node_reporting toneAmber
class node_safety,node_policy,node_remediation,node_k8s_actions,node_k8s_client,node_validation toneMint
class node_rag_store,node_rag_ingest,node_writeback,node_bandit toneRose
class node_approval_api,node_notify,node_dashboard,node_api,node_prometheus,node_operator toneIndigo
```

## Components

### Alert Intake

- [Alert Webhook](https://github.com/aryannehe/klarnova/blob/main/backend/app/api/webhooks.py): `backend/app/api/webhooks.py`
- [Incident Records](https://github.com/aryannehe/klarnova/blob/main/backend/app/models/domain.py): `backend/app/models/domain.py`
- [Backend API Routing](https://github.com/aryannehe/klarnova/blob/main/backend/app/main.py): `backend/app/main.py`
- [Application Database](https://github.com/aryannehe/klarnova/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Agent Workflows

- [Graph Orchestrator](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/graph.py): `backend/app/agents/graph.py`
- [Evidence Gathering](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/investigation.py): `backend/app/agents/investigation.py`
- [Runbook Retrieval](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/retrieval.py): `backend/app/agents/retrieval.py`
- [Root Cause Diagnosis](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/root_cause.py): `backend/app/agents/root_cause.py`
- [Action Planning](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/planning.py): `backend/app/agents/planning.py`
- [Incident Reporting](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/reporting.py): `backend/app/agents/reporting.py`

### Safety and Remediation

- [Safety Gate](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/safety.py): `backend/app/agents/safety.py`
- [Risk Policy Engine](https://github.com/aryannehe/klarnova/blob/main/backend/app/policy/engine.py): `backend/app/policy/engine.py`
- [Kubernetes Remediation](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/remediation.py): `backend/app/agents/remediation.py`
- [Kubernetes Actions](https://github.com/aryannehe/klarnova/blob/main/backend/app/k8s/actions.py): `backend/app/k8s/actions.py`
- [Kubernetes Client](https://github.com/aryannehe/klarnova/blob/main/backend/app/k8s/client.py): `backend/app/k8s/client.py`
- [Recovery Validation](https://github.com/aryannehe/klarnova/blob/main/backend/app/agents/validation.py): `backend/app/agents/validation.py`

### Learning and Knowledge

- [Vector Knowledge Store](https://github.com/aryannehe/klarnova/blob/main/backend/app/rag/store.py): `backend/app/rag/store.py`
- [Knowledge Ingestion](https://github.com/aryannehe/klarnova/blob/main/backend/app/rag/ingest.py): `backend/app/rag/ingest.py`
- [Incident Write-back](https://github.com/aryannehe/klarnova/blob/main/backend/app/rag/writeback.py): `backend/app/rag/writeback.py`
- [Contextual Bandit](https://github.com/aryannehe/klarnova/blob/main/backend/app/bandit/learning.py): `backend/app/bandit/learning.py`

### Operator Experience

- [Approval API](https://github.com/aryannehe/klarnova/blob/main/backend/app/api/approval.py): `backend/app/api/approval.py`
- [Notifications](https://github.com/aryannehe/klarnova/blob/main/backend/app/services/notify.py): `backend/app/services/notify.py`
- [Operator Dashboard](https://github.com/aryannehe/klarnova/blob/main/frontend/app/(dashboard)/incidents/page.tsx): `frontend/app/(dashboard)/incidents/page.tsx`
- [Dashboard API Client](https://github.com/aryannehe/klarnova/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Other components

- **Prometheus / Alertmanager**
- **Operator**

## Connections

- Prometheus / Alertmanager → Alert Webhook: posts alerts
- Alert Webhook → Incident Records: creates incident (evidence: `backend/app/api/webhooks.py`)
- Alert Webhook → Graph Orchestrator: invokes investigation (evidence: `backend/app/api/webhooks.py`)
- Graph Orchestrator → Evidence Gathering: runs first (evidence: `backend/app/agents/graph.py`)
- Graph Orchestrator → Runbook Retrieval: runs next (evidence: `backend/app/agents/graph.py`)
- Graph Orchestrator → Root Cause Diagnosis: runs next (evidence: `backend/app/agents/graph.py`)
- Graph Orchestrator → Action Planning: runs next (evidence: `backend/app/agents/graph.py`)
- Graph Orchestrator → Safety Gate: runs last (evidence: `backend/app/agents/graph.py`)
- Evidence Gathering → Kubernetes Client: collects evidence (evidence: `backend/app/agents/investigation.py`)
- Runbook Retrieval → Vector Knowledge Store: searches documents (evidence: `backend/app/agents/retrieval.py`)
- Safety Gate → Risk Policy Engine: checks risk
- Operator → Approval API: approves actions
- Approval API → Graph Orchestrator: resumes remediation (evidence: `backend/app/api/approval.py`)
- Alert Webhook → Graph Orchestrator: invokes remediation (evidence: `backend/app/api/webhooks.py`)
- Graph Orchestrator → Kubernetes Remediation: executes approved action (evidence: `backend/app/agents/graph.py`)
- Kubernetes Remediation → Kubernetes Actions: applies action
- Kubernetes Actions → Kubernetes Client: uses cluster client
- Graph Orchestrator → Recovery Validation: checks recovery (evidence: `backend/app/agents/graph.py`)
- Graph Orchestrator → Incident Reporting: reports outcome (evidence: `backend/app/agents/graph.py`)
- Alert Webhook → Application Database: persists results (evidence: `backend/app/api/webhooks.py`)
- Alert Webhook → Contextual Bandit: records outcome (evidence: `backend/app/api/webhooks.py`)
- Contextual Bandit → Risk Policy Engine: uses policy (evidence: `backend/app/bandit/learning.py`)
- Alert Webhook → Incident Write-back: writes resolved incidents (evidence: `backend/app/api/webhooks.py`)
- Incident Write-back → Vector Knowledge Store: adds knowledge
- Knowledge Ingestion → Vector Knowledge Store: seeds collections (evidence: `backend/app/rag/ingest.py`)
- Alert Webhook → Notifications: sends notifications (evidence: `backend/app/api/webhooks.py`)
- Operator → Operator Dashboard: reviews incidents
- Operator Dashboard → Dashboard API Client: requests data
- Dashboard API Client → Backend API Routing: calls backend
- Backend API Routing → Alert Webhook: routes webhook (evidence: `backend/app/main.py`)
- Backend API Routing → Approval API: routes approvals (evidence: `backend/app/main.py`)
