# kloudlite/helm-charts architecture

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

- Interactive diagram: https://gitdiagram.com/kloudlite/helm-charts
- Repository: https://github.com/kloudlite/helm-charts

## Overview

##### Project type and purpose
- This repo is a set of Helm charts (charts/kloudlite-platform and charts/kloudlite-agent) plus a small Go‐based templating CLI (cmd/tmpl).
- Its purpose is to package, release, and install the Kloudlite platform and agent into Kubernetes clusters. It manages CRDs, operators, microservices, backing services, ingress, security, and observability stacks.

##### File structure
- Top-level:
- .github/workflows: CI/CD pipelines for chart releases and README generation
- Dockerfile + Taskfile.yml: build and packaging steps for the templating CLI and container images
- charts/kloudlite-platform: the main platform chart, with values, templates, CRDs, and sub-charts for cert-manager, ingress, operators, backing services, apps, RBAC, observability
- charts/kloudlite-agent: the agent chart (deploys an agent pod, operator, RBAC, wireguard, post-install jobs)
- cmd/tmpl: the Go binary used to preprocess Helm templates or generate README snippets
- crds: standalone YAML definitions for CRDs that need to be applied before chart install
- scripts: release helper for GitHub actions
- The directory hierarchy reflects an Infrastructure-as-Code pattern (Helm charts + GitOps/CI pipelines) rather than a classic frontend/backend codebase.

##### README for additional insights
- The readme confirms that this is an “application” type Helm chart, versioned, and installed via `helm install`.
- It calls out CRD installation, chart configuration via values.yaml, and upgrade/uninstall commands.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    subgraph "CI/CD & Dev Environment"
        direction TB
        Dev["Developer Workstation"]:::external
        GH["GitHub Actions CI/CD"]:::external
        Docker["Docker Build"]:::external
        Task["Task Automation"]:::external
        TemplatingCLI["Templating CLI (cmd/tmpl)"]:::external
    end

    Dev -->|push & PR| GH
    GH -->|"build image"| Docker
    GH -->|"run tasks"| Task
    Task -->|"invoke"| TemplatingCLI

    click GH "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/.github/workflows/helm-release.yml"
    click GH "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/.github/workflows/helm-unlist-release.yml"
    click GH "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/.github/workflows/readme-generator.yml"
    click Docker "https://github.com/kloudlite/helm-charts/tree/release-v1.1.6/Dockerfile"
    click Task "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/Taskfile.yml"
    click TemplatingCLI "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/cmd/tmpl/main.go"
    click TemplatingCLI "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/cmd/tmpl/pkg/functions/functions.go"
    click TemplatingCLI "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/cmd/tmpl/pkg/template/parser.go"

    %% Chart Repo
    Repo["Helm Chart Repo"]:::external
    GH -->|publish charts| Repo

    %% Kubernetes Cluster Boundary
    subgraph "Kubernetes Cluster (namespace: kloudlite)" 
        direction TB

        %% Pre-install CRDs
        CRDs["CRDs (pre-install)"]:::purple
        click CRDs "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/crds/crds-cert-manager.yml"
        click CRDs "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/crds/crds-kloudlite.yml"

        %% Platform Release
        subgraph "Helm Release: kloudlite-platform"
            direction TB

            ChartPlat["Platform Chart"]:::gray
            click ChartPlat "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/Chart.yaml"
            click ChartPlat "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/values.yaml"

            %% Kubernetes Prereqs
            subgraph "K8s Prereqs" 
                direction TB
                CertMgr["cert-manager ClusterIssuer"]:::purple
                click CertMgr "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/01-kubernetes/cert-manager/_cluster-issuer.yml.tpl"
                IngressCtrl["nginx-ingress Helm"]:::purple
                click IngressCtrl "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/01-kubernetes/nginx-ingress/_helm.yml.tpl"
            end

            %% Operators
            subgraph "Operators"
                direction TB
                PlatOp["platform-operator"]:::purple
                click PlatOp "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/01-operators/platform-operator/operator.yml.tpl"
            end

            %% Backing Services
            subgraph "Backing Services"
                direction TB
                NATS["NATS"]:::orange
                click NATS "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/02-backing-services/helm-nats.yml.tpl"
                Mongo["MongoDB"]:::orange
                click Mongo "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/02-backing-services/mongo-svc.yml.tpl"
            end

            %% Microservices
            subgraph "Microservices"
                direction TB
                AuthAPI["auth-api"]:::blue
                GatewayAPI["gateway-api"]:::blue
                click AuthAPI "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/03-apps/apis/apps/auth-api.yml.tpl"
                click GatewayAPI "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/03-apps/apis/apps/gateway.yml.tpl"
            end

            %% Routers
            subgraph "Routers"
                direction TB
                APIRouter["gateway-api-router"]:::blue
                WebRouter["console-web-router"]:::blue
                click APIRouter "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/03-apps/routers/gateway-api-router.yml.tpl"
                click WebRouter "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/03-apps/routers/console-web-router.yml.tpl"
            end

            %% Web Frontends
            subgraph "Web Front-ends"
                direction TB
                AuthWeb["auth-web"]:::blue
                ConsoleWeb["console-web"]:::blue
                click AuthWeb "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/03-apps/web/auth-web.yml.tpl"
                click ConsoleWeb "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/03-apps/web/console-web.yml.tpl"
            end

            %% Workers
            subgraph "Workers"
                direction TB
                AuditWorker["audit-logging-worker"]:::blue
                click AuditWorker "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/03-apps/workers/_audit-logging-worker.yml.tpl"
            end

            %% RBAC
            subgraph "RBAC"
                direction TB
                AdminSA["cluster-admin svc-account"]:::purple
                NormSA["normal svc-account"]:::purple
                click AdminSA "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/04-RBAC/cluster-admin-svc-account.yml.tpl"
                click NormSA "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/04-RBAC/normal-svc-account.yml.tpl"
            end

            %% Observability
            subgraph "Observability"
                direction TB
                Vector["VectorAggregator"]:::green
                click Vector "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/05-observability/vector/helm-vector-aggregator.yml.tpl"
                Victoria["VictoriaMetrics"]:::green
                click Victoria "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-platform/templates/05-observability/victoria-metrics/helm.yml.tpl"
            end

        end

        %% Agent Release
        subgraph "Helm Release: kloudlite-agent"
            direction TB

            ChartAgent["Agent Chart"]:::gray
            click ChartAgent "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-agent/Chart.yaml"
            click ChartAgent "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-agent/values.yaml"

            AgentPod["agent pod"]:::blue
            click AgentPod "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-agent/templates/01-agent/kl-agent.yml.tpl"

            AgentOp["agent-operator"]:::purple
            click AgentOp "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-agent/templates/02-agent-operator/agent-operator.yml.tpl"

            WireGuard["WireGuard sidecar"]:::blue
            click WireGuard "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-agent/templates/wireguard/_wg-example-device.yml.tpl"

            PostJobs["post-install jobs"]:::purple
            click PostJobs "https://github.com/kloudlite/helm-charts/blob/release-v1.1.6/charts/kloudlite-agent/templates/post-helm-jobs/exclude-logs-from-namespace.yml"
        end

        %% Relationships
        CRDs --> ChartPlat
        ChartPlat --> CertMgr
        ChartPlat --> IngressCtrl
        CertMgr --> PlatOp
        IngressCtrl --> APIRouter
        APIRouter --> AuthAPI
        APIRouter --> GatewayAPI
        GatewayAPI --> NATS
        AuthAPI --> Mongo
        AuthAPI -->|publish/subscribe| NATS
        AuthWeb -->|UI traffic| WebRouter
        WebRouter --> ConsoleWeb
        Atlas["Observability Agents"]:::green
        Atlas --> Vector
        Vector --> Victoria

        ChartAgent --> AgentOp
        AgentOp --> AgentPod
        AgentPod --> WireGuard

    end

    %% Legend
    subgraph "Legend"
        direction TB
        O["Operators/CRDs"]:::purple
        MS["Microservices/Web"]:::blue
        BS["Backing Services"]:::orange
        OBS["Observability"]:::green
        CI["CI/CD & Tools"]:::external
    end

    classDef external fill:#aaa,stroke:#333,color:#fff;
    classDef purple fill:#D8BFD8,stroke:#9370DB,color:#000;
    classDef blue fill:#ADD8E6,stroke:#1E90FF,color:#000;
    classDef orange fill:#FFDAB9,stroke:#FF8C00,color:#000;
    classDef green fill:#98FB98,stroke:#2E8B57,color:#000;
    classDef gray fill:#D3D3D3,stroke:#696969,color:#000;
```
