# k0rdent/catalog architecture

> Architecture diagram of the GitHub repository k0rdent/catalog, 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/catalog
- Repository: https://github.com/k0rdent/catalog

## Overview

##### Project type and purpose
- This is an infrastructure‐as‐code/catalog repository, not a traditional full‐stack app.
- It serves two main functions:
- Maintain a curated catalog of Helm charts and Kubernetes resources under `apps/`.
- Generate and deploy a static documentation/website via MkDocs (`mkdocs/`, `docs/`, `overrides/`, `mkdocs.yml`).
- CI/CD (in `.github/workflows/`) automates testing of charts, building the site, and deploying artifacts.

##### File‐structure analysis
- Top-level directories:
- `.github/workflows/` – GitHub Action YAMLs for testing, cleaning artifacts, building Helm charts, deploying the MkDocs site to GitHub Pages.
- `apps/` – Hundreds of subfolders, each containing:
– `charts/` (versioned Helm charts and service-template wrappers)
– `data.yaml` (metadata for catalog entries)
– `example/` (sample values and Chart.yaml)
- `mkdocs/` and `docs/` – Source Markdown, templates, and CSS for documentation.
- `overrides/` – HTML/Liquid overrides to customize the MkDocs theme.
- `scripts/` – Python and shell utilities to lint, test (via Kind or cluster config), package, and deploy charts.
- Key config files: `mkdocs.yml` for site build, `scripts/requirements.txt`, various `config/*.yaml` for test clusters, `chart_ctl.py` and cluster‐management scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Actors
    Dev["Developer / Contributor"]:::external
    Users["End Users"]:::external

    %% Repository Components
    subgraph "GitHub Repository" 
        style GitHubRepository stroke:#000,stroke-width:1,fill:none
        Catalog["Catalog Entries\n(apps/)"]:::source
        MkCfg["MkDocs Config\n(mkdocs.yml)"]:::source
        MkSrc["MkDocs Source & Generators\n(mkdocs/)"]:::source
        Overrides["Theme Overrides\n(overrides/)"]:::source
        ScriptsDir["Scripts & Utils\n(scripts/)"]:::source
        CIWorkflows["GitHub Actions Workflows\n(.github/workflows/)"]:::source
    end

    %% CI/CD Engine
    CI["CI/CD Engine\n(GitHub Actions)"]:::process

    %% Workflows
    subgraph "Workflows" 
        cwf["Cleanup Workflow"]:::process
        hcb["Helm Chart Build"]:::process
        had["Helm App Deploy"]:::process
        ghd["Pages Deploy"]:::process
        rbw["Reusable Build"]:::process
    end

    %% Scripts
    subgraph "Scripts Layer"
        ctl["Chart Control Utility"]:::process
        addrepo["Helm Repo Setup Script"]:::process
        config["Test Cluster Configurations"]:::process
        kind["Kind Provisioning Script"]:::process
        deploycld["Cluster Deploy/Cleanup"]:::process
        installst["ServiceTemplate Installer"]:::process
        deployweb["Web Deploy Script"]:::process
        spell["Spellcheck & Site Validation"]:::process
    end

    %% Testing Environment
    TestEnv["Testing Environment\n(Kind / Kubernetes)"]:::process

    %% Artifact Stores & Outputs
    HelmStore["Helm Artifact Store"]:::output
    MkGen["MkDocs Generator"]:::process
    StaticSite["Static Site Output"]:::output
    Pages["GitHub Pages Hosting"]:::external
    DocsOut["Documentation Output\n(docs/)"]:::output

    %% Flows
    Dev -->|push| Catalog
    Dev -->|push| MkCfg
    Dev -->|push| MkSrc
    Dev -->|push| Overrides
    Dev -->|push| ScriptsDir
    Dev -->|push| CIWorkflows

    CIWorkflows -->|trigger| CI

    CI -->|invoke| cwf
    CI -->|invoke| hcb
    CI -->|invoke| had
    CI -->|invoke| ghd
    CI -->|invoke| rbw

    hcb -->|invoke| ctl
    hcb -->|invoke| addrepo
    hcb -->|invoke| config

    config -->|provision| kind
    kind -->|deploy| deploycld
    deploycld -->|validate| installst
    installst -->|report| ctl

    hcb -->|package| HelmStore

    ghd -->|invoke| MkGen
    MkGen -->|build| StaticSite
    StaticSite -->|deploy| Pages

    Users -->|HTTP| Pages
    Users -->|Helm CLI| HelmStore

    %% Click Events
    click cwf "https://github.com/k0rdent/catalog/blob/main/.github/workflows/cleanup-untagged-artifacts.yml"
    click hcb "https://github.com/k0rdent/catalog/blob/main/.github/workflows/helm-chart-build.yml"
    click had "https://github.com/k0rdent/catalog/blob/main/.github/workflows/helm-app-deploy.yml"
    click ghd "https://github.com/k0rdent/catalog/blob/main/.github/workflows/gh-pages-deploy.yml"
    click rbw "https://github.com/k0rdent/catalog/blob/main/.github/workflows/reusable-build.yml"
    click Catalog "https://github.com/k0rdent/catalog/tree/main/apps/"
    click MkCfg "https://github.com/k0rdent/catalog/blob/main/mkdocs.yml"
    click MkSrc "https://github.com/k0rdent/catalog/tree/main/mkdocs/"
    click Overrides "https://github.com/k0rdent/catalog/tree/main/overrides/"
    click DocsOut "https://github.com/k0rdent/catalog/tree/main/docs/"

    %% Styles
    classDef source fill:#cbe0f4,stroke:#0366d6,color:#0366d6;
    classDef process fill:#d4f4dd,stroke:#28a745,color:#28a745;
    classDef output fill:#fde1a9,stroke:#d9930e,color:#d9930e;
    classDef external fill:#eeeeee,stroke:#666666,color:#333333;
```
