# polds/kubectl-forwarder architecture

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

- Interactive diagram: https://gitdiagram.com/polds/kubectl-forwarder
- Repository: https://github.com/polds/kubectl-forwarder

## Overview

kubectl-forwarder is an interactive terminal app for creating and supervising Kubernetes service port-forwards. The user chooses a namespace, service, remote port, and local port; the app launches kubectl, monitors the tunnel, retries failures with backoff, and displays status, logs, and errors. The main internal layers are the Bubble Tea model and renderer, Kubernetes metadata lookup, and per-forward supervision. Excerpts establish these calls; unsampled details are omitted.

Main entry points: [`model.go`](https://github.com/polds/kubectl-forwarder/blob/main/model.go) (Wizard and dashboard state), [`supervisor.go`](https://github.com/polds/kubectl-forwarder/blob/main/supervisor.go) (Forward supervisor), [`kubectl.go`](https://github.com/polds/kubectl-forwarder/blob/main/kubectl.go) (Namespace and service lookup), [`main.go`](https://github.com/polds/kubectl-forwarder/blob/main/main.go) (Application entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Terminal interaction"]
  node_main["Application entry<br/>[main.go]"]
  node_model["Wizard and dashboard state<br/>[model.go]"]
  node_renderer["Terminal renderer<br/>[view.go]"]
end

subgraph group_discovery["Cluster discovery"]
  node_lookup["Namespace and service lookup<br/>[kubectl.go]"]
end

subgraph group_forwarding["Tunnel supervision"]
  node_supervisor["Forward supervisor<br/>[supervisor.go]"]
  node_forwardstate[("Forward status and logs<br/>[supervisor.go]")]
end

node_user(("User"))
node_cluster[("Kubernetes cluster")]
node_kubectl["kubectl process"]

node_user -->|"launches"| node_main
node_main -->|"initializes"| node_model
node_user -->|"operates"| node_model
node_model -->|"schedules lookups"| node_lookup
node_lookup -->|"queries metadata"| node_kubectl
node_kubectl -->|"reads services"| node_cluster
node_lookup -->|"returns results"| node_model
node_model -->|"starts or cancels"| node_supervisor
node_supervisor -->|"runs port-forward"| node_kubectl
node_kubectl -->|"forwards traffic"| node_cluster
node_supervisor -->|"updates"| node_forwardstate
node_model -->|"reads snapshots"| node_forwardstate
node_supervisor -->|"notifies changes"| node_model
node_model -->|"renders screens"| node_renderer

click node_main "https://github.com/polds/kubectl-forwarder/blob/main/main.go"
click node_model "https://github.com/polds/kubectl-forwarder/blob/main/model.go"
click node_renderer "https://github.com/polds/kubectl-forwarder/blob/main/view.go"
click node_lookup "https://github.com/polds/kubectl-forwarder/blob/main/kubectl.go"
click node_supervisor "https://github.com/polds/kubectl-forwarder/blob/main/supervisor.go"
click node_forwardstate "https://github.com/polds/kubectl-forwarder/blob/main/supervisor.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_main,node_model,node_renderer,node_user toneBlue
class node_lookup,node_cluster toneAmber
class node_supervisor,node_forwardstate toneMint
class node_kubectl toneIndigo
```

## Components

### Terminal interaction

- [Application entry](https://github.com/polds/kubectl-forwarder/blob/main/main.go): `main.go`
- [Wizard and dashboard state](https://github.com/polds/kubectl-forwarder/blob/main/model.go): `model.go`
- [Terminal renderer](https://github.com/polds/kubectl-forwarder/blob/main/view.go): `view.go`

### Cluster discovery

- [Namespace and service lookup](https://github.com/polds/kubectl-forwarder/blob/main/kubectl.go): `kubectl.go`

### Tunnel supervision

- [Forward supervisor](https://github.com/polds/kubectl-forwarder/blob/main/supervisor.go): `supervisor.go`
- [Forward status and logs](https://github.com/polds/kubectl-forwarder/blob/main/supervisor.go): `supervisor.go`

### Other components

- **User**
- **Kubernetes cluster**
- **kubectl process**

## Connections

- User → Application entry: launches
- Application entry → Wizard and dashboard state: initializes
- User → Wizard and dashboard state: operates
- Wizard and dashboard state → Namespace and service lookup: schedules lookups
- Namespace and service lookup → kubectl process: queries metadata
- kubectl process → Kubernetes cluster: reads services
- Namespace and service lookup → Wizard and dashboard state: returns results
- Wizard and dashboard state → Forward supervisor: starts or cancels
- Forward supervisor → kubectl process: runs port-forward
- kubectl process → Kubernetes cluster: forwards traffic
- Forward supervisor → Forward status and logs: updates
- Wizard and dashboard state → Forward status and logs: reads snapshots
- Forward supervisor → Wizard and dashboard state: notifies changes
- Wizard and dashboard state → Terminal renderer: renders screens