# dsx-ai-factory/nvke architecture

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

- Interactive diagram: https://gitdiagram.com/dsx-ai-factory/nvke
- Repository: https://github.com/dsx-ai-factory/nvke

## Overview

NVKE is a self-hosted Kubernetes management plane for provisioning and operating isolated workload clusters on operator-owned infrastructure. The main operator workflow bootstraps a management cluster, installs NVKE services, then uses `nvkectl` or the API to create clusters and manage their node pools; customers access workload clusters through Kubernetes. The graph preserves the documented infrastructure-provider, node-identity, and node-agent capabilities. Some subsystems are represented by their exact source directories because their implementation was not sampled; uncertain connections are omitted.

Main entry points: [`controller/cmd/worker/main.go`](https://github.com/dsx-ai-factory/nvke/blob/main/controller/cmd/worker/main.go) (Controller worker), [`controller/internal/server`](https://github.com/dsx-ai-factory/nvke/tree/main/controller/internal/server) (Management API), [`agent/cmd/agent/main.go`](https://github.com/dsx-ai-factory/nvke/blob/main/agent/cmd/agent/main.go) (Node agent), [`management-engine/controllers/nvkecluster_controller.go`](https://github.com/dsx-ai-factory/nvke/blob/main/management-engine/controllers/nvkecluster_controller.go) (Cluster reconciler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Management Bootstrap"]
  node_nvkectl["nvkectl"]
  node_bootstrap_engine["Seed cluster<br/>[bootstrapengine.go]"]
  node_controller_deploy["Service deployment"]
end

subgraph group_management["Management Plane"]
  node_worker["Controller worker<br/>[main.go]"]
  node_management_api["Management API"]
  node_cluster_controller["Cluster reconciler"]
  node_management_client["Controller API client<br/>[client.go]"]
  node_fake_api["Fake controller API<br/>[server.go]"]
  node_cluster_state[("Cluster state")]
end

subgraph group_provisioning["Cluster Provisioning"]
  node_capi_provider["Provisioned provider"]
  node_nico_sim["NICo simulator<br/>[engine.go]"]
end

subgraph group_node["Node Operations"]
  node_node_agent["Node agent<br/>[main.go]"]
  node_agent_stream["Agent streaming client<br/>[main.go]"]
  node_agent_upgrade["Agent upgrades"]
end

subgraph group_access["Identity And Access"]
  node_bootstrap_auth["Bootstrap authorization"]
  node_tenant_access["Tenant access<br/>[controller.go]"]
  node_teleport_tokens["Teleport tokens<br/>[controller.go]"]
  node_authz_client["Authorization client<br/>[client.go]"]
end

node_operator(("Platform operator"))
node_nico["NICo infrastructure"]
node_cluster_api["Cluster API"]
node_customer(("Cluster customer"))
node_workload_kubernetes["Workload Kubernetes"]

node_operator -->|"runs commands"| node_nvkectl
node_nvkectl -->|"bootstraps seed"| node_bootstrap_engine
node_bootstrap_engine -->|"enables deployment"| node_controller_deploy
node_operator -->|"requests clusters"| node_management_api
node_nvkectl -->|"manages clusters"| node_management_api
node_worker -.->|"persists state"| node_cluster_state
node_cluster_controller -->|"calls API"| node_management_client
node_management_client -->|"sends requests"| node_management_api
node_fake_api -->|"implements API"| node_management_api
node_worker -.->|"starts controller"| node_bootstrap_auth
node_worker -.->|"starts controller"| node_agent_upgrade
node_worker -.->|"starts controller"| node_tenant_access
node_worker -.->|"starts controller"| node_teleport_tokens
node_cluster_controller -.->|"creates machines"| node_capi_provider
node_capi_provider -->|"provisions machines"| node_nico
node_nico_sim -.->|"simulates provisioning"| node_nico
node_cluster_controller -->|"drives lifecycle"| node_cluster_api
node_cluster_api -->|"runs on nodes"| node_node_agent
node_agent_upgrade -->|"upgrades agent"| node_node_agent
node_node_agent -->|"joins cluster"| node_workload_kubernetes
node_customer -->|"uses kubectl"| node_workload_kubernetes
node_bootstrap_auth -.->|"authorizes bootstrap"| node_workload_kubernetes
node_tenant_access -->|"publishes kubeconfig"| node_workload_kubernetes
node_teleport_tokens -.->|"checks node identity"| node_nico
node_authz_client -.->|"authorizes requests"| node_management_api
node_agent_stream -.->|"streams agent data"| node_node_agent

click node_nvkectl "https://github.com/dsx-ai-factory/nvke/tree/main/cli/internal/nvkectl"
click node_bootstrap_engine "https://github.com/dsx-ai-factory/nvke/blob/main/cli/internal/bootstrap/engine/bootstrapengine.go"
click node_controller_deploy "https://github.com/dsx-ai-factory/nvke/blob/main/cli/internal/bootstrap/controllerdeploy/controllerdeploy.go"
click node_worker "https://github.com/dsx-ai-factory/nvke/blob/main/controller/cmd/worker/main.go"
click node_management_api "https://github.com/dsx-ai-factory/nvke/tree/main/controller/internal/server"
click node_cluster_controller "https://github.com/dsx-ai-factory/nvke/blob/main/management-engine/controllers/nvkecluster_controller.go"
click node_management_client "https://github.com/dsx-ai-factory/nvke/blob/main/management-engine/internal/nvkecontroller/client.go"
click node_fake_api "https://github.com/dsx-ai-factory/nvke/blob/main/management-engine/internal/fake/server.go"
click node_capi_provider "https://github.com/dsx-ai-factory/nvke/blob/main/cluster-api-provider-provisioned/controllers/machine_controller.go"
click node_node_agent "https://github.com/dsx-ai-factory/nvke/blob/main/agent/cmd/agent/main.go"
click node_agent_stream "https://github.com/dsx-ai-factory/nvke/blob/main/agent/sample-clients/streaming-script/main.go"
click node_agent_upgrade "https://github.com/dsx-ai-factory/nvke/blob/main/controller/internal/controllers/controlplane/agent_upgrade_controller.go"
click node_nico_sim "https://github.com/dsx-ai-factory/nvke/blob/main/controller/nico-sim/internal/lifecycle/engine.go"
click node_bootstrap_auth "https://github.com/dsx-ai-factory/nvke/blob/main/controller/internal/controllers/bootstrap/bootstrap_authorization_controller.go"
click node_tenant_access "https://github.com/dsx-ai-factory/nvke/blob/main/controller/internal/controllers/tenantaccess/controller.go"
click node_teleport_tokens "https://github.com/dsx-ai-factory/nvke/blob/main/controller/internal/controllers/teleporttoken/controller.go"
click node_authz_client "https://github.com/dsx-ai-factory/nvke/blob/main/auth/authz/client.go"
click node_cluster_state "https://github.com/dsx-ai-factory/nvke/tree/main/controller/internal/db"

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_nvkectl,node_bootstrap_engine,node_controller_deploy toneBlue
class node_worker,node_management_api,node_cluster_controller,node_management_client,node_fake_api,node_cluster_state toneAmber
class node_capi_provider,node_nico_sim,node_cluster_api toneMint
class node_node_agent,node_agent_stream,node_agent_upgrade toneRose
class node_bootstrap_auth,node_tenant_access,node_teleport_tokens,node_authz_client,node_operator,node_nico,node_customer,node_workload_kubernetes toneIndigo
```

## Components

### Management Bootstrap

- [nvkectl](https://github.com/dsx-ai-factory/nvke/tree/main/cli/internal/nvkectl): `cli/internal/nvkectl`
- [Seed cluster](https://github.com/dsx-ai-factory/nvke/blob/main/cli/internal/bootstrap/engine/bootstrapengine.go): `cli/internal/bootstrap/engine/bootstrapengine.go`
- [Service deployment](https://github.com/dsx-ai-factory/nvke/blob/main/cli/internal/bootstrap/controllerdeploy/controllerdeploy.go): `cli/internal/bootstrap/controllerdeploy/controllerdeploy.go`

### Management Plane

- [Controller worker](https://github.com/dsx-ai-factory/nvke/blob/main/controller/cmd/worker/main.go): `controller/cmd/worker/main.go`
- [Management API](https://github.com/dsx-ai-factory/nvke/tree/main/controller/internal/server): `controller/internal/server`
- [Cluster reconciler](https://github.com/dsx-ai-factory/nvke/blob/main/management-engine/controllers/nvkecluster_controller.go): `management-engine/controllers/nvkecluster_controller.go`
- [Controller API client](https://github.com/dsx-ai-factory/nvke/blob/main/management-engine/internal/nvkecontroller/client.go): `management-engine/internal/nvkecontroller/client.go`
- [Fake controller API](https://github.com/dsx-ai-factory/nvke/blob/main/management-engine/internal/fake/server.go): `management-engine/internal/fake/server.go`
- [Cluster state](https://github.com/dsx-ai-factory/nvke/tree/main/controller/internal/db): `controller/internal/db`

### Cluster Provisioning

- [Provisioned provider](https://github.com/dsx-ai-factory/nvke/blob/main/cluster-api-provider-provisioned/controllers/machine_controller.go): `cluster-api-provider-provisioned/controllers/machine_controller.go`
- [NICo simulator](https://github.com/dsx-ai-factory/nvke/blob/main/controller/nico-sim/internal/lifecycle/engine.go): `controller/nico-sim/internal/lifecycle/engine.go`

### Node Operations

- [Node agent](https://github.com/dsx-ai-factory/nvke/blob/main/agent/cmd/agent/main.go): `agent/cmd/agent/main.go`
- [Agent streaming client](https://github.com/dsx-ai-factory/nvke/blob/main/agent/sample-clients/streaming-script/main.go): `agent/sample-clients/streaming-script/main.go`
- [Agent upgrades](https://github.com/dsx-ai-factory/nvke/blob/main/controller/internal/controllers/controlplane/agent_upgrade_controller.go): `controller/internal/controllers/controlplane/agent_upgrade_controller.go`

### Identity And Access

- [Bootstrap authorization](https://github.com/dsx-ai-factory/nvke/blob/main/controller/internal/controllers/bootstrap/bootstrap_authorization_controller.go): `controller/internal/controllers/bootstrap/bootstrap_authorization_controller.go`
- [Tenant access](https://github.com/dsx-ai-factory/nvke/blob/main/controller/internal/controllers/tenantaccess/controller.go): `controller/internal/controllers/tenantaccess/controller.go`
- [Teleport tokens](https://github.com/dsx-ai-factory/nvke/blob/main/controller/internal/controllers/teleporttoken/controller.go): `controller/internal/controllers/teleporttoken/controller.go`
- [Authorization client](https://github.com/dsx-ai-factory/nvke/blob/main/auth/authz/client.go): `auth/authz/client.go`

### Other components

- **Platform operator**
- **NICo infrastructure**
- **Cluster API**
- **Cluster customer**
- **Workload Kubernetes**

## Connections

- Platform operator → nvkectl: runs commands (evidence: `README.md`)
- nvkectl → Seed cluster: bootstraps seed (evidence: `cli/internal/bootstrap/engine/bootstrapengine.go`)
- Seed cluster → Service deployment: enables deployment (evidence: `cli/internal/bootstrap/controllerdeploy/controllerdeploy.go`)
- Platform operator → Management API: requests clusters (evidence: `README.md`)
- nvkectl → Management API: manages clusters (evidence: `README.md`)
- Controller worker → Cluster state: persists state (evidence: `controller/cmd/worker/main.go`)
- Cluster reconciler → Controller API client: calls API (evidence: `management-engine/controllers/nvkecluster_controller.go`)
- Controller API client → Management API: sends requests (evidence: `management-engine/internal/nvkecontroller/client.go`)
- Fake controller API → Management API: implements API (evidence: `management-engine/internal/fake/server.go`)
- Controller worker → Bootstrap authorization: starts controller
- Controller worker → Agent upgrades: starts controller
- Controller worker → Tenant access: starts controller
- Controller worker → Teleport tokens: starts controller
- Cluster reconciler → Provisioned provider: creates machines
- Provisioned provider → NICo infrastructure: provisions machines (evidence: `README.md`)
- NICo simulator → NICo infrastructure: simulates provisioning
- Cluster reconciler → Cluster API: drives lifecycle (evidence: `README.md`)
- Cluster API → Node agent: runs on nodes (evidence: `README.md`)
- Agent upgrades → Node agent: upgrades agent (evidence: `controller/internal/controllers/controlplane/agent_upgrade_controller.go`)
- Node agent → Workload Kubernetes: joins cluster (evidence: `README.md`)
- Cluster customer → Workload Kubernetes: uses kubectl (evidence: `README.md`)
- Bootstrap authorization → Workload Kubernetes: authorizes bootstrap
- Tenant access → Workload Kubernetes: publishes kubeconfig (evidence: `controller/internal/controllers/tenantaccess/controller.go`)
- Teleport tokens → NICo infrastructure: checks node identity
- Authorization client → Management API: authorizes requests
- Agent streaming client → Node agent: streams agent data