# gorizond/fleet-workspace-controller architecture

> Architecture diagram of the GitHub repository gorizond/fleet-workspace-controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gorizond/fleet-workspace-controller
- Repository: https://github.com/gorizond/fleet-workspace-controller

## Overview

##### Project type and purpose
- This is a Kubernetes “operator” (controller) written in Go, built using Kubebuilder patterns, whose job is to reconcile a set of custom resources (FleetWorkspace, GlobalRoleBinding, RoleBinding, User, etc.) in a Rancher/Kubernetes environment.
- It ships as a container image (see Dockerfile), deployed via a Helm chart under `charts/fleet-workspace-controller`, and uses generated client code in `pkg/generated` against CRD definitions in `pkg/apis/management.cattle.io/v3`.

##### File structure
- Top level
- Dockerfile, .dockerignore → build/operator container
- main.go → entrypoint that sets up the controller manager
- go.mod/go.sum → Go modules
- `controllers/`
- Reconciler implementations for each CR type (FleetWorkspace, GlobalRoleBinding, TTL handler, RoleBinding, User)
- `pkg/apis/management.cattle.io/v3/`
- CRD type definitions (types.go) and registration code (zz_generated_*.go)
- `pkg/generated/controllers/…`
- Generated client interfaces and factories for watchers/informers
- `charts/fleet-workspace-controller/`
- Helm chart to install CRDs, RBAC, deployment, HPA, global roles
- `scripts/`
- Code-gen helpers to produce deepcopy, clientsets, informers

##### Essential elements to capture
- CRD definitions (pkg/apis) vs. runtime CR instances
- Generated clients (pkg/generated) feeding into reconcilers
- Reconcile loops in each controller file
- Deployment via Helm (charts/)
- RBAC roles/bindings that grant the operator its permissions

- **Labels** every component explicitly
- Captures the **end-to-end flow**: from Helm chart installation, through event watching, to resource reconciliation and updates in the cluster

This gives you a comprehensive, accurate architectural view tailored specifically to the fleet-workspace-controller operator.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CI / Code Generation"
        Scripts["Codegen Helpers"]:::codegen
    end

    subgraph "Helm Deployment"
        HelmCLI["Helm CLI"]:::helm
    end

    subgraph "Kubernetes Cluster"
        subgraph "Control Plane"
            APIServer["API Server"]:::controlplane
            etcd["etcd (Storage)"]:::controlplane
        end

        subgraph "CustomResourceDefinitions" 
            types["types.go"]:::crd
            deepcopy["zz_generated_deepcopy.go"]:::crd
            listtypes["zz_generated_list_types.go"]:::crd
            reg1["zz_generated_register.go"]:::crd
            reg2["zz_generated_register.go"]:::crd
        end

        subgraph "Operator Pod"
            Operator["Operator Container"]:::operator
            subgraph "Controller Manager"
                Main["main.go"]:::operator
                subgraph "Generated Clients & Informers"
                    GenClient["Pkg/generated/controllers"]:::operator
                end
                subgraph "Reconcilers"
                    FWH["FleetWorkspaceHandler"]:::operator
                    GRBH["GlobalRoleBindingHandler"]:::operator
                    GRBT["GlobalRoleBindingTTLHandler"]:::operator
                    RBC["RoleBinding Controller"]:::operator
                    UC["User Controller"]:::operator
                end
            end
        end
    end

    Prometheus["Prometheus"]:::external

    %% Connections
    Scripts --> GenClient
    HelmCLI --> APIServer
    HelmCLI --> Operator
    APIServer -->|watch events| Operator
    Operator -->|API calls| APIServer
    Operator -->|metrics| Prometheus
    APIServer -->|persists CRs| etcd
    APIServer -->|serves CRD definitions| types
    types --> etcd
    deepcopy --> types
    listtypes --> types
    reg1 --> types
    reg2 --> types

    %% Click Events
    click Scripts "https://github.com/gorizond/fleet-workspace-controller/blob/main/scripts/controller-gen.go"
    click HelmCLI "https://github.com/gorizond/fleet-workspace-controller/blob/main/charts/fleet-workspace-controller/Chart.yaml"
    click Operator "https://github.com/gorizond/fleet-workspace-controller/tree/main/Dockerfile"
    click Main "https://github.com/gorizond/fleet-workspace-controller/blob/main/main.go"
    click FWH "https://github.com/gorizond/fleet-workspace-controller/blob/main/controllers/fleetworkspace_handler.go"
    click GRBH "https://github.com/gorizond/fleet-workspace-controller/blob/main/controllers/globalrolebinding_handler.go"
    click GRBT "https://github.com/gorizond/fleet-workspace-controller/blob/main/controllers/globalrolebinding_ttl_handler.go"
    click RBC "https://github.com/gorizond/fleet-workspace-controller/blob/main/controllers/role_binding.go"
    click UC "https://github.com/gorizond/fleet-workspace-controller/blob/main/controllers/user_controller.go"
    click types "https://github.com/gorizond/fleet-workspace-controller/blob/main/pkg/apis/management.cattle.io/v3/types.go"
    click deepcopy "https://github.com/gorizond/fleet-workspace-controller/blob/main/pkg/apis/management.cattle.io/v3/zz_generated_deepcopy.go"
    click listtypes "https://github.com/gorizond/fleet-workspace-controller/blob/main/pkg/apis/management.cattle.io/v3/zz_generated_list_types.go"
    click reg1 "https://github.com/gorizond/fleet-workspace-controller/blob/main/pkg/apis/management.cattle.io/v3/zz_generated_register.go"
    click reg2 "https://github.com/gorizond/fleet-workspace-controller/blob/main/pkg/apis/management.cattle.io/zz_generated_register.go"
    click GenClient "https://github.com/gorizond/fleet-workspace-controller/blob/main/pkg/generated/controllers/management.cattle.io/factory.go"

    %% Styles
    classDef controlplane fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef operator fill:#D0FFD8,stroke:#028a0f,color:#028a0f;
    classDef crd fill:#FFE4B5,stroke:#d2691e,color:#d2691e;
    classDef helm fill:#E1D5E7,stroke:#6f42c1,color:#6f42c1;
    classDef codegen fill:#F0F0F0,stroke:#666666,color:#333333;
    classDef external fill:#F5F5F5,stroke:#999999,color:#555555
```
