# maniacbeast20/kubenexus-v2 architecture

> Architecture diagram of the GitHub repository maniacbeast20/kubenexus-v2, 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/maniacbeast20/kubenexus-v2
- Repository: https://github.com/maniacbeast20/kubenexus-v2

## Overview

KubeNexus is a local natural-language Kubernetes CLI. The main workflow accepts a user request, intercepts sensitive input, parses it with a local Ollama model, validates and applies guardrails, then routes the intent to a Kubernetes operation. Deploy, workload management, observation, cleanup, and rollback are distinct execution stages; dry-run and destructive confirmation are safety branches. The audit log supports history and rollback. Relationships are based on README workflow statements and the shown source/index references; unsampled dispatch details are not inferred beyond those links.

Main entry points: [`kubenxs/main.py`](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/main.py) (CLI workflow), [`kubenxs/pillars/rollback.py`](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/rollback.py) (Rollback pillar), [`kubenxs/action_log.py`](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/action_log.py) (Action log), [`kubenxs/parser.py`](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/parser.py) (Intent parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request handling"]
  node_cli["CLI workflow<br/>[main.py]"]
  node_parser["Intent parser<br/>[parser.py]"]
end

subgraph group_safety["Safety and policy"]
  node_interceptor["Secret interceptor<br/>[interceptor.py]"]
  node_validator["Intent validator<br/>[validator.py]"]
  node_guardrails["Policy guardrails<br/>[guardrails.py]"]
  node_config["Policy config<br/>[config.py]"]
  node_dryrun["Dry-run preview<br/>[dry_run.py]"]
  node_confirm["Destructive confirmation<br/>[confirm.py]"]
end

subgraph group_operations["Kubernetes operations"]
  node_deploy["Deploy pillar<br/>[deploy.py]"]
  node_manage["Workload management<br/>[manage.py]"]
  node_observe["Cluster observation<br/>[observe.py]"]
  node_cleanup["Cleanup pillar<br/>[cleanup.py]"]
  node_rollback["Rollback pillar<br/>[rollback.py]"]
end

subgraph group_audit["Audit and history"]
  node_actionlog[("Action log<br/>[action_log.py]")]
  node_history["History viewer<br/>[main.py]"]
end

node_user(("CLI user"))
node_ollama["Local Ollama"]
node_kubectl["kubectl"]

node_user -->|"submits request"| node_cli
node_cli -->|"scans input"| node_interceptor
node_cli -->|"sends clean prompt"| node_parser
node_parser -->|"requests parsing"| node_ollama
node_cli -->|"validates intent"| node_validator
node_cli -->|"checks policy"| node_guardrails
node_guardrails -->|"loads policy"| node_config
node_cli -->|"previews intent"| node_dryrun
node_cli -->|"requests confirmation"| node_confirm
node_cli -->|"routes deploy"| node_deploy
node_cli -->|"routes mutations"| node_manage
node_cli -->|"routes inspection"| node_observe
node_cli -->|"routes cleanup"| node_cleanup
node_cli -->|"routes rollback"| node_rollback
node_deploy -->|"applies manifests"| node_kubectl
node_manage -->|"runs mutations"| node_kubectl
node_observe -->|"reads cluster"| node_kubectl
node_cleanup -->|"deletes resources"| node_kubectl
node_rollback -->|"restores workload"| node_kubectl
node_cli -->|"records actions"| node_actionlog
node_rollback -->|"looks up snapshots"| node_actionlog
node_cli -->|"serves history"| node_history
node_history -->|"filters entries"| node_actionlog

click node_cli "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/main.py"
click node_interceptor "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/interceptor.py"
click node_parser "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/parser.py"
click node_validator "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/validator.py"
click node_guardrails "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/guardrails.py"
click node_config "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/config.py"
click node_dryrun "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/dry_run.py"
click node_confirm "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/confirm.py"
click node_deploy "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/deploy.py"
click node_manage "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/manage.py"
click node_observe "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/observe.py"
click node_cleanup "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/cleanup.py"
click node_rollback "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/rollback.py"
click node_actionlog "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/action_log.py"
click node_history "https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/main.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_cli,node_parser,node_user toneBlue
class node_interceptor,node_validator,node_guardrails,node_config,node_dryrun,node_confirm toneAmber
class node_deploy,node_manage,node_observe,node_cleanup,node_rollback toneMint
class node_actionlog,node_history toneRose
class node_ollama,node_kubectl toneIndigo
```

## Components

### Request handling

- [CLI workflow](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/main.py): `kubenxs/main.py`
- [Intent parser](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/parser.py): `kubenxs/parser.py`

### Safety and policy

- [Secret interceptor](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/interceptor.py): `kubenxs/interceptor.py`
- [Intent validator](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/validator.py): `kubenxs/validator.py`
- [Policy guardrails](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/guardrails.py): `kubenxs/guardrails.py`
- [Policy config](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/config.py): `kubenxs/config.py`
- [Dry-run preview](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/dry_run.py): `kubenxs/dry_run.py`
- [Destructive confirmation](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/confirm.py): `kubenxs/confirm.py`

### Kubernetes operations

- [Deploy pillar](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/deploy.py): `kubenxs/pillars/deploy.py`
- [Workload management](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/manage.py): `kubenxs/pillars/manage.py`
- [Cluster observation](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/observe.py): `kubenxs/pillars/observe.py`
- [Cleanup pillar](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/cleanup.py): `kubenxs/pillars/cleanup.py`
- [Rollback pillar](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/pillars/rollback.py): `kubenxs/pillars/rollback.py`

### Audit and history

- [Action log](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/action_log.py): `kubenxs/action_log.py`
- [History viewer](https://github.com/maniacbeast20/kubenexus-v2/blob/main/kubenxs/main.py): `kubenxs/main.py`

### Other components

- **CLI user**
- **Local Ollama**
- **kubectl**

## Connections

- CLI user → CLI workflow: submits request (evidence: `README.md`)
- CLI workflow → Secret interceptor: scans input (evidence: `README.md`)
- CLI workflow → Intent parser: sends clean prompt (evidence: `README.md`)
- Intent parser → Local Ollama: requests parsing (evidence: `README.md`)
- CLI workflow → Intent validator: validates intent (evidence: `README.md`)
- CLI workflow → Policy guardrails: checks policy (evidence: `kubenxs/main.py`)
- Policy guardrails → Policy config: loads policy (evidence: `kubenxs/guardrails.py`)
- CLI workflow → Dry-run preview: previews intent (evidence: `kubenxs/main.py`)
- CLI workflow → Destructive confirmation: requests confirmation (evidence: `kubenxs/main.py`)
- CLI workflow → Deploy pillar: routes deploy (evidence: `README.md`)
- CLI workflow → Workload management: routes mutations (evidence: `README.md`)
- CLI workflow → Cluster observation: routes inspection (evidence: `README.md`)
- CLI workflow → Cleanup pillar: routes cleanup (evidence: `README.md`)
- CLI workflow → Rollback pillar: routes rollback (evidence: `README.md`)
- Deploy pillar → kubectl: applies manifests (evidence: `kubenxs/pillars/deploy.py`)
- Workload management → kubectl: runs mutations (evidence: `kubenxs/pillars/manage.py`)
- Cluster observation → kubectl: reads cluster (evidence: `kubenxs/pillars/observe.py`)
- Cleanup pillar → kubectl: deletes resources (evidence: `kubenxs/pillars/cleanup.py`)
- Rollback pillar → kubectl: restores workload (evidence: `kubenxs/pillars/rollback.py`)
- CLI workflow → Action log: records actions (evidence: `README.md`)
- Rollback pillar → Action log: looks up snapshots (evidence: `kubenxs/pillars/rollback.py`)
- CLI workflow → History viewer: serves history (evidence: `README.md`)
- History viewer → Action log: filters entries (evidence: `kubenxs/main.py`)
