# evald24/go-gen-config architecture

> Architecture diagram of the GitHub repository evald24/go-gen-config, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evald24/go-gen-config
- Repository: https://github.com/evald24/go-gen-config

## Overview

##### Project type and purpose
- This is an open-source CLI tool written in Go (“go-gen-config”) whose sole purpose is to generate strongly typed Go code and default YAML configuration files from a user-provided YAML template, with support for environment variables and hot-reload.

##### File structure
- **cmd/go-gen-config**: entrypoint for the CLI.
- **internal/generator**: core logic that reads the template, builds an AST/representation, and emits Go source code.
- **internal/helpers** & **pkg/helpers**: utility functions (e.g., file I/O, environment lookup, string conversion).
- **example**: sample template, generated code, and a small Go app showing how to consume the generated config with init, get, and hot-reload.
- **go.mod/go.sum**: external dependencies (e.g., YAML parsing, OS signal handling).

##### README for additional insights
- Workflow:
a. User runs `go-gen-config -t template.yaml -o config.gen.go -c config.yaml`.
b. CLI parses flags → loads template → merges defaults + env → writes generated YAML + Go code.
- Runtime usage: generated package exposes `Init()`, `GetConfig()`, `UpdateConfig()` and a hot-reload example reacting to SIGHUP.

a. Main components
- CLI Binary (cmd/go-gen-config)
- Template Parser & Model (internal/generator)
- Code Generator (internal/generator)
- File I/O & Env Provider (internal/helpers & pkg/helpers)
- Example Consumer App (example/main.go)
- External libraries: YAML parser, OS/signal APIs
b. Relationships & interactions
1. User invokes CLI → CLI Flag Parser reads `-t`, `-o`, `-c`.
2. Template Parser loads `template.yaml` (via YAML library).
3. Env Provider fetches environment variables.
4. Generator merges template defaults + env → produces:
- Generated Go file (`config.gen.go`)
- Updated YAML config file (`config.yaml`)
5. Example App imports the generated code:
- Calls `Init(configPath)` → File I/O reads YAML + env → populates `Config` struct.
- `GetConfig()` returns in-memory config.
- Signal watcher invokes `UpdateConfig()` on SIGHUP.
c. Architectural patterns & design principles
- Single-responsibility: CLI handling, code generation, template parsing, helpers are separated.
- Dependency inversion: internal packages expose clean interfaces; external libraries are swappable.
- Hot-reload via observer (OS signals → callback).
d. Key technologies & libraries
- Go standard library: `flag`, `os`, `io/ioutil`, `text/template` (if used), `signal`.
- YAML parser: (e.g., `gopkg.in/yaml.v2`).
- Go code generation: AST or text/template in `internal/generator`.

##### Detailed breakdown of components
- **User CLI** (cmd/go-gen-config)
– Reads flags
– Invokes generator
- **Template Parser** (internal/generator/template.go)
– Parses template.yaml → in-memory representation
- **Generator Core** (internal/generator/generator.go)
– Walks representation → builds Go AST/text → writes Go file
- **Helpers** (internal/helpers + pkg/helpers)
– Env var lookup, file read/write, naming conversions
- **Disk**
– template.yaml (input)
– config.gen.go (output)
– config.yaml (optional output)
- **Example App** (example/main.go)
– Init(), GetConfig(), UpdateConfig(), hot-reload loop
- **External Libs**
– YAML parser
– OS/signal APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global actor
    UserCLI["User CLI"]:::external

    subgraph "Generation Pipeline"
        CLI["CLI Binary"]:::internal
        Flags["Flag Parser"]:::internal
        TemplateParser["Template Parser"]:::internal
        GeneratorCore["Generator Core"]:::internal
        InternalHelpers["Internal Helpers"]:::internal
        PublicHelpers["Public Helpers"]:::internal
        YAMLLib["YAML Parser"]:::external
        OSAPI["OS/Signal API"]:::external
        DiskTemplate["template.yaml"]:::file
        DiskGenGo["config.gen.go"]:::file
        DiskGenYAML["config.yaml"]:::file
        DepManifest["go.mod"]:::file
    end

    subgraph "Runtime Example"
        ExampleApp["Example App"]:::internal
        Init["Init()"]:::internal
        GetCfg["GetConfig()"]:::internal
        SignalHandler["Signal Handler"]:::internal
        UpdateCfg["UpdateConfig()"]:::internal
        ConfigStore["Config Store"]:::internal
    end

    %% Generation flow
    UserCLI --> CLI
    CLI --> Flags
    CLI --> DepManifest
    Flags --> TemplateParser
    TemplateParser -->|uses| YAMLLib
    TemplateParser --> DiskTemplate
    TemplateParser --> GeneratorCore
    GeneratorCore --> InternalHelpers
    GeneratorCore --> PublicHelpers
    GeneratorCore --> DiskGenGo
    GeneratorCore --> DiskGenYAML

    %% Runtime flow
    ExampleApp --> Init
    Init --> DiskGenYAML
    Init --> InternalHelpers
    Init --> PublicHelpers
    Init --> ConfigStore
    ExampleApp --> GetCfg
    GetCfg --> ConfigStore
    ExampleApp --> SignalHandler
    SignalHandler --> OSAPI
    SignalHandler --> UpdateCfg
    UpdateCfg --> ConfigStore

    %% Click events
    click CLI "https://github.com/evald24/go-gen-config/blob/main/cmd/go-gen-config/main.go"
    click TemplateParser "https://github.com/evald24/go-gen-config/blob/main/internal/generator/template.go"
    click GeneratorCore "https://github.com/evald24/go-gen-config/blob/main/internal/generator/generator.go"
    click InternalHelpers "https://github.com/evald24/go-gen-config/blob/main/internal/helpers/helpers.go"
    click PublicHelpers "https://github.com/evald24/go-gen-config/blob/main/pkg/helpers/helpers.go"
    click DiskTemplate "https://github.com/evald24/go-gen-config/blob/main/example/config.template.yaml"
    click DiskGenYAML "https://github.com/evald24/go-gen-config/blob/main/example/config.yaml"
    click DiskGenGo "https://github.com/evald24/go-gen-config/blob/main/example/config/config.gen.go"
    click ExampleApp "https://github.com/evald24/go-gen-config/blob/main/example/main.go"
    click DepManifest "https://github.com/evald24/go-gen-config/blob/main/go.mod"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000;
    classDef file fill:#90EE90,stroke:#000;
    classDef external fill:#FFDAB9,stroke:#000;
```
