# viveksinghggits/kluster architecture

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

## Overview

Kluster is a Kubernetes operator that turns a Kluster custom resource into a DigitalOcean Kubernetes cluster. The workflow starts when a user installs the CRD and submits a resource; the operator observes it, queues reconciliation, reads its token Secret, requests cluster creation, polls for readiness, and writes progress to resource status. The generated informer and lister support this control loop. The sampled implementation shows creation and readiness updates, but deletion handling only logs success; it does not show deletion of a DigitalOcean cluster.

Main entry points: [`pkg/controller/kluster.go`](https://github.com/viveksinghggits/kluster/blob/master/pkg/controller/kluster.go) (Reconcile controller), [`pkg/do/do.go`](https://github.com/viveksinghggits/kluster/blob/master/pkg/do/do.go) (DigitalOcean adapter), [`pkg/client/clientset/versioned/typed/viveksingh.dev/v1alpha1/kluster.go`](https://github.com/viveksinghggits/kluster/blob/master/pkg/client/clientset/versioned/typed/viveksingh.dev/v1alpha1/kluster.go) (Custom client), [`main.go`](https://github.com/viveksinghggits/kluster/blob/master/main.go) (Operator startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Kluster API"]
  node_crd["Kluster CRD"]
  node_spec["Kluster types<br/>[types.go]"]
  node_client["Custom client<br/>[kluster.go]"]
end

subgraph group_observe["Observation"]
  node_factory["Informer factory<br/>[factory.go]"]
  node_informer["Kluster informer<br/>[kluster.go]"]
  node_lister["Kluster lister<br/>[kluster.go]"]
end

subgraph group_reconcile["Reconciliation"]
  node_entry["Operator startup<br/>[main.go]"]
  node_controller["Reconcile controller<br/>[kluster.go]"]
  node_queue["Work queue<br/>[kluster.go]"]
end

subgraph group_cloud["Cloud integration"]
  node_do["DigitalOcean adapter<br/>[do.go]"]
end

node_user(("Kubernetes user"))
node_kube["Kubernetes API"]
node_secret[("Token Secret")]
node_digitalocean["DigitalOcean API"]

node_user -->|"installs"| node_crd
node_user -->|"submits Kluster"| node_kube
node_entry -->|"creates client"| node_client
node_entry -->|"starts factory"| node_factory
node_entry -->|"starts controller"| node_controller
node_factory -->|"provides informer"| node_informer
node_informer -->|"lists and watches"| node_client
node_controller -->|"registers handlers"| node_informer
node_controller -->|"enqueues events"| node_queue
node_controller -->|"reads cached Kluster"| node_lister
node_controller -->|"creates and polls cluster"| node_do
node_do -->|"reads token"| node_secret
node_do -->|"creates and queries"| node_digitalocean
node_controller -->|"updates status"| node_client
node_client -->|"accesses Kluster API"| node_kube
node_do -->|"fetches Secret"| node_kube
node_controller -->|"checks namespace and records events"| node_kube

click node_crd "https://github.com/viveksinghggits/kluster/blob/master/manifests/viveksingh.dev_klusters.yaml"
click node_spec "https://github.com/viveksinghggits/kluster/blob/master/pkg/apis/viveksingh.dev/v1alpha1/types.go"
click node_entry "https://github.com/viveksinghggits/kluster/blob/master/main.go"
click node_client "https://github.com/viveksinghggits/kluster/blob/master/pkg/client/clientset/versioned/typed/viveksingh.dev/v1alpha1/kluster.go"
click node_factory "https://github.com/viveksinghggits/kluster/blob/master/pkg/client/informers/externalversions/factory.go"
click node_informer "https://github.com/viveksinghggits/kluster/blob/master/pkg/client/informers/externalversions/viveksingh.dev/v1alpha1/kluster.go"
click node_lister "https://github.com/viveksinghggits/kluster/blob/master/pkg/client/listers/viveksingh.dev/v1alpha1/kluster.go"
click node_controller "https://github.com/viveksinghggits/kluster/blob/master/pkg/controller/kluster.go"
click node_queue "https://github.com/viveksinghggits/kluster/blob/master/pkg/controller/kluster.go"
click node_do "https://github.com/viveksinghggits/kluster/blob/master/pkg/do/do.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_crd,node_spec,node_client,node_user toneBlue
class node_factory,node_informer,node_lister,node_secret toneAmber
class node_entry,node_controller,node_queue,node_kube,node_digitalocean toneMint
class node_do toneRose
```

## Components

### Kluster API

- [Kluster CRD](https://github.com/viveksinghggits/kluster/blob/master/manifests/viveksingh.dev_klusters.yaml): `manifests/viveksingh.dev_klusters.yaml`
- [Kluster types](https://github.com/viveksinghggits/kluster/blob/master/pkg/apis/viveksingh.dev/v1alpha1/types.go): `pkg/apis/viveksingh.dev/v1alpha1/types.go`
- [Custom client](https://github.com/viveksinghggits/kluster/blob/master/pkg/client/clientset/versioned/typed/viveksingh.dev/v1alpha1/kluster.go): `pkg/client/clientset/versioned/typed/viveksingh.dev/v1alpha1/kluster.go`

### Observation

- [Informer factory](https://github.com/viveksinghggits/kluster/blob/master/pkg/client/informers/externalversions/factory.go): `pkg/client/informers/externalversions/factory.go`
- [Kluster informer](https://github.com/viveksinghggits/kluster/blob/master/pkg/client/informers/externalversions/viveksingh.dev/v1alpha1/kluster.go): `pkg/client/informers/externalversions/viveksingh.dev/v1alpha1/kluster.go`
- [Kluster lister](https://github.com/viveksinghggits/kluster/blob/master/pkg/client/listers/viveksingh.dev/v1alpha1/kluster.go): `pkg/client/listers/viveksingh.dev/v1alpha1/kluster.go`

### Reconciliation

- [Operator startup](https://github.com/viveksinghggits/kluster/blob/master/main.go): `main.go`
- [Reconcile controller](https://github.com/viveksinghggits/kluster/blob/master/pkg/controller/kluster.go): `pkg/controller/kluster.go`
- [Work queue](https://github.com/viveksinghggits/kluster/blob/master/pkg/controller/kluster.go): `pkg/controller/kluster.go`

### Cloud integration

- [DigitalOcean adapter](https://github.com/viveksinghggits/kluster/blob/master/pkg/do/do.go): `pkg/do/do.go`

### Other components

- **Kubernetes user**
- **Kubernetes API**
- **Token Secret**
- **DigitalOcean API**

## Connections

- Kubernetes user → Kluster CRD: installs (evidence: `README.md`)
- Kubernetes user → Kubernetes API: submits Kluster (evidence: `README.md`)
- Operator startup → Custom client: creates client (evidence: `main.go`)
- Operator startup → Informer factory: starts factory (evidence: `main.go`)
- Operator startup → Reconcile controller: starts controller (evidence: `main.go`)
- Informer factory → Kluster informer: provides informer (evidence: `pkg/client/informers/externalversions/factory.go`)
- Kluster informer → Custom client: lists and watches (evidence: `pkg/client/informers/externalversions/viveksingh.dev/v1alpha1/kluster.go`)
- Reconcile controller → Kluster informer: registers handlers (evidence: `pkg/controller/kluster.go`)
- Reconcile controller → Work queue: enqueues events (evidence: `pkg/controller/kluster.go`)
- Reconcile controller → Kluster lister: reads cached Kluster (evidence: `pkg/controller/kluster.go`)
- Reconcile controller → DigitalOcean adapter: creates and polls cluster (evidence: `pkg/controller/kluster.go`)
- DigitalOcean adapter → Token Secret: reads token (evidence: `pkg/do/do.go`)
- DigitalOcean adapter → DigitalOcean API: creates and queries (evidence: `pkg/do/do.go`)
- Reconcile controller → Custom client: updates status (evidence: `pkg/controller/kluster.go`)
- Custom client → Kubernetes API: accesses Kluster API (evidence: `pkg/client/clientset/versioned/typed/viveksingh.dev/v1alpha1/kluster.go`)
- DigitalOcean adapter → Kubernetes API: fetches Secret (evidence: `pkg/do/do.go`)
- Reconcile controller → Kubernetes API: checks namespace and records events (evidence: `pkg/controller/kluster.go`)
