# hojat-gazestani/k8s-ai-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/hojat-gazestani/k8s-ai-assistant
- Repository: https://github.com/hojat-gazestani/k8s-ai-assistant

## Overview

Kubernetes AI Assistant is an interactive observability triage application. The principal workflow validates settings, connects to three MCP backends, fetches frequent firing alerts from VictoriaMetrics, lets an operator select one, and asks an agent to investigate it using metrics, Kubernetes state, and Elasticsearch logs before printing a report. The repository also includes a separate cluster-analysis agent. The README documents the MCP server roles; unsampled backend implementation details are represented only at the integration boundary.

Main entry points: [`app/main.py`](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/main.py) (Application entry), [`app/clients/mcp_client.py`](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/clients/mcp_client.py) (MCP client manager), [`app/tools/victoria_tools.py`](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/tools/victoria_tools.py) (Metrics tools), [`app/handlers/investigation_handler.py`](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/handlers/investigation_handler.py) (Alert investigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Assistant workflow"]
  node_main["Application entry<br/>[main.py]"]
  node_settings["Settings<br/>[settings.py]"]
  node_alerts["Alert selection<br/>[alert_handler.py]"]
  node_investigation["Alert investigation"]
  node_analysis["Cluster analysis"]
end

subgraph group_tools["Tool providers"]
  node_toolbase["Tool discovery<br/>[base.py]"]
  node_victoriatools["Metrics tools<br/>[victoria_tools.py]"]
  node_k8stools["Kubernetes tools<br/>[k8s_tools.py]"]
  node_estools["Log tools"]
end

subgraph group_clients["MCP connections"]
  node_manager["MCP client manager<br/>[mcp_client.py]"]
  node_victoriaconfig["VictoriaMetrics client config<br/>[victoria_metric.py]"]
  node_k8sconfig["Kubernetes client config<br/>[k8s.py]"]
  node_esconfig["Elasticsearch client config<br/>[elasticsearch.py]"]
end

subgraph group_external["External systems"]
  node_llm{{"LLM endpoint"}}
  node_victoria{{"VictoriaMetrics MCP"}}
  node_k8s{{"Kubernetes MCP"}}
  node_elasticsearch{{"Elasticsearch MCP"}}
end

node_operator(("Operator"))

node_operator -->|"starts"| node_main
node_main -->|"validates"| node_settings
node_main -->|"loads config"| node_victoriaconfig
node_main -->|"loads config"| node_k8sconfig
node_main -->|"loads config"| node_esconfig
node_main -->|"creates clients"| node_manager
node_main -->|"fetches alerts"| node_alerts
node_main -->|"starts investigation"| node_investigation
node_main -->|"creates provider"| node_victoriatools
node_main -->|"creates provider"| node_k8stools
node_main -->|"creates provider"| node_estools
node_alerts -->|"queries alerts"| node_victoriatools
node_operator -->|"selects alert"| node_alerts
node_investigation -->|"invokes agent"| node_llm
node_investigation -->|"registers tools"| node_victoriatools
node_investigation -->|"registers tools"| node_k8stools
node_investigation -->|"registers tools"| node_estools
node_analysis -->|"invokes agent"| node_llm
node_analysis -->|"registers tools"| node_victoriatools
node_analysis -->|"registers tools"| node_k8stools
node_analysis -->|"registers tools"| node_estools
node_victoriatools -->|"decorates methods"| node_toolbase
node_k8stools -->|"decorates methods"| node_toolbase
node_estools -->|"decorates methods"| node_toolbase
node_victoriatools -->|"gets MCP tools"| node_manager
node_k8stools -->|"gets MCP tools"| node_manager
node_estools -->|"gets MCP tools"| node_manager
node_manager -->|"connects via MCP"| node_victoria
node_manager -->|"connects via MCP"| node_k8s
node_manager -->|"connects via MCP"| node_elasticsearch
node_victoriaconfig -->|"configures endpoint"| node_victoria
node_k8sconfig -.->|"configures endpoint"| node_k8s
node_esconfig -->|"configures endpoint"| node_elasticsearch

click node_main "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/main.py"
click node_settings "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/config/settings.py"
click node_alerts "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/handlers/alert_handler.py"
click node_investigation "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/handlers/investigation_handler.py"
click node_analysis "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/handlers/analysis_handler.py"
click node_toolbase "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/tools/base.py"
click node_victoriatools "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/tools/victoria_tools.py"
click node_k8stools "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/tools/k8s_tools.py"
click node_estools "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/tools/elasticsearch_tools.py"
click node_manager "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/clients/mcp_client.py"
click node_victoriaconfig "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/clients/victoria_metric.py"
click node_k8sconfig "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/clients/k8s.py"
click node_esconfig "https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/clients/elasticsearch.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_main,node_settings,node_alerts,node_investigation,node_analysis toneBlue
class node_toolbase,node_victoriatools,node_k8stools,node_estools toneAmber
class node_manager,node_victoriaconfig,node_k8sconfig,node_esconfig toneMint
class node_llm,node_victoria,node_k8s,node_elasticsearch toneRose
class node_operator toneIndigo
```

## Components

### Assistant workflow

- [Application entry](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/main.py): `app/main.py`
- [Settings](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/config/settings.py): `app/config/settings.py`
- [Alert selection](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/handlers/alert_handler.py): `app/handlers/alert_handler.py`
- [Alert investigation](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/handlers/investigation_handler.py): `app/handlers/investigation_handler.py`
- [Cluster analysis](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/handlers/analysis_handler.py): `app/handlers/analysis_handler.py`

### Tool providers

- [Tool discovery](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/tools/base.py): `app/tools/base.py`
- [Metrics tools](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/tools/victoria_tools.py): `app/tools/victoria_tools.py`
- [Kubernetes tools](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/tools/k8s_tools.py): `app/tools/k8s_tools.py`
- [Log tools](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/tools/elasticsearch_tools.py): `app/tools/elasticsearch_tools.py`

### MCP connections

- [MCP client manager](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/clients/mcp_client.py): `app/clients/mcp_client.py`
- [VictoriaMetrics client config](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/clients/victoria_metric.py): `app/clients/victoria_metric.py`
- [Kubernetes client config](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/clients/k8s.py): `app/clients/k8s.py`
- [Elasticsearch client config](https://github.com/hojat-gazestani/k8s-ai-assistant/blob/main/app/clients/elasticsearch.py): `app/clients/elasticsearch.py`

### External systems

- **LLM endpoint**
- **VictoriaMetrics MCP**
- **Kubernetes MCP**
- **Elasticsearch MCP**

### Other components

- **Operator**

## Connections

- Operator → Application entry: starts (evidence: `README.md`)
- Application entry → Settings: validates (evidence: `app/main.py`)
- Application entry → VictoriaMetrics client config: loads config (evidence: `app/main.py`)
- Application entry → Kubernetes client config: loads config (evidence: `app/main.py`)
- Application entry → Elasticsearch client config: loads config (evidence: `app/main.py`)
- Application entry → MCP client manager: creates clients (evidence: `app/main.py`)
- Application entry → Alert selection: fetches alerts (evidence: `app/main.py`)
- Application entry → Alert investigation: starts investigation (evidence: `app/main.py`)
- Application entry → Metrics tools: creates provider (evidence: `app/main.py`)
- Application entry → Kubernetes tools: creates provider (evidence: `app/main.py`)
- Application entry → Log tools: creates provider (evidence: `app/main.py`)
- Alert selection → Metrics tools: queries alerts (evidence: `app/handlers/alert_handler.py`)
- Operator → Alert selection: selects alert (evidence: `app/handlers/alert_handler.py`)
- Alert investigation → LLM endpoint: invokes agent (evidence: `app/handlers/investigation_handler.py`)
- Alert investigation → Metrics tools: registers tools (evidence: `app/handlers/investigation_handler.py`)
- Alert investigation → Kubernetes tools: registers tools (evidence: `app/handlers/investigation_handler.py`)
- Alert investigation → Log tools: registers tools (evidence: `app/handlers/investigation_handler.py`)
- Cluster analysis → LLM endpoint: invokes agent (evidence: `app/handlers/analysis_handler.py`)
- Cluster analysis → Metrics tools: registers tools (evidence: `app/handlers/analysis_handler.py`)
- Cluster analysis → Kubernetes tools: registers tools (evidence: `app/handlers/analysis_handler.py`)
- Cluster analysis → Log tools: registers tools (evidence: `app/handlers/analysis_handler.py`)
- Metrics tools → Tool discovery: decorates methods (evidence: `app/tools/victoria_tools.py`)
- Kubernetes tools → Tool discovery: decorates methods (evidence: `app/tools/k8s_tools.py`)
- Log tools → Tool discovery: decorates methods (evidence: `app/tools/elasticsearch_tools.py`)
- Metrics tools → MCP client manager: gets MCP tools (evidence: `app/tools/victoria_tools.py`)
- Kubernetes tools → MCP client manager: gets MCP tools (evidence: `app/tools/k8s_tools.py`)
- Log tools → MCP client manager: gets MCP tools (evidence: `app/tools/elasticsearch_tools.py`)
- MCP client manager → VictoriaMetrics MCP: connects via MCP (evidence: `README.md`)
- MCP client manager → Kubernetes MCP: connects via MCP (evidence: `README.md`)
- MCP client manager → Elasticsearch MCP: connects via MCP (evidence: `README.md`)
- VictoriaMetrics client config → VictoriaMetrics MCP: configures endpoint (evidence: `app/clients/victoria_metric.py`)
- Kubernetes client config → Kubernetes MCP: configures endpoint
- Elasticsearch client config → Elasticsearch MCP: configures endpoint (evidence: `app/clients/elasticsearch.py`)
