# idsulik/helm-cel architecture

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

- Interactive diagram: https://gitdiagram.com/idsulik/helm-cel
- Repository: https://github.com/idsulik/helm-cel

## Overview

##### Project Type and Purpose
- This is a command-line Helm plugin written in Go. It integrates with the Helm CLI (via `helm plugin install`) or can run in a Docker container. Its two main functions are:
- validate: load user chart values and CEL rules, run expressions to enforce constraints
- generate: scan chart values and emit a skeletal CEL rules file
- Key indicators: `cmd/helm-cel/main.go` as entrypoint, `pkg/validator` and `pkg/generator` subdirectories, README describing Helm commands and Docker usage.

##### File Structure Analysis
- Top-level
- cmd/helm-cel – CLI entrypoint and command-registration
- pkg/generator – “generate” logic, building rules from values
- pkg/validator – “validate” logic, loading values, loading rules, invoking CEL engine
- pkg/models – shared data structures (e.g., chart values, rule definitions)
- pkg/utils – file I/O helpers
- scripts, Dockerfile, GitHub workflows – build/test/release automation
- Patterns
- Layered CLI architecture:
– Presentation (cmd)
– Application / orchestration (generator & validator packages)
– Domain models
– Infrastructure (utils for file loading, external calls)
- Config & Deployment
- Dockerfile for containerized plugin
- goreleaser, GitHub Actions workflows for build/test/release

##### README Insights
- Describes command names, flags, input/output formats, exit codes
- Discusses how rules are structured (`.cel.yaml`), how expressions are reused
- Mentions integration points: reading from file system, writing to stdout/exit codes, Helm plugin interface

a. Main Components
- CLI Front-end
- Command Dispatcher (parses flags, selects “validate” or “generate”)
- Generator Module
- Validator Module
- CEL Expression Engine (third-party library)
- File System (chart directory, values.yaml, .cel.yaml files)
- Output Renderer (text/json/yaml)
- External Dependencies: Helm CLI, Docker runtime (optional)
b. Relationships & Data Flows
- User invokes `helm cel validate` or Docker wrapper → CLI Front-end
- Dispatcher loads values files via File System → hands off to Validator
- Validator loads rules, invokes CEL Engine, produces a result object
- Result goes to Output Renderer → stdout, exit code
- Generator follows analogous flow: read values, build rule skeletons, write .cel.yaml
- All components depend on Models to share data definitions
c. Architectural Patterns
- Layered separation of concerns
- Dependency injection of file-loading and expression evaluation
- Plugin-style entrypoint decoupled from core logic
d. Technologies & Frameworks
- Go 1.22+, Go modules
- CEL library for expression parsing and evaluation
- Helm Plugin SDK (implicit via CLI approach)
- Docker for container distribution
- GitHub Actions & goreleaser for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation (CLI Layer)"
        CLI["CLI Front-end"] 
        Dispatcher["Command Dispatcher"]
    end

    %% Application Logic
    subgraph "Application Logic"
        Generator["Generator Module"]
        Validator["Validator Module"]
        RulesLoader["Rules Loader"]
        ExpressionProcessor["Expressions Processor"]
        ValuesLoader["Values Loader"]
        Renderer["Output Renderer"]
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        Models["Shared Models"]
        FSHelpers["File System Helpers"]
    end

    %% External Dependencies
    subgraph "External"
        HelmCLI["Helm CLI"]
        Docker["Docker Runtime"]
        CEL["CEL Expression Engine"]
        PluginMeta["Plugin Metadata"]
        CI1["GH Actions: docker"]
        CI2["GH Actions: tests"]
        CI3["GH Actions: release"]
        GoRel["GoReleaser"]
        IntTests["Integration Tests"]
        IntTests2["Integration Output Tests"]
    end

    %% Relationships
    HelmCLI -->|invokes| CLI
    Docker -->|wraps| CLI
    PluginMeta --> CLI

    CLI --> Dispatcher
    Dispatcher -->|"validate command"| ValuesLoader
    Dispatcher -->|"validate command"| RulesLoader
    Dispatcher -->|"generate command"| ValuesLoader
    Dispatcher -->|"generate command"| Generator

    ValuesLoader -->|loads Values YAML| Models
    RulesLoader -->|loads .cel.yaml rules| Models
    Generator -->|builds rule skeletons| Models
    Generator -->|writes .cel.yaml| FSHelpers

    Models --> Validator
    FSHelpers --> Validator
    Models --> Generator

    Validator --> ExpressionProcessor
    ExpressionProcessor -->|evaluates CEL AST| CEL
    CEL --> ExpressionProcessor
    ExpressionProcessor -->|returns results| Validator

    Validator --> Renderer
    Renderer -->|outputs to stdout/exit code| CLI

    CI1 --> Docker
    CI2 --> CLI
    CI3 --> CLI
    GoRel --> CI3
    IntTests --> CLI
    IntTests2 --> CLI

    %% Click Events
    click CLI "https://github.com/idsulik/helm-cel/blob/main/cmd/helm-cel/main.go"
    click Dispatcher "https://github.com/idsulik/helm-cel/blob/main/cmd/helm-cel/main.go"
    click Generator "https://github.com/idsulik/helm-cel/blob/main/pkg/generator/generator.go"
    click RulesLoader "https://github.com/idsulik/helm-cel/blob/main/pkg/validator/rules_loader.go"
    click ExpressionProcessor "https://github.com/idsulik/helm-cel/blob/main/pkg/validator/expression_processor.go"
    click ValuesLoader "https://github.com/idsulik/helm-cel/blob/main/pkg/validator/values_loader.go"
    click Validator "https://github.com/idsulik/helm-cel/blob/main/pkg/validator/validator.go"
    click Models "https://github.com/idsulik/helm-cel/blob/main/pkg/models/models.go"
    click FSHelpers "https://github.com/idsulik/helm-cel/blob/main/pkg/utils/file.go"
    click PluginMeta "https://github.com/idsulik/helm-cel/blob/main/plugin.yaml"
    click Docker "https://github.com/idsulik/helm-cel/tree/main/Dockerfile"
    click CI1 "https://github.com/idsulik/helm-cel/blob/main/.github/workflows/docker.yml"
    click CI2 "https://github.com/idsulik/helm-cel/blob/main/.github/workflows/tests.yml"
    click CI3 "https://github.com/idsulik/helm-cel/blob/main/.github/workflows/release.yml"
    click GoRel "https://github.com/idsulik/helm-cel/blob/main/.goreleaser.yml"
    click IntTests "https://github.com/idsulik/helm-cel/blob/main/tests/integration/validation_test.go"
    click IntTests2 "https://github.com/idsulik/helm-cel/blob/main/tests/integration/validation_output_test.go"

    %% Styles
    classDef presentation fill:#ccf,stroke:#333,stroke-width:1px;
    classDef application fill:#cfc,stroke:#333,stroke-width:1px;
    classDef infrastructure fill:#ffc,stroke:#333,stroke-width:1px;
    classDef external fill:#ddd,stroke:#333,stroke-width:1px;

    class CLI,Dispatcher presentation;
    class Generator,Validator,RulesLoader,ExpressionProcessor,ValuesLoader,Renderer application;
    class Models,FSHelpers infrastructure;
    class HelmCLI,Docker,CEL,PluginMeta,CI1,CI2,CI3,GoRel,IntTests,IntTests2 external;
```
