# mrankitvish/ai-agent-kubectl architecture

> Architecture diagram of the GitHub repository mrankitvish/ai-agent-kubectl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrankitvish/ai-agent-kubectl
- Repository: https://github.com/mrankitvish/ai-agent-kubectl

## Overview

##### Project type and purpose
- This is a backend microservice built with FastAPI. Its purpose is to accept natural-language queries, convert them to kubectl commands using the OpenAI API, optionally execute those commands on a Kubernetes cluster, and return results along with timing/validation metadata.

##### File structure
- Top-level files:
- app.py – the FastAPI application entry point
- requirements.txt – dependencies (FastAPI, OpenAI, cachetools, asyncio, Prometheus client, etc.)
- Dockerfile & docker-compose.yml – containerization and local orchestration
- .env-sample – environment variables (API_AUTH_KEY, OPENAI_API_KEY, RATE_LIMIT, CACHE_TTL)
- No frontend directory; all logic lives in Python modules referenced by app.py (likely in the same folder or imported).

##### Extract additional insights from README
- Features: command conversion, safety validation, caching (TTLCache), rate limiting, Prometheus metrics
- API: two POST endpoints (/kubectl-command and /execute) with separate request/response schemas
- Architecture section lists five layers:
1. API Layer (FastAPI)
2. Service Layer (business rules)
3. LLM Integration (OpenAI)
4. Caching Layer (TTLCache)
5. Execution Layer (async subprocess)

a. Main components:
- Client (curl/HTTP client or UI)
- API Layer (FastAPI)
- Authentication & Rate Limiter
- Service Layer
- LLM Integration (external OpenAI API)
- Caching Layer (in-memory TTLCache)
- Execution Layer (async subprocess invoking kubectl)
- Metrics & Monitoring (Prometheus client)
- Environment & Config (.env variables)
- Containerization (Docker, docker-compose)
b. Relationships & interactions:
1. Client → API Layer: sends POST /kubectl-command or /execute with API key
2. API Layer → Auth & Rate Limiter: verify X-API-Key, enforce RATE_LIMIT
3. API Layer → Service Layer: route request to generate or execute service
4. Service Layer:
- For generation: check Cache → if miss call LLM Integration → store in Cache
- For execution: validate command safety → call Execution Layer
5. LLM Integration ↔ OpenAI API (HTTPS)
6. Execution Layer → subprocess kubectl → Kubernetes cluster (stdout/stderr)
7. All layers emit metrics → Prometheus registry
8. Docker container runs app with environment from .env
c. Architectural patterns & principles:
- Clean architecture (layered separation)
- Single responsibility: split generate vs execute endpoints
- Externalize configuration via environment variables
- Observable: Prometheus metrics, timing metadata
- Safe fallback: caching to reduce LLM calls, validation before execution
d. Key technologies:
- FastAPI (web framework)
- cachetools.TTLCache (caching)
- Asyncio & subprocess (command execution)
- OpenAI Python SDK (LLM)
- Prometheus client (metrics)
- Docker & docker-compose (deployment)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client\n(curl/HTTP)"]:::client
    subgraph "Docker Container"
        direction TB
        Env["Environment & Config"]:::config
        API["API Layer\nFastAPI"]:::internal
        AuthLimiter["Authentication & Rate Limiter"]:::internal
        Service["Service Layer\nBusiness Logic"]:::internal
        Cache["Caching Layer\nTTLCache"]:::internal
        LLM["LLM Integration\nOpenAI SDK"]:::internal
        Executor["Execution Layer\nSubprocess Executor"]:::internal
    end
    Client -->|HTTP POST| API:::http
    API -->|validate key| AuthLimiter:::http
    AuthLimiter -->|forward request| Service:::internal
    Service -->|check cache| Cache:::internal
    Cache -->|cache miss| LLM:::externalCall
    LLM -->|return command| Service:::internal
    Service -->|execute command| Executor:::externalCall
    Executor -->|kubectl cmd| KubeCluster["Kubernetes Cluster"]:::externalCall
    LLM -->|API call| OpenAI["OpenAI API"]:::externalCall
    API -->|emit metrics| Prometheus["Prometheus\n(client)"]:::metrics
    AuthLimiter -->|emit metrics| Prometheus
    Service -->|emit metrics| Prometheus
    Cache -->|emit metrics| Prometheus
    LLM -->|emit metrics| Prometheus
    Executor -->|emit metrics| Prometheus

    subgraph "Project Artifacts"
        Dependencies["Dependencies\n(requirements.txt)"]:::artifact
        Container["Containerization\n(Dockerfile)"]:::artifact
        Orchestration["Local Orchestration\n(docker-compose.yml)"]:::artifact
        Env
        DiagramAsset["Architecture Diagram\n(assets/diagram.svg)"]:::artifact
        Documentation["Project Documentation\n(readme.md)"]:::artifact
        VCSIgnore["VCS Ignore\n(.gitignore)"]:::artifact
    end

    click API "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/app.py"
    click AuthLimiter "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/app.py"
    click Service "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/app.py"
    click Cache "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/app.py"
    click LLM "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/app.py"
    click Executor "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/app.py"
    click Prometheus "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/app.py"
    click Env "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/.env-sample"
    click Container "https://github.com/mrankitvish/ai-agent-kubectl/tree/master/Dockerfile"
    click Orchestration "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/docker-compose.yml"
    click Dependencies "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/requirements.txt"
    click DiagramAsset "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/assets/diagram.svg"
    click Documentation "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/readme.md"
    click VCSIgnore "https://github.com/mrankitvish/ai-agent-kubectl/blob/master/.gitignore"

    classDef client fill:#D3EFFF,stroke:#0366d6,color:#0366d6
    classDef http stroke:#0366d6,stroke-width:2px
    classDef internal fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef externalCall fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef metrics fill:#F5F5F5,stroke:#9E9E9E,color:#616161,stroke-dasharray:5 5
    classDef config fill:#E1F5FE,stroke:#0288D1,color:#01579B
    classDef artifact fill:#eeeeee,stroke:#424242,color:#424242
```
