# k0rdent/kof architecture

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

- Interactive diagram: https://gitdiagram.com/k0rdent/kof
- Repository: https://github.com/k0rdent/kof

## Overview

##### Project type and purpose
- This is a Kubernetes-native Observability and FinOps platform (“kof”) that comprises:
- A Go-based Kubernetes Operator (“kof-operator”) that uses CRDs to coordinate multi-cluster deployments and telemetry aggregation
- A suite of Helm charts under charts/ to install components like collectors (OpenTelemetry, Prometheus, VictoriaMetrics), Istio configuration, storage, and dashboards
- Demo manifests and extensive documentation for running on AWS, Azure, EKS, etc.
- Its goal is to deploy, configure, and manage telemetry in child and regional clusters, aggregate metrics/traces in a “mothership,” and present dashboards & alerts for cost-and-performance insights.

##### File structure
Top-level directories reveal architectural layers:
- charts/ – Helm charts for each logical component: collectors, Istio config, “mothership” aggregator, storage backends, operators, child/regional multi-cluster services
- kof-operator/ – the custom Kubernetes Operator built with controller-runtime, defining CRDs (PromxyServerGroup, MultiClusterService, ClusterDeployment, etc.), reconcilers, RBAC, and Dockerfiles
- demo/ – example values and cluster manifests showing how operator and charts are applied in real environments

##### README
- Confirms project focus (“k0rdent Observability and FinOps”) and points at full documentation
- Suggests conventional commit standards for contribution

##### Final advice
- CRDs (e.g., PromxyServerGroup, MultiClusterService) as diamonds or annotations to underscore the operator pattern
- Keep the layout clean: control flows on top, data flows bottom, storage at the center or right side
- With version or Helm values file names where meaningful (e.g., demo/demo-mothership-values.yaml)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Developer/User Interface Layer
    subgraph "Developer/User Interface" 
        direction TB
        Makefile["Makefile"] 
        README["README.md"] 
        GitHub[".github/workflows/"] 
    end

    %% Control Plane
    subgraph "Control Plane (kof-operator)" 
        direction TB
        OperatorDir["kof-operator/"] 
        CRDs["config/crd/bases/"] 
        APIControllers["api/v1beta1 & internal/controller/"] 
        OperatorBuild["Dockerfile & Makefile"] 
    end

    %% Child Cluster Layer
    subgraph "Child Cluster"
        direction TB
        ChildChart["charts/kof-child/"] 
        CollectorChart["charts/kof-collectors/"] 
        IstioChart["charts/kof-istio/"] 
    end

    %% Regional Cluster Layer
    subgraph "Regional Cluster"
        direction TB
        RegionalChart["charts/kof-regional/"] 
    end

    %% Mothership Cluster Layer
    subgraph "Mothership Cluster"
        direction TB
        MothershipChart["charts/kof-mothership/"] 
        PromxyCRD["crds/promxyservergroups.yaml"] 
        GrafanaTemplates["templates/grafana/ & files/dashboards/"] 
        PromTemplates["templates/prometheus/ & promxy/ & victoria/"] 
    end

    %% Storage Backend
    subgraph "Storage Backend"
        direction TB
        StorageChart["charts/kof-storage/"] 
        StorageDash["files/dashboards/ & templates/"] 
    end

    %% Additional Components
    subgraph "Operators Helm Chart"
        direction TB
        OperatorsChart["charts/kof-operators/"] 
    end

    subgraph "Demo Manifests"
        direction TB
        DemoCluster["demo/cluster/"] 
        DemoValues["demo/demo-mothership-values.yaml"] 
    end

    subgraph "Documentation & Guides"
        direction TB
        DocsDir["docs/"] 
    end

    %% Data & Control Flows
    Makefile -->|uses| OperatorDir
    README -->|documents| OperatorDir
    GitHub -->|triggers| OperatorDir

    OperatorDir -->|defines| CRDs
    OperatorDir -->|implements| APIControllers
    OperatorBuild -->|builds image| OperatorDir

    OperatorDir -->|deploys charts| ChildChart
    OperatorDir -->|deploys charts| RegionalChart
    OperatorDir -->|deploys charts| MothershipChart

    ChildChart -->|installs collectors| CollectorChart
    ChildChart -->|installs sidecars| IstioChart

    CollectorChart -->|scrapes metrics| RegionalChart
    IstioChart -->|injects sidecars| CollectorChart

    RegionalChart -->|forwards telemetry| MothershipChart

    MothershipChart -->|manages CRD| PromxyCRD
    MothershipChart -->|deploys dashboards| GrafanaTemplates
    MothershipChart -->|deploys metrics stack| PromTemplates

    MothershipChart -->|stores long-term| StorageChart
    StorageChart -->|provides dashboards| StorageDash

    OperatorsChart -->|aggregates operators| OperatorDir

    DemoCluster -->|example usage| ChildChart
    DemoCluster -->|example usage| RegionalChart
    DemoValues -->|values file| MothershipChart

    DocsDir -.->|guides| CollectorChart
    DocsDir -.->|guides| IstioChart
    DocsDir -.->|guides| APIControllers

    %% Click Events
    click Makefile "https://github.com/k0rdent/kof/tree/main/Makefile"
    click README "https://github.com/k0rdent/kof/blob/main/README.md"
    click GitHub "https://github.com/k0rdent/kof/tree/main/.github/workflows/"
    click OperatorDir "https://github.com/k0rdent/kof/tree/main/kof-operator/"
    click CRDs "https://github.com/k0rdent/kof/tree/main/kof-operator/config/crd/bases/"
    click APIControllers "https://github.com/k0rdent/kof/tree/main/kof-operator/api/v1beta1/"
    click OperatorBuild "https://github.com/k0rdent/kof/tree/main/kof-operator/Dockerfile"
    click ChildChart "https://github.com/k0rdent/kof/tree/main/charts/kof-child/"
    click CollectorChart "https://github.com/k0rdent/kof/tree/main/charts/kof-collectors/"
    click IstioChart "https://github.com/k0rdent/kof/tree/main/charts/kof-istio/"
    click RegionalChart "https://github.com/k0rdent/kof/tree/main/charts/kof-regional/"
    click MothershipChart "https://github.com/k0rdent/kof/tree/main/charts/kof-mothership/"
    click PromxyCRD "https://github.com/k0rdent/kof/blob/main/charts/kof-mothership/crds/kof.k0rdent.mirantis.com_promxyservergroups.yaml"
    click GrafanaTemplates "https://github.com/k0rdent/kof/tree/main/charts/kof-mothership/templates/grafana/"
    click PromTemplates "https://github.com/k0rdent/kof/tree/main/charts/kof-mothership/templates/prometheus/"
    click StorageChart "https://github.com/k0rdent/kof/tree/main/charts/kof-storage/"
    click StorageDash "https://github.com/k0rdent/kof/tree/main/charts/kof-storage/files/dashboards/"
    click OperatorsChart "https://github.com/k0rdent/kof/tree/main/charts/kof-operators/"
    click DemoCluster "https://github.com/k0rdent/kof/tree/main/demo/cluster/"
    click DemoValues "https://github.com/k0rdent/kof/blob/main/demo/demo-mothership-values.yaml"
    click DocsDir "https://github.com/k0rdent/kof/tree/main/docs/"

    %% Styles
    classDef developer fill:#D0E6F6,stroke:#003366,color:#003366;
    classDef controlPlane fill:#CCE5FF,stroke:#004085,color:#004085;
    classDef dataPlane fill:#DFF0D8,stroke:#3C763D,color:#3C763D;
    classDef storage fill:#FFE5B4,stroke:#FF8C00,color:#8B4513;
    classDef charts fill:#E2D6F8,stroke:#6A1B9A,color:#4A148C;
    classDef docs fill:#F5F5F5,stroke:#666666,color:#333333;
    classDef demo fill:#FDE2E4,stroke:#A93226,color:#641E16;

    class Makefile,README,GitHub developer
    class OperatorDir,CRDs,APIControllers,OperatorBuild controlPlane
    class ChildChart,CollectorChart,IstioChart,RegionalChart,MothershipChart dataPlane
    class PromxyCRD,GrafanaTemplates,PromTemplates storage
    class StorageChart,StorageDash storage
    class OperatorsChart charts
    class DemoCluster,DemoValues demo
    class DocsDir docs
```
