# abhaybhargav/kubernetes-langgraph-bot architecture

> Architecture diagram of the GitHub repository abhaybhargav/kubernetes-langgraph-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhaybhargav/kubernetes-langgraph-bot
- Repository: https://github.com/abhaybhargav/kubernetes-langgraph-bot

## Overview

##### Project type and purpose
- This project is a backend‐only Python application (CLI tool) designed to perform a security audit of a Kubernetes cluster.
- It uses the Langgraph framework to build and traverse a graph representation of the cluster, employs Langchain plus the OpenAI API for reasoning, and interacts directly with Kubernetes via the official Python SDK.

##### File structure
Top-level files and directories:
- graph_k8s.py      – entrypoint that kicks off the audit workflow
- state_k8s.py      – module for retrieving and normalizing Kubernetes state
- agents/           – folder containing “actor” classes that perform analysis and orchestration
– engineer.py     – an agent that drives high-level audit tasks
– expert.py       – an agent specializing in security rules and checks
– k8s_tools.py    – utility functions that wrap low-level Kubernetes Python SDK calls
- helpers.py        – shared helper functions
- pyproject.toml    – project metadata and dependencies
- .env              – stores the OpenAI API key
- uv.lock           – environment lockfile

##### README for additional insights
- The README confirms the runtime command (`uv run graph_k8s.py`) and lists external dependencies:
- Kubernetes Python SDK
- Langchain / Langgraph
- OpenAI API

##### Main components and their interactions
1. CLI Runner (graph_k8s.py)
2. State Retriever (state_k8s.py)
3. Agent Layer
– EngineerAgent (engineer.py)
– ExpertAgent (expert.py)
– K8sToolsAgent (k8s_tools.py)
4. Langgraph Engine (graph builder, traversal logic)
5. Langchain / OpenAI Service (external LLM inference)
6. Kubernetes Cluster (API server)
b. Relationships & data flow:
- User triggers the CLI Runner → reads `.env` → kicks off `graph_k8s.py`.
- CLI Runner invokes State Retriever → calls Kubernetes Python SDK → fetches live cluster resources.
- Retrieved state is transformed into a graph via Langgraph → passed to Agent Layer.
- EngineerAgent orchestrates the audit plan, delegating specific checks to ExpertAgent.
- ExpertAgent uses K8sToolsAgent to inspect resource configurations (e.g., RBAC, network policies).
- When deeper reasoning is required, agents call out to Langchain → which calls the OpenAI API.
- Results are aggregated back in the graph and output to the console or report.
c. Architectural patterns & principles:
– Modular “agent” pattern: each agent encapsulates a distinct responsibility.
– Graph-based representation of cluster state for flexible traversal.
– Clear separation between data retrieval, graph processing, agent logic, and external LLM calls.

##### Final advice
- Be exhaustive in naming each agent and module.
- Clearly which components live in “agents/” versus standalone scripts.
- Loop between Agents and the OpenAI service to illustrate recursive reasoning.
- That the Kubernetes cluster is depicted outside your application boundary.
- Provide version annotations if needed (e.g., Python 3.10+, Langchain vX.Y).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Runner Layer
    subgraph "CLI Runner"
        CLI["CLI Runner\n(graph_k8s.py)"]:::core
        ENV[".env\n(API Key)"]:::external
    end
    click CLI "https://github.com/abhaybhargav/kubernetes-langgraph-bot/blob/main/graph_k8s.py"

    %% Data Ingestion Layer
    subgraph "Data Ingestion"
        SR["State Retriever\n(state_k8s.py)"]:::core
        KTA["K8sToolsAgent\n(agents/k8s_tools.py)"]:::core
        Helpers["Shared Helpers\n(helpers.py)"]:::core
    end
    click SR "https://github.com/abhaybhargav/kubernetes-langgraph-bot/blob/main/state_k8s.py"
    click KTA "https://github.com/abhaybhargav/kubernetes-langgraph-bot/blob/main/agents/k8s_tools.py"
    click Helpers "https://github.com/abhaybhargav/kubernetes-langgraph-bot/blob/main/helpers.py"

    %% Graph Processing Layer
    subgraph "Graph Processing"
        GE["Langgraph Engine"]:::artifact
        Graph["Cluster Graph\n(data structure)"]:::artifact
    end

    %% Analysis Layer
    subgraph "Analysis"
        EA["EngineerAgent\n(agents/engineer.py)"]:::core
        ExA["ExpertAgent\n(agents/expert.py)"]:::core
    end
    click EA "https://github.com/abhaybhargav/kubernetes-langgraph-bot/blob/main/agents/engineer.py"
    click ExA "https://github.com/abhaybhargav/kubernetes-langgraph-bot/blob/main/agents/expert.py"

    %% LLM Integration Layer
    subgraph "LLM Integration"
        LC["Langchain"]:::external
        OA["OpenAI Service"]:::external
    end

    %% External Systems
    K8sAPI["Kubernetes API Server"]:::external

    %% Data Flow
    CLI -->|"reads .env"| ENV
    CLI -->|"invoke"| SR
    SR -->|"API request/response"| K8sAPI
    K8sAPI -->|"cluster state"| SR
    SR -->|"raw state"| GE
    GE -->|"build graph"| Graph
    Graph -->|"graph object"| EA
    EA -->|"audit plan"| ExA
    ExA -->|"resource inspections"| KTA
    ExA -->|"LLM prompt"| LC
    LC -->|"API call"| OA
    OA -->|"LLM response"| LC
    LC -->|"LLM result"| ExA
    ExA -->|"findings"| EA
    EA -->|"final report"| CLI

    %% Styling
    classDef core fill:#E0F7FA,stroke:#006064,color:#000;
    classDef external fill:#E8F5E9,stroke:#1B5E20,color:#000;
    classDef artifact fill:#FFF3E0,stroke:#E65100,color:#000;
```
