# sozercan/kubectl-ai architecture

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

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

## Overview

Kubectl AI is a command-line assistant that turns a natural-language request (optionally combined with YAML piped on stdin) into Kubernetes manifests, then lets the user refine, discard, or apply them. Its main runtime path is command setup and orchestration, OpenAI completion, optional Kubernetes OpenAPI schema lookup for function calling, interactive review, and application to the configured cluster. The sampled files show these calls directly; README documents pipe input/output and configuration options. Schema lookup can use either the cluster API or a configured URL.

Main entry points: [`cmd/cli/root.go`](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/root.go) (Prompt and review), [`cmd/cli/openai.go`](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/openai.go) (Chat completion), [`cmd/cli/schema.go`](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/schema.go) (Schema retrieval), [`cmd/cli/completion.go`](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/completion.go) (Completion retries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_entry["CLI entry<br/>[root.go]"]
  node_workflow["Prompt and review<br/>[root.go]"]
end

subgraph group_generation["Manifest generation"]
  node_completion["Completion retries<br/>[completion.go]"]
  node_openai["Chat completion<br/>[openai.go]"]
end

subgraph group_schema["Schema discovery"]
  node_tools["Schema tools<br/>[functions.go]"]
  node_schemafetch["Schema retrieval<br/>[schema.go]"]
end

subgraph group_cluster["Kubernetes application"]
  node_apply["Manifest application<br/>[kubernetes.go]"]
end

node_user(("User"))
node_stdin["Piped YAML"]
node_service{{"OpenAI-compatible API"}}
node_clusterapi{{"Kubernetes API"}}
node_kubectl["kubectl OpenAPI request"]
node_specurl{{"Custom OpenAPI URL"}}
node_review[("Kubernetes cluster")]

node_user -->|"runs command"| node_entry
node_entry -->|"routes prompt"| node_workflow
node_stdin -->|"provides YAML"| node_completion
node_workflow -->|"requests completion"| node_completion
node_completion -->|"calls with prompt"| node_openai
node_openai -->|"sends chat request"| node_service
node_service -->|"returns completion"| node_openai
node_openai -->|"dispatches tool calls"| node_tools
node_tools -->|"fetches schema"| node_schemafetch
node_schemafetch -->|"requests cluster spec"| node_kubectl
node_kubectl -->|"reads OpenAPI spec"| node_clusterapi
node_schemafetch -.->|"fetches configured spec"| node_specurl
node_workflow -->|"applies approved manifest"| node_apply
node_apply -->|"applies resources"| node_review
node_user -->|"chooses review action"| node_workflow

click node_entry "https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/root.go"
click node_workflow "https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/root.go"
click node_completion "https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/completion.go"
click node_openai "https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/openai.go"
click node_tools "https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/functions.go"
click node_schemafetch "https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/schema.go"
click node_apply "https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/kubernetes.go"

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_entry,node_workflow,node_user toneBlue
class node_completion,node_openai,node_review toneAmber
class node_tools,node_schemafetch,node_service,node_clusterapi,node_kubectl,node_specurl toneMint
class node_apply toneRose
class node_stdin toneIndigo
```

## Components

### CLI workflow

- [CLI entry](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/root.go): `cmd/cli/root.go`
- [Prompt and review](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/root.go): `cmd/cli/root.go`

### Manifest generation

- [Completion retries](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/completion.go): `cmd/cli/completion.go`
- [Chat completion](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/openai.go): `cmd/cli/openai.go`

### Schema discovery

- [Schema tools](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/functions.go): `cmd/cli/functions.go`
- [Schema retrieval](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/schema.go): `cmd/cli/schema.go`

### Kubernetes application

- [Manifest application](https://github.com/sozercan/kubectl-ai/blob/main/cmd/cli/kubernetes.go): `cmd/cli/kubernetes.go`

### Other components

- **User**
- **Piped YAML**
- **OpenAI-compatible API**
- **Kubernetes API**
- **kubectl OpenAPI request**
- **Custom OpenAPI URL**
- **Kubernetes cluster**

## Connections

- User → CLI entry: runs command (evidence: `README.md`)
- CLI entry → Prompt and review: routes prompt (evidence: `cmd/cli/root.go`)
- Piped YAML → Completion retries: provides YAML (evidence: `README.md`)
- Prompt and review → Completion retries: requests completion (evidence: `cmd/cli/root.go`)
- Completion retries → Chat completion: calls with prompt (evidence: `cmd/cli/completion.go`)
- Chat completion → OpenAI-compatible API: sends chat request (evidence: `cmd/cli/openai.go`)
- OpenAI-compatible API → Chat completion: returns completion (evidence: `cmd/cli/openai.go`)
- Chat completion → Schema tools: dispatches tool calls (evidence: `cmd/cli/openai.go`)
- Schema tools → Schema retrieval: fetches schema (evidence: `cmd/cli/functions.go`)
- Schema retrieval → kubectl OpenAPI request: requests cluster spec (evidence: `cmd/cli/schema.go`)
- kubectl OpenAPI request → Kubernetes API: reads OpenAPI spec (evidence: `README.md`)
- Schema retrieval → Custom OpenAPI URL: fetches configured spec (evidence: `cmd/cli/schema.go`)
- Prompt and review → Manifest application: applies approved manifest (evidence: `cmd/cli/root.go`)
- Manifest application → Kubernetes cluster: applies resources (evidence: `cmd/cli/kubernetes.go`)
- User → Prompt and review: chooses review action (evidence: `cmd/cli/root.go`)
