# datum-cloud/datum architecture

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

- Interactive diagram: https://gitdiagram.com/datum-cloud/datum
- Repository: https://github.com/datum-cloud/datum

## Overview

##### Project type and purpose
- This is a Kubernetes-native control-plane project (“Datum”) written in Go, composed of three main binaries (api server, authorization webhook, controller manager) plus accompanying Kubernetes manifests.
- Its purpose is to provide a portable “Datum” control plane that implements custom APIs (via the generic control plane libraries) and controllers/operators for network and workload management.

##### File structure
- Top-level directories:
- cmd/… – entrypoints for each binary:
◦ datum-apiserver
◦ datum-authorization-webhook
◦ datum-controller-manager
- config/… – Kubernetes YAML/kustomize configurations for deploying each component.
- pkg/… – shared Go packages (logging, server filters).
- .github/workflows – CI pipelines (build, test, publish).
- Each cmd/<binary>/app folder contains the Go code for that component’s logic (e.g., admission.go, filters, authorizers, controllers).

##### README for additional insights
- The README clarifies the three key Datum control-plane roles:
- API Server – extends Kubernetes API using generic control plane libraries
- Authorization Webhook – enforces RBAC/authorization rules on Datum resources
- Controller Manager – runs controller loops to reconcile Datum CRDs
- There are operator-focused subprojects (network, workload, GCP infra), but this repo provides the core control-plane binaries and deployment manifests.

##### Elements
- Datum API Server
- Authorization Webhook Service
- Controller Manager
- etcd
- External Cloud APIs
- API calls from kubectl → API Server
- API Server → admission webhook
- API Server ↔ etcd
- Controller Manager → API Server watcher/listener
- Controller Manager → external cloud services
- Blue for “control-plane components” (API Server, Controller Manager)
- Orange for “admission/authorization”
- Green for “external dependencies” (etcd, cloud APIs)

##### Detailed but concise
- Side-notes for shared libraries (pkg/) to indicate where common code lives.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    A["kubectl / Clients"]:::external
    A -->|"Invoke Datum APIs"| B["API Aggregator"]:::control_plane

    subgraph "Kubernetes Cluster"
        direction TB

        B -->|"Forwards requests"| C["Datum API Server"]:::control_plane
        C -->|"CRUD Datum CRs"| D["etcd"]:::external
        C -->|"Validate & Authorize"| E["Authorization Webhook"]:::admission

        E -->|"Response: Admit/Deny"| C

        subgraph "Controller Manager (Deployment)" 
            direction TB
            F["Datum Controller Manager"]:::control_plane
        end

        C -->|"Watch Datum CRs"| F
        F -->|"Reconcile & Call External APIs"| G["External Cloud APIs"]:::external
    end

    %% Shared libraries and manifests
    H["Shared Libraries (pkg/)"]:::shared
    I["Kustomize Manifests (config/)"]:::infra
    J["CI/CD Workflows (.github/workflows/)"]:::infra

    %% Connections to shared modules
    C -->|"Uses pkg/server, pkg/cmd"| H
    E -->|"Uses pkg/server"| H
    F -->|"Uses pkg/cmd"| H
    I -->|"Deploys components via kustomize"| C
    I -->|"Deploys components via kustomize"| F
    J -->|"Build/Test/Publish pipelines"| C

    %% Click Events Datum API Server
    click C "https://github.com/datum-cloud/datum/blob/main/cmd/datum-apiserver/main.go"
    click C "https://github.com/datum-cloud/datum/blob/main/cmd/datum-apiserver/app/server.go"
    click C "https://github.com/datum-cloud/datum/blob/main/cmd/datum-apiserver/app/admission.go"
    click C "https://github.com/datum-cloud/datum/blob/main/cmd/datum-apiserver/app/config.go"
    click C "https://github.com/datum-cloud/datum/blob/main/cmd/datum-apiserver/app/serviceaccounts.go"
    click C "https://github.com/datum-cloud/datum/tree/main/cmd/datum-apiserver/Dockerfile"
    click I "https://github.com/datum-cloud/datum/blob/main/config/apiserver/deployment.yaml"
    click I "https://github.com/datum-cloud/datum/blob/main/config/apiserver/service.yaml"
    click I "https://github.com/datum-cloud/datum/blob/main/config/apiserver/httpproxy.yaml"
    click I "https://github.com/datum-cloud/datum/blob/main/config/apiserver/kustomization.yaml"

    %% Click Events Authorization Webhook
    click E "https://github.com/datum-cloud/datum/blob/main/cmd/datum-authorization-webhook/webhook.go"
    click E "https://github.com/datum-cloud/datum/blob/main/cmd/datum-authorization-webhook/app/serve.go"
    click E "https://github.com/datum-cloud/datum/blob/main/cmd/datum-authorization-webhook/app/webhook.go"
    click E "https://github.com/datum-cloud/datum/blob/main/cmd/datum-authorization-webhook/app/internal/webhook/http.go"
    click E "https://github.com/datum-cloud/datum/blob/main/cmd/datum-authorization-webhook/app/internal/webhook/webhook.go"
    click E "https://github.com/datum-cloud/datum/blob/main/cmd/datum-authorization-webhook/app/internal/webhook/response.go"
    click E "https://github.com/datum-cloud/datum/blob/main/cmd/datum-authorization-webhook/app/internal/iam/core_control_plane_authorizer.go"
    click E "https://github.com/datum-cloud/datum/blob/main/cmd/datum-authorization-webhook/app/internal/iam/project_control_plane_authorizer.go"
    click E "https://github.com/datum-cloud/datum/blob/main/cmd/datum-authorization-webhook/app/internal/webhook/webhook_test.go"
    click E "https://github.com/datum-cloud/datum/tree/main/cmd/datum-authorization-webhook/Dockerfile"

    %% Click Events Controller Manager
    click F "https://github.com/datum-cloud/datum/blob/main/cmd/datum-controller-manager/main.go"
    click F "https://github.com/datum-cloud/datum/blob/main/cmd/datum-controller-manager/app/controllermanager.go"
    click F "https://github.com/datum-cloud/datum/blob/main/cmd/datum-controller-manager/app/core.go"
    click F "https://github.com/datum-cloud/datum/tree/main/cmd/datum-controller-manager/Dockerfile"
    click I "https://github.com/datum-cloud/datum/blob/main/config/controller-manager/deployment.yaml"
    click I "https://github.com/datum-cloud/datum/blob/main/config/controller-manager/kustomization.yaml"

    %% Click Events Shared Libraries
    click H "https://github.com/datum-cloud/datum/blob/main/pkg/server/filters/organizations.go"
    click H "https://github.com/datum-cloud/datum/blob/main/pkg/server/filters/organizations_test.go"
    click H "https://github.com/datum-cloud/datum/blob/main/pkg/cmd/logging.go"

    %% Click Events CI/CD
    click J "https://github.com/datum-cloud/datum/blob/main/.github/workflows/build.yaml"
    click J "https://github.com/datum-cloud/datum/blob/main/.github/workflows/test.yaml"
    click J "https://github.com/datum-cloud/datum/blob/main/.github/workflows/publish.yaml"

    %% Styles
    classDef control_plane fill:#0088cc,stroke:#005f8a,color:#fff;
    classDef admission fill:#ff9900,stroke:#cc7a00,color:#000;
    classDef external fill:#33cc33,stroke:#229922,color:#000;
    classDef shared fill:#66ccff,stroke:#3399cc,color:#000;
    classDef infra fill:#cccccc,stroke:#999999,color:#000;
```
