# mittal122/helmsman architecture

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

- Interactive diagram: https://gitdiagram.com/mittal122/helmsman
- Repository: https://github.com/mittal122/helmsman

## Overview

Helmsman is an AI-assisted Kubernetes deployment platform with a deterministic deployment core and an advisory LLM layer. Developers submit an image, Git repository, Compose stack, or structured intake through the web console; the backend normalizes inputs and coordinates build, manifest generation, validation, scanning, deployment, and verification. Separate capabilities provide live progress, workload management, self-healing guidance, optional authentication, and durable event/audit history. Edges reflect shown imports and calls or README-documented flows; several feature modules are represented by their exact directories because their implementation was not sampled.

Main entry points: [`backend/coordinator.py`](https://github.com/mittal122/helmsman/blob/main/backend/coordinator.py) (Deploy coordinator), [`backend/main.py`](https://github.com/mittal122/helmsman/blob/main/backend/main.py) (HTTP API), [`backend/store.py`](https://github.com/mittal122/helmsman/blob/main/backend/store.py) (History and audit store), [`backend/static`](https://github.com/mittal122/helmsman/tree/main/backend/static) (Web consoles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Intake and API"]
  node_console["Web consoles"]
  node_api["HTTP API<br/>[main.py]"]
  node_intake_flow["Structured intake<br/>[intake.py]"]
  node_compose["Compose parser<br/>[compose.py]"]
end

subgraph group_deploy["Deployment lifecycle"]
  node_coordinator["Deploy coordinator<br/>[coordinator.py]"]
  node_builder["Source builder<br/>[builder.py]"]
  node_manifest["Manifest rendering<br/>[manifests.py]"]
  node_validation["Validation and scan"]
  node_deployment["Deploy and verify<br/>[deploy.py]"]
  node_monitoring["Deploy monitoring<br/>[monitor.py]"]
  node_rollback["Rollback<br/>[rollback.py]"]
end

subgraph group_advice["Advisory and recovery"]
  node_agents["Advisory agents"]
  node_agent_base["LLM client<br/>[base.py]"]
  node_diagnostics["Failure diagnostics<br/>[diagnostics.py]"]
end

subgraph group_sre["Cluster operations"]
  node_cluster["Cluster manager<br/>[cluster.py]"]
  node_portforward["Port forwarding<br/>[portforward.py]"]
end

subgraph group_platform["Identity and state"]
  node_auth["Authentication and RBAC<br/>[auth.py]"]
  node_kubeconfigs["Encrypted kubeconfigs"]
  node_eventbus["Event stream<br/>[events.py]"]
  node_store[("History and audit store<br/>[store.py]")]
end

node_developer(("Developer"))
node_cluster_service["Kubernetes cluster"]
node_llm_provider["LLM provider"]
node_postgres[("PostgreSQL")]

node_developer -->|"uses"| node_console
node_console -->|"submits requests"| node_api
node_api -->|"dispatches deployment"| node_coordinator
node_api -->|"builds and ingests"| node_intake_flow
node_api -->|"parses stacks"| node_compose
node_coordinator -->|"builds source"| node_builder
node_coordinator -->|"renders manifests"| node_manifest
node_coordinator -->|"validates and scans"| node_validation
node_coordinator -->|"deploys and verifies"| node_deployment
node_coordinator -->|"checks health"| node_monitoring
node_coordinator -->|"rolls back"| node_rollback
node_coordinator -->|"generates guidance"| node_diagnostics
node_coordinator -->|"requests advice"| node_agents
node_agents -->|"calls"| node_agent_base
node_agent_base -->|"requests completion"| node_llm_provider
node_coordinator -->|"emits progress"| node_eventbus
node_coordinator -->|"operates on"| node_cluster_service
node_api -->|"serves management"| node_cluster
node_cluster -->|"starts forwarding"| node_portforward
node_api -->|"enforces access"| node_auth
node_auth -->|"reads user records"| node_store
node_coordinator -->|"loads cluster config"| node_kubeconfigs
node_eventbus -.->|"persists event history"| node_store
node_store -->|"uses when configured"| node_postgres

click node_console "https://github.com/mittal122/helmsman/tree/main/backend/static"
click node_api "https://github.com/mittal122/helmsman/blob/main/backend/main.py"
click node_intake_flow "https://github.com/mittal122/helmsman/blob/main/backend/intake.py"
click node_compose "https://github.com/mittal122/helmsman/blob/main/backend/tools/compose.py"
click node_coordinator "https://github.com/mittal122/helmsman/blob/main/backend/coordinator.py"
click node_builder "https://github.com/mittal122/helmsman/blob/main/backend/tools/builder.py"
click node_manifest "https://github.com/mittal122/helmsman/blob/main/backend/tools/manifests.py"
click node_validation "https://github.com/mittal122/helmsman/tree/main/backend/tools"
click node_deployment "https://github.com/mittal122/helmsman/blob/main/backend/tools/deploy.py"
click node_monitoring "https://github.com/mittal122/helmsman/blob/main/backend/tools/monitor.py"
click node_rollback "https://github.com/mittal122/helmsman/blob/main/backend/tools/rollback.py"
click node_cluster "https://github.com/mittal122/helmsman/blob/main/backend/tools/cluster.py"
click node_portforward "https://github.com/mittal122/helmsman/blob/main/backend/tools/portforward.py"
click node_agents "https://github.com/mittal122/helmsman/tree/main/backend/agents"
click node_agent_base "https://github.com/mittal122/helmsman/blob/main/backend/agents/base.py"
click node_diagnostics "https://github.com/mittal122/helmsman/blob/main/backend/diagnostics.py"
click node_auth "https://github.com/mittal122/helmsman/blob/main/backend/auth.py"
click node_kubeconfigs "https://github.com/mittal122/helmsman/blob/main/backend/kubeconfig_store.py"
click node_eventbus "https://github.com/mittal122/helmsman/blob/main/backend/events.py"
click node_store "https://github.com/mittal122/helmsman/blob/main/backend/store.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_console,node_api,node_intake_flow,node_compose toneBlue
class node_coordinator,node_builder,node_manifest,node_validation,node_deployment,node_monitoring,node_rollback,node_postgres toneAmber
class node_agents,node_agent_base,node_diagnostics toneMint
class node_cluster,node_portforward toneRose
class node_auth,node_kubeconfigs,node_eventbus,node_store,node_developer,node_cluster_service,node_llm_provider toneIndigo
```

## Components

### Intake and API

- [Web consoles](https://github.com/mittal122/helmsman/tree/main/backend/static): `backend/static`
- [HTTP API](https://github.com/mittal122/helmsman/blob/main/backend/main.py): `backend/main.py`
- [Structured intake](https://github.com/mittal122/helmsman/blob/main/backend/intake.py): `backend/intake.py`
- [Compose parser](https://github.com/mittal122/helmsman/blob/main/backend/tools/compose.py): `backend/tools/compose.py`

### Deployment lifecycle

- [Deploy coordinator](https://github.com/mittal122/helmsman/blob/main/backend/coordinator.py): `backend/coordinator.py`
- [Source builder](https://github.com/mittal122/helmsman/blob/main/backend/tools/builder.py): `backend/tools/builder.py`
- [Manifest rendering](https://github.com/mittal122/helmsman/blob/main/backend/tools/manifests.py): `backend/tools/manifests.py`
- [Validation and scan](https://github.com/mittal122/helmsman/tree/main/backend/tools): `backend/tools`
- [Deploy and verify](https://github.com/mittal122/helmsman/blob/main/backend/tools/deploy.py): `backend/tools/deploy.py`
- [Deploy monitoring](https://github.com/mittal122/helmsman/blob/main/backend/tools/monitor.py): `backend/tools/monitor.py`
- [Rollback](https://github.com/mittal122/helmsman/blob/main/backend/tools/rollback.py): `backend/tools/rollback.py`

### Advisory and recovery

- [Advisory agents](https://github.com/mittal122/helmsman/tree/main/backend/agents): `backend/agents`
- [LLM client](https://github.com/mittal122/helmsman/blob/main/backend/agents/base.py): `backend/agents/base.py`
- [Failure diagnostics](https://github.com/mittal122/helmsman/blob/main/backend/diagnostics.py): `backend/diagnostics.py`

### Cluster operations

- [Cluster manager](https://github.com/mittal122/helmsman/blob/main/backend/tools/cluster.py): `backend/tools/cluster.py`
- [Port forwarding](https://github.com/mittal122/helmsman/blob/main/backend/tools/portforward.py): `backend/tools/portforward.py`

### Identity and state

- [Authentication and RBAC](https://github.com/mittal122/helmsman/blob/main/backend/auth.py): `backend/auth.py`
- [Encrypted kubeconfigs](https://github.com/mittal122/helmsman/blob/main/backend/kubeconfig_store.py): `backend/kubeconfig_store.py`
- [Event stream](https://github.com/mittal122/helmsman/blob/main/backend/events.py): `backend/events.py`
- [History and audit store](https://github.com/mittal122/helmsman/blob/main/backend/store.py): `backend/store.py`

### Other components

- **Developer**
- **Kubernetes cluster**
- **LLM provider**
- **PostgreSQL**

## Connections

- Developer → Web consoles: uses (evidence: `README.md`)
- Web consoles → HTTP API: submits requests (evidence: `README.md`)
- HTTP API → Deploy coordinator: dispatches deployment (evidence: `backend/main.py`)
- HTTP API → Structured intake: builds and ingests (evidence: `backend/main.py`)
- HTTP API → Compose parser: parses stacks (evidence: `backend/main.py`)
- Deploy coordinator → Source builder: builds source (evidence: `backend/coordinator.py`)
- Deploy coordinator → Manifest rendering: renders manifests (evidence: `backend/coordinator.py`)
- Deploy coordinator → Validation and scan: validates and scans (evidence: `backend/coordinator.py`)
- Deploy coordinator → Deploy and verify: deploys and verifies (evidence: `backend/coordinator.py`)
- Deploy coordinator → Deploy monitoring: checks health (evidence: `backend/coordinator.py`)
- Deploy coordinator → Rollback: rolls back (evidence: `backend/coordinator.py`)
- Deploy coordinator → Failure diagnostics: generates guidance (evidence: `backend/coordinator.py`)
- Deploy coordinator → Advisory agents: requests advice (evidence: `backend/coordinator.py`)
- Advisory agents → LLM client: calls (evidence: `backend/agents/stack_reviewer.py`)
- LLM client → LLM provider: requests completion (evidence: `backend/agents/base.py`)
- Deploy coordinator → Event stream: emits progress (evidence: `backend/coordinator.py`)
- Deploy coordinator → Kubernetes cluster: operates on (evidence: `README.md`)
- HTTP API → Cluster manager: serves management (evidence: `backend/main.py`)
- Cluster manager → Port forwarding: starts forwarding (evidence: `backend/tools/cluster.py`)
- HTTP API → Authentication and RBAC: enforces access (evidence: `backend/main.py`)
- Authentication and RBAC → History and audit store: reads user records (evidence: `backend/auth.py`)
- Deploy coordinator → Encrypted kubeconfigs: loads cluster config (evidence: `backend/coordinator.py`)
- Event stream → History and audit store: persists event history (evidence: `README.md`)
- History and audit store → PostgreSQL: uses when configured (evidence: `README.md`)
