# cyclops-ui/cyclops architecture

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

- Interactive diagram: https://gitdiagram.com/cyclops-ui/cyclops
- Repository: https://github.com/cyclops-ui/cyclops

## Overview

Cyclops provides a browser UI and CLI for managing Kubernetes applications through template-backed modules, while its controller renders and reconciles those modules into cluster resources. The README highlights customizable Helm-chart templates; the source also exposes template stores, release management, resource inspection, logs, exec, and module history. The graph follows documented routes and sampled wiring where available; unsampled subsystems are included from the tree and README, but their internal calls are not inferred.

Main entry points: [`cyclops-ctrl/pkg/cluster/k8sclient/client.go`](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/pkg/cluster/k8sclient/client.go) (Kubernetes client), [`cyclops-ui/src/routes/index.tsx`](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/routes/index.tsx) (UI pages), [`cyclops-ctrl/internal/handler/handler.go`](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/handler/handler.go) (HTTP API), [`cyclops-ctrl/internal/modulecontroller/module_controller.go`](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/modulecontroller/module_controller.go) (Module reconciler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User interfaces"]
  node_ui["Cyclops UI<br/>[App.tsx]"]
  node_ui_routes["UI pages<br/>[index.tsx]"]
  node_module_pages["Module pages<br/>[Modules.tsx]"]
  node_template_page["Template store<br/>[TemplateStore.tsx]"]
  node_resource_pages["Cluster views<br/>[Nodes.tsx]"]
  node_helm_pages["Helm views<br/>[Releases.tsx]"]
  node_resource_components["Resource details<br/>[Service.tsx]"]
  node_theme["Theme state<br/>[ThemeContext.tsx]"]
end

subgraph group_api["Control API"]
  node_api_server["HTTP API<br/>[handler.go]"]
  node_module_api["Module endpoints<br/>[modules.go]"]
  node_template_api["Template endpoints<br/>[templates.go]"]
  node_sse["Live streams<br/>[server.go]"]
  node_websocket["Pod exec<br/>[server.go]"]
end

subgraph group_templates["Templates and modules"]
  node_template_repo["Template repository<br/>[git.go]"]
  node_template_render["Template renderer<br/>[render.go]"]
  node_module_reconcile["Module reconciler"]
  node_module_types["Module resources<br/>[module_types.go]"]
  node_template_store["Template stores"]
  node_auth_rules["Template credentials"]
  node_git_write["Git config writes<br/>[writeclient.go]"]
end

subgraph group_cluster["Cluster operations"]
  node_k8s_client["Kubernetes client<br/>[client.go]"]
  node_helm["Helm integration<br/>[helm.go]"]
  node_resource_mapper["Resource mapping<br/>[modules.go]"]
end

subgraph group_operations["Operations and tooling"]
  node_metrics["Metrics<br/>[handler.go]"]
  node_telemetry["Telemetry<br/>[client.go]"]
  node_cli["cyctl<br/>[root.go]"]
end

node_developer(("Developer"))
node_cluster[("Kubernetes cluster")]

node_developer -->|"uses"| node_ui
node_ui -->|"routes through"| node_ui_routes
node_ui_routes -->|"routes to"| node_module_pages
node_ui_routes -->|"routes to"| node_template_page
node_ui_routes -->|"routes to"| node_resource_pages
node_ui_routes -->|"routes to"| node_helm_pages
node_ui -->|"provides theme"| node_theme
node_resource_components -->|"reads theme"| node_theme
node_api_server -->|"routes requests"| node_module_api
node_api_server -->|"routes requests"| node_template_api
node_api_server -->|"routes streams"| node_sse
node_api_server -->|"routes exec"| node_websocket
node_developer -->|"manages resources"| node_cli
node_template_repo -->|"resolves credentials"| node_auth_rules
node_module_reconcile -->|"loads templates"| node_template_repo
node_module_reconcile -->|"renders templates"| node_template_render
node_module_reconcile -->|"applies resources"| node_k8s_client
node_module_reconcile -->|"reconciles"| node_module_types
node_template_api -.->|"reads templates"| node_template_repo
node_module_api -.->|"queries cluster"| node_k8s_client
node_sse -->|"streams resources"| node_k8s_client
node_websocket -->|"executes commands"| node_k8s_client
node_k8s_client -.->|"reads and writes"| node_cluster
node_helm_pages -.->|"manages releases"| node_helm
node_resource_pages -.->|"inspects resources"| node_k8s_client
node_git_write -->|"resolves credentials"| node_auth_rules
node_cli -.->|"manages modules"| node_module_types
node_cli -.->|"manages stores"| node_template_store
node_cli -->|"manages credentials"| node_auth_rules

click node_ui "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/App.tsx"
click node_ui_routes "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/routes/index.tsx"
click node_module_pages "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/pages/Modules/Modules.tsx"
click node_template_page "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/pages/TemplateStore/TemplateStore.tsx"
click node_resource_pages "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/pages/Nodes.tsx"
click node_helm_pages "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/pages/Helm/Releases/Releases.tsx"
click node_resource_components "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/k8s-resources/Service.tsx"
click node_theme "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/theme/ThemeContext.tsx"
click node_api_server "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/handler/handler.go"
click node_module_api "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/controller/modules.go"
click node_template_api "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/controller/templates.go"
click node_sse "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/controller/sse/server.go"
click node_websocket "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/controller/ws/server.go"
click node_template_repo "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/pkg/template/git.go"
click node_template_render "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/pkg/template/render/render.go"
click node_module_reconcile "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/modulecontroller/module_controller.go"
click node_module_types "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/api/v1alpha1/module_types.go"
click node_template_store "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/api/v1alpha1/template_store_types.go"
click node_auth_rules "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/api/v1alpha1/template_auth_rule_types.go"
click node_git_write "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/git/writeclient.go"
click node_k8s_client "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/pkg/cluster/k8sclient/client.go"
click node_helm "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/integrations/helm/helm.go"
click node_resource_mapper "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/mapper/modules.go"
click node_metrics "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/prometheus/handler.go"
click node_telemetry "https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/telemetry/client.go"
click node_cli "https://github.com/cyclops-ui/cyclops/blob/main/cyctl/cmd/root.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_ui,node_ui_routes,node_module_pages,node_template_page,node_resource_pages,node_helm_pages,node_resource_components,node_theme toneBlue
class node_api_server,node_module_api,node_template_api,node_sse,node_websocket,node_cluster toneAmber
class node_template_repo,node_template_render,node_module_reconcile,node_module_types,node_template_store,node_auth_rules,node_git_write toneMint
class node_k8s_client,node_helm,node_resource_mapper toneRose
class node_metrics,node_telemetry,node_cli,node_developer toneIndigo
```

## Components

### User interfaces

- [Cyclops UI](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/App.tsx): `cyclops-ui/src/App.tsx`
- [UI pages](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/routes/index.tsx): `cyclops-ui/src/routes/index.tsx`
- [Module pages](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/pages/Modules/Modules.tsx): `cyclops-ui/src/components/pages/Modules/Modules.tsx`
- [Template store](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/pages/TemplateStore/TemplateStore.tsx): `cyclops-ui/src/components/pages/TemplateStore/TemplateStore.tsx`
- [Cluster views](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/pages/Nodes.tsx): `cyclops-ui/src/components/pages/Nodes.tsx`
- [Helm views](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/pages/Helm/Releases/Releases.tsx): `cyclops-ui/src/components/pages/Helm/Releases/Releases.tsx`
- [Resource details](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/k8s-resources/Service.tsx): `cyclops-ui/src/components/k8s-resources/Service.tsx`
- [Theme state](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ui/src/components/theme/ThemeContext.tsx): `cyclops-ui/src/components/theme/ThemeContext.tsx`

### Control API

- [HTTP API](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/handler/handler.go): `cyclops-ctrl/internal/handler/handler.go`
- [Module endpoints](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/controller/modules.go): `cyclops-ctrl/internal/controller/modules.go`
- [Template endpoints](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/controller/templates.go): `cyclops-ctrl/internal/controller/templates.go`
- [Live streams](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/controller/sse/server.go): `cyclops-ctrl/internal/controller/sse/server.go`
- [Pod exec](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/controller/ws/server.go): `cyclops-ctrl/internal/controller/ws/server.go`

### Templates and modules

- [Template repository](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/pkg/template/git.go): `cyclops-ctrl/pkg/template/git.go`
- [Template renderer](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/pkg/template/render/render.go): `cyclops-ctrl/pkg/template/render/render.go`
- [Module reconciler](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/modulecontroller/module_controller.go): `cyclops-ctrl/internal/modulecontroller/module_controller.go`
- [Module resources](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/api/v1alpha1/module_types.go): `cyclops-ctrl/api/v1alpha1/module_types.go`
- [Template stores](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/api/v1alpha1/template_store_types.go): `cyclops-ctrl/api/v1alpha1/template_store_types.go`
- [Template credentials](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/api/v1alpha1/template_auth_rule_types.go): `cyclops-ctrl/api/v1alpha1/template_auth_rule_types.go`
- [Git config writes](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/git/writeclient.go): `cyclops-ctrl/internal/git/writeclient.go`

### Cluster operations

- [Kubernetes client](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/pkg/cluster/k8sclient/client.go): `cyclops-ctrl/pkg/cluster/k8sclient/client.go`
- [Helm integration](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/integrations/helm/helm.go): `cyclops-ctrl/internal/integrations/helm/helm.go`
- [Resource mapping](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/mapper/modules.go): `cyclops-ctrl/internal/mapper/modules.go`

### Operations and tooling

- [Metrics](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/prometheus/handler.go): `cyclops-ctrl/internal/prometheus/handler.go`
- [Telemetry](https://github.com/cyclops-ui/cyclops/blob/main/cyclops-ctrl/internal/telemetry/client.go): `cyclops-ctrl/internal/telemetry/client.go`
- [cyctl](https://github.com/cyclops-ui/cyclops/blob/main/cyctl/cmd/root.go): `cyctl/cmd/root.go`

### Other components

- **Developer**
- **Kubernetes cluster**

## Connections

- Developer → Cyclops UI: uses (evidence: `README.md`)
- Cyclops UI → UI pages: routes through (evidence: `cyclops-ui/src/App.tsx`)
- UI pages → Module pages: routes to (evidence: `cyclops-ui/src/routes/index.tsx`)
- UI pages → Template store: routes to (evidence: `cyclops-ui/src/routes/index.tsx`)
- UI pages → Cluster views: routes to (evidence: `cyclops-ui/src/routes/index.tsx`)
- UI pages → Helm views: routes to (evidence: `cyclops-ui/src/routes/index.tsx`)
- Cyclops UI → Theme state: provides theme (evidence: `cyclops-ui/src/App.tsx`)
- Resource details → Theme state: reads theme (evidence: `cyclops-ui/src/components/k8s-resources/Service.tsx`)
- HTTP API → Module endpoints: routes requests (evidence: `cyclops-ctrl/internal/handler/handler.go`)
- HTTP API → Template endpoints: routes requests (evidence: `cyclops-ctrl/internal/handler/handler.go`)
- HTTP API → Live streams: routes streams (evidence: `cyclops-ctrl/internal/handler/handler.go`)
- HTTP API → Pod exec: routes exec (evidence: `cyclops-ctrl/internal/handler/handler.go`)
- Developer → cyctl: manages resources (evidence: `README.md`)
- Template repository → Template credentials: resolves credentials (evidence: `cyclops-ctrl/pkg/template/git.go`)
- Module reconciler → Template repository: loads templates (evidence: `cyclops-ctrl/internal/modulecontroller/module_controller.go`)
- Module reconciler → Template renderer: renders templates (evidence: `cyclops-ctrl/internal/modulecontroller/module_controller.go`)
- Module reconciler → Kubernetes client: applies resources (evidence: `cyclops-ctrl/internal/modulecontroller/module_controller.go`)
- Module reconciler → Module resources: reconciles (evidence: `cyclops-ctrl/internal/modulecontroller/module_controller.go`)
- Template endpoints → Template repository: reads templates
- Module endpoints → Kubernetes client: queries cluster
- Live streams → Kubernetes client: streams resources (evidence: `cyclops-ctrl/internal/controller/sse/server.go`)
- Pod exec → Kubernetes client: executes commands (evidence: `cyclops-ctrl/internal/controller/ws/server.go`)
- Kubernetes client → Kubernetes cluster: reads and writes
- Helm views → Helm integration: manages releases
- Cluster views → Kubernetes client: inspects resources
- Git config writes → Template credentials: resolves credentials (evidence: `cyclops-ctrl/internal/git/writeclient.go`)
- cyctl → Module resources: manages modules
- cyctl → Template stores: manages stores
- cyctl → Template credentials: manages credentials