# cnoe-io/idpbuilder architecture

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

- Interactive diagram: https://gitdiagram.com/cnoe-io/idpbuilder
- Repository: https://github.com/cnoe-io/idpbuilder

## Overview

##### Project Type and Purpose
- This is a Go-based CLI tool that doubles as a Kubernetes operator. Its primary function (“idpbuilder create”) is to spin up a complete internal developer platform (IDP) on a local Kubernetes cluster (via Docker/Kind). It defines three custom resources (CustomPackage, GitRepository, LocalBuild) and reconciles them to deploy Argo CD, Gitea, Ingress‐NGINX, CoreDNS, Backstage, etc.

##### Top-Level Components (from the file tree)
- CLI layer (pkg/cmd + main.go)
- Builder engine (pkg/build + hack/ manifests)
- Kubernetes cluster management (pkg/kind)
- Kubernetes API clients & CRD definitions (api/v1alpha1, pkg/k8s, pkg/util)
- Controller-manager (pkg/controllers/*)
- Utility libraries (pkg/util, pkg/logger, pkg/printer)

##### Runtime Workflow & Interactions
a. User invokes `idpbuilder create` (Cobra CLI)
→ CLI parses flags, calls builder code (pkg/build)
→ Optionally spins up a Kind cluster (pkg/kind)
→ Applies CRD manifests (api/v1alpha1 + hack/) via Kubernetes API client (pkg/k8s)
→ Creates custom resource instances (GitRepository, CustomPackage, LocalBuild)
b. Controller-manager (run via `idpbuilder run` or embedded in create) watches CRDs
→ pkg/controllers/gitrepository: clones or mirrors repositories (GitHub/Gitea adapter)
→ pkg/controllers/custompackage: materializes application sets, Helm charts, Kustomize apps
→ pkg/controllers/localbuild: bootstraps local services (Argo CD server, Gitea server, NGINX ingress)
c. Controllers reconcile desired state by generating Kubernetes manifests (templates under pkg/build/templates & hack/**), then apply them through the Kubernetes API
d. The platform components (Argo CD, Gitea, Ingress controller, CoreDNS) come up in the cluster

##### Key Architectural Patterns & Technologies
- Operator pattern: controllers built with Kubebuilder conventions, reconciling CRDs
- CLI pattern: Cobra commands under pkg/cmd, with “create”, “delete”, “get”, “version”
- Local cluster provisioning: Kind (pkg/kind)
- Kubernetes API interactions: client-go abstractions in pkg/k8s & pkg/util/k8s
- Templating: Go‐text templates for manifests (pkg/build/templates, hack/)
- Test harness: e2e tests (tests/e2e), unit tests alongside each package

- User Terminal (CLI)
- idpbuilder binary
- pkg/cmd (Cobra)
- Builder Engine
- pkg/build (manifest generation)
- hack/ (static YAML templates)
- Kind Cluster Manager
- pkg/kind: cluster create/delete
- Kubernetes Control Plane
- API server, etcd (external Docker-hosted Kind)
- CRD registrations (api/v1alpha1)
- Controller Manager (pkg/controllers)
- gitrepository controller
- custompackage controller
- localbuild controller
- Deployed Workloads in Cluster
- Argo CD components
- Gitea server
- Ingress-NGINX
- CoreDNS
- Backstage (if included in templates)
- External Services
- Docker daemon (prerequisite)
- GitHub/Gitea endpoints (for Git mirroring)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        User["User Terminal"]:::user
    end

    %% idpbuilder Binary Components
    subgraph "idpbuilder Binary"
        CLI["CLI (pkg/cmd)"]:::control
        BuildPkg["Builder Engine - pkg/build"]:::control
        Hack["Builder Engine - hack/"]:::control
        KindMgr["Kind Manager (pkg/kind)"]:::provision
        ControllerMgr["Controller Manager (pkg/controllers)"]:::control
    end

    %% Kind Cluster Boundary
    subgraph "Kind Cluster"
        subgraph "Kubernetes Control Plane"
            APIServer["API Server & etcd"]:::k8s
            CRDDefs["CRD Definitions (api/v1alpha1)"]:::k8s
        end
        subgraph "In-Cluster Controllers"
            GitCtrl["gitrepository controller"]:::controllers
            CPkgCtrl["custompackage controller"]:::controllers
            LBldCtrl["localbuild controller"]:::controllers
        end
        subgraph "Deployed Workloads"
            Argo["Argo CD"]:::workloads
            Gitea["Gitea"]:::workloads
            Ingress["Ingress-NGINX"]:::workloads
            CoreDNS["CoreDNS"]:::workloads
            Backstage["Backstage"]:::workloads
        end
    end

    %% External Services
    Docker["Docker Daemon"]:::external
    GitHub["GitHub/Gitea Endpoints"]:::external

    %% Connections
    User -->|"invoke idpbuilder create"| CLI
    CLI -->|"generate manifests"| BuildPkg
    CLI -->|"use static templates"| Hack
    CLI -->|"spin up cluster"| KindMgr
    KindMgr -->|"docker drive"| Docker
    KindMgr -->|"create Kind cluster"| APIServer
    BuildPkg -->|"apply CRDs & resources"| APIServer
    CRDDefs -->|"registered at startup"| APIServer
    APIServer -->|"watch events"| ControllerMgr
    ControllerMgr -->|"reconcile CustomPackage, GitRepository, LocalBuild"| APIServer
    APIServer -->|"serve events"| GitCtrl
    APIServer -->|"serve events"| CPkgCtrl
    APIServer -->|"serve events"| LBldCtrl
    GitCtrl -->|"reconcile GitRepository"| APIServer
    GitCtrl -->|"clone/mirror"| GitHub
    CPkgCtrl -->|"reconcile CustomPackage"| APIServer
    LBldCtrl -->|"reconcile LocalBuild"| APIServer
    APIServer -->|"create workloads"| Argo
    APIServer -->|"create workloads"| Gitea
    APIServer -->|"create workloads"| Ingress
    APIServer -->|"create workloads"| CoreDNS
    APIServer -->|"create workloads"| Backstage

    %% Click Events
    click CLI "https://github.com/cnoe-io/idpbuilder/tree/main/pkg/cmd"
    click BuildPkg "https://github.com/cnoe-io/idpbuilder/tree/main/pkg/build"
    click Hack "https://github.com/cnoe-io/idpbuilder/tree/main/hack"
    click KindMgr "https://github.com/cnoe-io/idpbuilder/tree/main/pkg/kind"
    click CRDDefs "https://github.com/cnoe-io/idpbuilder/tree/main/api/v1alpha1"
    click ControllerMgr "https://github.com/cnoe-io/idpbuilder/tree/main/pkg/controllers"

    %% Styles
    classDef user fill:#e5f5e0,stroke:#31b354,color:#000
    classDef control fill:#e0ecf4,stroke:#2b8cbe,color:#000
    classDef provision fill:#fde0dd,stroke:#fb6a4a,color:#000
    classDef k8s fill:#fff7bc,stroke:#fdae61,color:#000
    classDef controllers fill:#e7e1ef,stroke:#7b3294,color:#000
    classDef workloads fill:#f0f0f0,stroke:#636363,color:#000
    classDef external fill:#fee8c8,stroke:#d95f0e,color:#000
```
