# martinmares/kube_build_app architecture

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

- Interactive diagram: https://gitdiagram.com/martinmares/kube_build_app
- Repository: https://github.com/martinmares/kube_build_app

## Overview

##### Project type and purpose
- This is a Ruby-based CLI tool (`kube_build_app`) whose sole purpose is to *generate* Kubernetes manifest YAML files from a simple directory structure of environment descriptors, application definitions and asset files.
- There is no long-running service, database or external API calls—this is a single-command, file-transformer tool.

##### File structure
- Top-level:
- bin/kube_build_app – the CLI entrypoint
- lib/kube_build_app/*.rb – core library code
- README.md, Gemfile, LICENSE, .gitignore
- Under `lib/kube_build_app` you see classes/modules:
- main.rb – coordinates the build
- application.rb, container.rb, service.rb, ingress.rb, asset.rb, env.rb
- kube_utils.rb, encjson.rb, utils.rb – shared helpers
- No database or HTTP server components; everything is file-based I/O.

##### README for additional insights
- The workflow reads:
- `env.secured.json` / `env.unsecured.json` – JSON environment variables
- `environments/<env>/apps/*.yml` – application descriptors
- `environments/<env>/assets/*` – static files (e.g. nginx.conf)
- Outputs to `deployments/<env>/deploy/…` directories:
– ConfigMaps, Deployments, Services, Ingresses

##### Main components
a. **Inputs**
- File System:
– JSON config files (`env.*.json`)
– YAML app descriptors
– Static asset files
b. **Core Processing Modules**
- `bin/kube_build_app` (CLI)
- `KubeBuildApp::Main` – parses flags, initiates build
- `Env` – loads JSON environment
- `Application` – loads app YAML, owns Container + Asset definitions
- `Container`, `Asset`, `Service`, `Ingress` – build object graph
- `EncJSON`, `KubeUtils`, `Utils` – support for encoding and rendering
c. **Output**
- File System writer: emits Kubernetes YAML (ConfigMap, Deployment, Service, Ingress) to `deployments/<env>/deploy`
d. **External Dependencies**
- Ruby stdlib and any gems in Gemfile (likely `yaml`, `json`)
- No live Kubernetes API calls—only file output

##### Relationships & interactions
1) **CLI invocation**
-> `Main`
2) **Main**
-> reads JSON via `Env`
-> scans `environments/<env>` for app YAML & assets
-> instantiates one `Application` object per YAML
3) **Application**
-> uses `Container`, `Asset` classes to model each container and asset
-> builds `Service` + `Ingress` definitions
4) **Rendering**
-> uses `EncJSON` & `KubeUtils` to produce correctly structured manifests
5) **Writer**
-> writes files into `deployments/<env>/deploy/{assets,deployments,services}`

##### Architectural patterns/design principles
- **Modular object model**: each Kubernetes concept is its own class
- **Single responsibility**: parsing, modeling and rendering are separated
- **File-transformer CLI**: no long-lived processes, purely input→object graph→output
- **Convention over configuration**: fixed directory conventions drive behavior

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Inputs
    subgraph "Inputs"
        JSON["JSON Environment Files"]:::input
        YAML["YAML App Descriptors"]:::input
        ASSETS["Static Asset Files"]:::input
    end

    %% Processing Modules
    subgraph "Processing Modules"
        CLI["CLI Entrypoint\nbin/kube_build_app"]:::process
        Main["KubeBuildApp::Main\n(main.rb)"]:::process
        Env["KubeBuildApp::Env\n(env.rb)"]:::process
        App["KubeBuildApp::Application\n(application.rb)"]:::process
        Container["KubeBuildApp::Container\n(container.rb)"]:::process
        Asset["KubeBuildApp::Asset\n(asset.rb)"]:::process
        Service["KubeBuildApp::Service\n(service.rb)"]:::process
        Ingress["KubeBuildApp::Ingress\n(ingress.rb)"]:::process
        EncJSON["KubeBuildApp::EncJSON\n(encjson.rb)"]:::process
        KubeUtils["KubeBuildApp::KubeUtils\n(kube_utils.rb)"]:::process
        Utils["KubeBuildApp::Utils\n(utils.rb)"]:::process
        Writer["File Writer"]:::process
    end

    %% Outputs
    subgraph "Outputs"
        Out["Kubernetes YAML Manifests\n(ConfigMap, Deployment, Service, Ingress)"]:::output
    end

    %% Data Flow
    JSON -->|"load JSON"| Env
    YAML -->|"parse YAML"| App
    ASSETS -->|"load assets"| Asset

    CLI -->|"invoke build"| Main
    Main -->|"read env"| Env
    Main -->|"scan apps"| App
    App -->|"model containers"| Container
    App -->|"model assets"| Asset
    App -->|"model services"| Service
    App -->|"model ingresses"| Ingress

    Container -->|"build object graph"| EncJSON
    Asset --> EncJSON
    Service --> EncJSON
    Ingress --> EncJSON

    EncJSON -->|"encode to JSON"| KubeUtils
    KubeUtils -->|"render YAML"| Writer
    Utils --> Writer

    Writer -->|"write files"| Out

    %% Click Events
    click CLI "https://github.com/martinmares/kube_build_app/tree/main/bin/kube_build_app"
    click Main "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/main.rb"
    click Env "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/env.rb"
    click App "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/application.rb"
    click Container "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/container.rb"
    click Asset "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/asset.rb"
    click Service "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/service.rb"
    click Ingress "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/ingress.rb"
    click EncJSON "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/encjson.rb"
    click KubeUtils "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/kube_utils.rb"
    click Utils "https://github.com/martinmares/kube_build_app/blob/main/lib/kube_build_app/utils.rb"

    %% Styles
    classDef input fill:#cce5ff,stroke:#4d94ff,color:#000;
    classDef process fill:#d4edda,stroke:#28a745,color:#000;
    classDef output fill:#fff3cd,stroke:#ffcd39,color:#000;
```
