# macropower/kclipper architecture

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

- Interactive diagram: https://gitdiagram.com/macropower/kclipper
- Repository: https://github.com/macropower/kclipper

## Overview

Based on your project’s file tree and README, kclipper is a CLI tool and library that extends KCL with seamless Helm integration. It wraps standard KCL commands with additional plugins and chart-management capabilities; in short, it is a superset of KCL that lets users work naturally with Helm charts (including rendering, schema generation, and updating) while still keeping full KCL compatibility. The project is written in Go and follows a layered, modular design architecture for handling CLI commands, chart management, JSON schema generation, plugin behavior, and integration with external tooling (like Argo CD and Docker).

##### Main components
- CLI / Command Interface: Represented by the “cmd/kclipper” directory (with its sub-commands such as chart, export, version, etc.) and “cmd/gen” for generation commands.
- Core Business Logic & Libraries: Capture the “pkg” directory which splits into multiple modules:
– Helm & Chart Management: (pkg/helm, pkg/kclchart, pkg/kclhelm) handle chart templating, configuration, and rendering.
– Schema Generation & Validation: (pkg/jsonschema) takes care of generating JSON Schemas, inferring values, and managing references.
– Utility and Plugin Support: (pkg/kclutil, pkg/plugin, pkg/syncutil, pkg/pathutil) support operations, file manipulations, concurrency, and external integrations.
– Logging and Versioning: (pkg/log and pkg/version) provide the logging framework and version management logic.
- Modules for KCL Extensions: The “modules” directory integrates additional KCL modules (like those for helm and filepath) that define friendly plugin interfaces.
- Infrastructure & Deployment: Represent ancillary configurations (Taskfile.yaml, Dockerfile, GitHub workflows in .github, and Devbox files) that provide build, deployment, testing, and CI/CD support.

##### Relationships and interactions
- The CLI layer (entry-point) accepts user commands which are routed to the core business logic libraries.
- The business logic layer orchestrates chart processing: it reads chart definitions from (charts.k) and then, via Helm-related packages (pkg/helm, pkg/kclhelm), renders charts by calling Helm APIs and applying custom post-render logic (as shown in the README examples).
- Schema generation libraries (pkg/jsonschema) are invoked during chart updates to automatically generate or validate the accompanying JSON Schemas.
- Plugin support abstracts integration with additional file formats (pkg/plugin) and extends functionality based on external KCL plugins.
- Integration with external services is depicted where the rendered output can be further utilized by GitOps workflows (Argo CD) and Docker-based deployments.

##### Architectural patterns/design principles
- A layered architecture segregating the CLI, business logic (rendering, chart management, schema generation), and utility layers.
- Modular design: The “pkg” directory is broken out into specific, purpose-built submodules (like helm, kclutil, jsonschema), making it easier to maintain, test, and extend.
- Use of plugins and extension points that allow for additional functionality (for example, the Helm and file path plugins) and pluggable schema generators.
- Integration of configuration management and CI/CD practices (using GitHub workflows, Taskfile, Docker, and Devbox configuration).

##### Relevant technologies and frameworks
- Go (the primary programming language for the CLI and libraries).
- KCL (the underlying constraint-based language that kclipper extends).
- Helm (as both a dependency and the core domain in which rendering and chart management operate).
- Integration points with cloud-native approaches (Argo CD, Docker, OCI registries) and testing (Taskfile and GitHub workflows).

##### Overall structure
- Middle Layer: Application Core – encapsulate business logic and libraries split by domain (chart management, schema generation, plugin management).
- Bottom Layer: Infrastructure & External Integration – indicate deployment, external repositories, CI/CD tooling.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Top Layer: CLI & User Interaction
    subgraph "CLI & User Interaction"
        cli_kclipper["CLI (cmd/kclipper)"]:::cli
        cli_gen["CLI Generator (cmd/gen)"]:::cli
    end

    %% Middle Layer: Core Business Logic & Libraries
    subgraph "Core Business Logic & Libraries"
        %% Chart & Helm Management
        subgraph "Chart & Helm Management"
            pkg_helm["Helm Management (pkg/helm)"]:::core
            pkg_kclchart["KCL Chart (pkg/kclchart)"]:::core
            pkg_kclhelm["KCL Helm (pkg/kclhelm)"]:::core
        end
        pkg_jsonschema["Schema Generation (pkg/jsonschema)"]:::core

        %% Utility & Plugin Support
        subgraph "Utility & Plugin Support"
            pkg_kclutil["KCL Utility (pkg/kclutil)"]:::core
            pkg_plugin["Plugin Support (pkg/plugin)"]:::core
            pkg_syncutil["Sync Utility (pkg/syncutil)"]:::core
            pkg_pathutil["Path Utility (pkg/pathutil)"]:::core
        end

        %% Logging & Versioning
        subgraph "Logging & Versioning"
            pkg_log["Logging (pkg/log)"]:::core
            pkg_version["Versioning (pkg/version)"]:::core
        end

        %% Modules for KCL Extensions
        subgraph "Modules for KCL Extensions"
            modules["Modules (modules)"]:::core
            modules_helm["Modules - Helm (modules/helm)"]:::core
            modules_filepath["Modules - Filepath (modules/filepath)"]:::core
        end
    end

    %% Bottom Layer: Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        infra_taskfile["Taskfile.yaml"]:::infra
        infra_dockerfile["Dockerfile"]:::infra
        infra_github["GitHub Workflows (.github)"]:::infra
        devbox_json["Devbox Config (devbox.json)"]:::infra
        devbox_lock["Devbox Lock (devbox.lock)"]:::infra
    end

    %% External Integrations
    subgraph "External Integrations"
        external_argocd["Argo CD"]:::external
        external_docker["Docker Registry"]:::external
    end

    %% Relationships from CLI to Core Business Logic
    cli_kclipper -->|"triggers"| pkg_helm
    cli_kclipper -->|"triggers"| pkg_kclchart
    cli_kclipper -->|"triggers"| pkg_kclhelm
    cli_kclipper -->|"initiates"| pkg_jsonschema
    cli_kclipper -->|"logs"| pkg_log
    cli_kclipper -->|"version"| pkg_version
    cli_gen -->|"generates"| pkg_jsonschema

    %% Internal Business Logic Relationships
    pkg_helm -->|"configures"| pkg_kclchart
    pkg_helm -->|"renders"| pkg_kclhelm
    pkg_helm -->|"auto-genSchema"| pkg_jsonschema

    pkg_kclhelm -->|"invokes"| pkg_plugin
    pkg_plugin -->|"utilizes"| pkg_kclutil
    pkg_plugin -->|"handlesPaths"| pkg_pathutil
    pkg_plugin -->|"syncs"| pkg_syncutil

    pkg_kclhelm -->|"extendsVia"| modules
    pkg_kclhelm -->|"usesHelmModule"| modules_helm
    pkg_kclhelm -->|"usesFilepathModule"| modules_filepath

    %% Business Logic to External Integrations
    pkg_kclhelm -->|"deploysTo"| external_argocd
    pkg_kclhelm -->|"buildsImage"| external_docker

    %% Business Logic to Infrastructure & Deployment
    pkg_kclhelm -->|"triggersCI"| infra_taskfile
    pkg_kclhelm -->|"dockerBuild"| infra_dockerfile
    pkg_kclhelm -->|"runsWorkflows"| infra_github
    pkg_kclhelm -->|"devboxConfig"| devbox_json
    pkg_kclhelm -->|"devboxLock"| devbox_lock

    %% Click Events for CLI / Command Interface
    click cli_kclipper "https://github.com/macropower/kclipper/tree/main/cmd/kclipper"
    click cli_gen "https://github.com/macropower/kclipper/tree/main/cmd/gen"

    %% Click Events for Helm & Chart Management
    click pkg_helm "https://github.com/macropower/kclipper/tree/main/pkg/helm"
    click pkg_kclchart "https://github.com/macropower/kclipper/tree/main/pkg/kclchart"
    click pkg_kclhelm "https://github.com/macropower/kclipper/tree/main/pkg/kclhelm"

    %% Click Event for Schema Generation & Validation
    click pkg_jsonschema "https://github.com/macropower/kclipper/tree/main/pkg/jsonschema"

    %% Click Events for Utility and Plugin Support
    click pkg_kclutil "https://github.com/macropower/kclipper/tree/main/pkg/kclutil"
    click pkg_plugin "https://github.com/macropower/kclipper/tree/main/pkg/plugin"
    click pkg_syncutil "https://github.com/macropower/kclipper/tree/main/pkg/syncutil"
    click pkg_pathutil "https://github.com/macropower/kclipper/tree/main/pkg/pathutil"

    %% Click Events for Logging and Versioning
    click pkg_log "https://github.com/macropower/kclipper/tree/main/pkg/log"
    click pkg_version "https://github.com/macropower/kclipper/tree/main/pkg/version"

    %% Click Events for Modules for KCL Extensions
    click modules "https://github.com/macropower/kclipper/tree/main/modules"
    click modules_helm "https://github.com/macropower/kclipper/tree/main/modules/helm"
    click modules_filepath "https://github.com/macropower/kclipper/tree/main/modules/filepath"

    %% Click Events for Infrastructure & Deployment
    click infra_taskfile "https://github.com/macropower/kclipper/blob/main/Taskfile.yaml"
    click infra_dockerfile "https://github.com/macropower/kclipper/tree/main/Dockerfile"
    click infra_github "https://github.com/macropower/kclipper/blob/main/.github"
    click devbox_json "https://github.com/macropower/kclipper/blob/main/devbox.json"
    click devbox_lock "https://github.com/macropower/kclipper/blob/main/devbox.lock"

    %% Styling
    classDef cli fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef core fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef infra fill:#f94144,stroke:#000,stroke-width:2px;
    classDef external fill:#277da1,stroke:#000,stroke-width:2px;
```
