# blackzu/k8s-troubleshooting-agent architecture

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

- Interactive diagram: https://gitdiagram.com/blackzu/k8s-troubleshooting-agent
- Repository: https://github.com/blackzu/k8s-troubleshooting-agent

## Overview

AI Kubernetes Agent is a web product intended to let users request Kubernetes troubleshooting and view an AI-generated diagnosis. The documented path runs from the Next.js frontend through a FastAPI orchestrator to Kubernetes inspection and AI reasoning. The implementation is still a foundation: the backend currently registers only a health endpoint, while investigation, pod inspection, and cluster reasoning are empty stubs. Dashed links represent the README’s intended workflow, not verified runtime calls; frontend wiring beyond the shown provider setup is not established by the excerpts.

Main entry points: [`backend/main.py`](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/main.py) (FastAPI app), [`backend/services/investigation.py`](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/services/investigation.py) (Investigation service), [`backend/ai/reasoning.py`](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/ai/reasoning.py) (Cluster reasoning), [`frontend/components/HomePage.tsx`](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/components/HomePage.tsx) (Home page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web frontend"]
  node_home["Home page<br/>[HomePage.tsx]"]
  node_investigate["Investigate control"]
  node_health_ui["Health hook<br/>[useHealth.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_app_shell["App shell<br/>[layout.tsx]"]
  node_query_provider["Query provider<br/>[providers.tsx]"]
end

subgraph group_backend["Backend service"]
  node_backend_app["FastAPI app<br/>[main.py]"]
  node_health_route["Health route<br/>[health.py]"]
  node_health_schema["Health schema<br/>[schemas.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_logging["Logging setup<br/>[logging.py]"]
end

subgraph group_diagnosis["Diagnosis capabilities"]
  node_investigation["Investigation service<br/>[investigation.py]"]
  node_pod_inspection["Pod inspection<br/>[pods.py]"]
  node_reasoning["Cluster reasoning<br/>[reasoning.py]"]
  node_diagnosis_result["Root cause and fix"]
end

node_user(("Troubleshooting user"))
node_kubernetes{{"Kubernetes cluster"}}
node_llm{{"OpenRouter LLM"}}

node_user -.->|"opens"| node_home
node_home -.->|"offers"| node_investigate
node_investigate -.->|"requests investigation"| node_api_client
node_api_client -.->|"calls backend"| node_backend_app
node_backend_app -->|"registers"| node_health_route
node_backend_app -->|"configures CORS"| node_settings
node_backend_app -->|"sets up"| node_logging
node_health_route -->|"returns"| node_health_schema
node_app_shell -->|"wraps children"| node_query_provider
node_backend_app -.->|"would orchestrate"| node_investigation
node_investigation -.->|"would inspect"| node_pod_inspection
node_investigation -.->|"would request analysis"| node_reasoning
node_pod_inspection -.->|"would inspect"| node_kubernetes
node_reasoning -.->|"would use"| node_llm
node_reasoning -.->|"would produce"| node_diagnosis_result
node_diagnosis_result -.->|"would display"| node_home
node_health_ui -.->|"uses"| node_api_client

click node_home "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/components/HomePage.tsx"
click node_investigate "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/components/InvestigateButton.tsx"
click node_health_ui "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/hooks/useHealth.ts"
click node_api_client "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/services/api.ts"
click node_app_shell "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/app/layout.tsx"
click node_query_provider "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/app/providers.tsx"
click node_backend_app "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/main.py"
click node_health_route "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/api/health.py"
click node_health_schema "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/models/schemas.py"
click node_settings "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/core/config.py"
click node_logging "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/core/logging.py"
click node_investigation "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/services/investigation.py"
click node_pod_inspection "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/kubernetes/pods.py"
click node_reasoning "https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/ai/reasoning.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_home,node_investigate,node_health_ui,node_api_client,node_app_shell,node_query_provider,node_user toneBlue
class node_backend_app,node_health_route,node_health_schema,node_settings,node_logging toneAmber
class node_investigation,node_pod_inspection,node_reasoning,node_diagnosis_result,node_llm toneMint
class node_kubernetes toneIndigo
```

## Components

### Web frontend

- [Home page](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/components/HomePage.tsx): `frontend/components/HomePage.tsx`
- [Investigate control](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/components/InvestigateButton.tsx): `frontend/components/InvestigateButton.tsx`
- [Health hook](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/hooks/useHealth.ts): `frontend/hooks/useHealth.ts`
- [API client](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/services/api.ts): `frontend/services/api.ts`
- [App shell](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/app/layout.tsx): `frontend/app/layout.tsx`
- [Query provider](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/frontend/app/providers.tsx): `frontend/app/providers.tsx`

### Backend service

- [FastAPI app](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/main.py): `backend/main.py`
- [Health route](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/api/health.py): `backend/api/health.py`
- [Health schema](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/models/schemas.py): `backend/models/schemas.py`
- [Runtime settings](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/core/config.py): `backend/core/config.py`
- [Logging setup](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/core/logging.py): `backend/core/logging.py`

### Diagnosis capabilities

- [Investigation service](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/services/investigation.py): `backend/services/investigation.py`
- [Pod inspection](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/kubernetes/pods.py): `backend/kubernetes/pods.py`
- [Cluster reasoning](https://github.com/blackzu/k8s-troubleshooting-agent/blob/main/backend/ai/reasoning.py): `backend/ai/reasoning.py`
- **Root cause and fix**

### Other components

- **Troubleshooting user**
- **Kubernetes cluster**
- **OpenRouter LLM**

## Connections

- Troubleshooting user → Home page: opens (evidence: `README.md`)
- Home page → Investigate control: offers (evidence: `README.md`)
- Investigate control → API client: requests investigation (evidence: `README.md`)
- API client → FastAPI app: calls backend (evidence: `README.md`)
- FastAPI app → Health route: registers (evidence: `backend/main.py`)
- FastAPI app → Runtime settings: configures CORS (evidence: `backend/main.py`)
- FastAPI app → Logging setup: sets up (evidence: `backend/main.py`)
- Health route → Health schema: returns (evidence: `backend/api/health.py`)
- App shell → Query provider: wraps children (evidence: `frontend/app/layout.tsx`)
- FastAPI app → Investigation service: would orchestrate (evidence: `README.md`)
- Investigation service → Pod inspection: would inspect (evidence: `README.md`)
- Investigation service → Cluster reasoning: would request analysis (evidence: `README.md`)
- Pod inspection → Kubernetes cluster: would inspect (evidence: `README.md`)
- Cluster reasoning → OpenRouter LLM: would use (evidence: `README.md`)
- Cluster reasoning → Root cause and fix: would produce (evidence: `README.md`)
- Root cause and fix → Home page: would display (evidence: `README.md`)
- Health hook → API client: uses
