# inderpooni/orale architecture

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

- Interactive diagram: https://gitdiagram.com/inderpooni/orale
- Repository: https://github.com/inderpooni/orale

## Overview

##### Project type and purpose
- Orale is an open-source Go library whose sole responsibility is to collect configuration data from three sources—command-line flags, environment variables, and configuration files—and then marshal that data into user-defined Go structs. It does not include a server or UI; it is purely a reusable tool/library.

##### File structure
- Top-level Go source files (file.go, get.go, load.go, loader.go) represent discrete logical modules of the loader.
- Corresponding *_test.go files verify each module’s behavior.
- The `test-assets` directory holds sample TOML files (and a test directory) used by the file-loader tests.
- `go.mod`/`go.sum` declare dependencies (e.g., TOML parser) and module version.

##### Key points from the README
- API surface: Load(name) → returns a Loader instance, then Loader.Get/ GetAll → populates a struct.
- Sources in order: flags, environment variables, file(s).
- Uses snake_case convention for config paths and TOML file sections.

a. Client Application
- Calls `orale.Load("app-name")`
- Invokes `Get` or `GetAll` on the returned object
b. Orale Core
- Loader Manager (loader.go) – orchestrates all source loaders
- Flag Loader (file.go/get.go?) – reads os.Args or uses the Go flag library
- Env Loader (loader.go / load.go) – reads from `os.Environ()` matching prefix+separator
- File Loader (load.go/file.go) – discovers and parses `<app>.config.toml` via a TOML parser
- Merger & Unmarshaller (get.go) – merges key/value maps in priority order, uses reflection to fill user structs
c. External Libraries
- Go standard packages (flag, os, reflect)
- Third-party TOML parser (imported in load.go)
d. Test Harness
- `test-assets` folder
- Individual test suites invoking each loader in isolation

##### Relationships and interactions
- The Client Application invokes the Loader Manager’s API.
- Loader Manager invokes each Source Loader in turn:
1. Flag Loader → produces map[string]string
2. Env Loader → produces map[string]string
3. File Loader → produces map[string]interface{} from TOML
- The three maps are merged in priority (flags > env > file).
- Merger passes the final map to the Unmarshaller, which uses reflection to populate the user’s struct.
- Finally, the populated struct is returned to the client code.

##### Architectural patterns and design principles
- Single Responsibility: each loader handles one source.
- Strategy Pattern: Loader Manager holds a slice of Loader interfaces, allowing adding new loaders (e.g., a Consul loader).
- Convention over configuration: snake_case paths, fixed file naming pattern.
- Test-driven design: each module has its own test file and test assets.

##### Elements
- Client Application
- Loader Manager
- Flag Loader
- Env Loader
- File Loader
- Merger & Unmarshaller
- External TOML Parser
- App → Loader Manager.Load
- Manager → [Flag Loader, Env Loader, File Loader]
- Each Loader → returns key/value data
- Manager → Merger → Unmarshaller → User Struct
- Blue for core library components
- Green for external deps
- Annotations:
- “snake_case convention” next to path keys
- Priority ordering flag>env>file

##### Final advice
- Be very explicit about the sequence of operations.
- Loader interface as the extension point for new sources.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Application
    C1["Client Application"]:::core

    %% Orale Core Components
    subgraph "Orale Core"
        direction TB
        LM["Loader Manager"]:::core
        FL["Flag Loader"]:::core
        EL["Env Loader"]:::core
        FIL["File Loader"]:::core
        MU["Merger & Unmarshaller"]:::core
        US["User Struct"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        TP["TOML Parser"]:::external
    end

    %% Test Artifacts
    subgraph "Test Artifacts"
        direction TB
        TA["Test Assets"]:::test
    end

    %% Flow of Control
    C1 -->|"Load(name)"| LM
    LM -->|"Flag Load"| FL
    LM -->|"Env Load"| EL
    LM -->|"File Load"| FIL
    FL -->|"map[string]string"| MU
    EL -->|"map[string]string"| MU
    FIL -->|"map[string]interface{}"| MU
    MU -->|"Populate Struct\n(flag>env>file)"| US

    %% Extension Point
    LM -->|"implements Loader interface"| FL
    LM -->|"implements Loader interface"| EL
    LM -->|"implements Loader interface"| FIL

    %% External Calls
    FIL -->|"uses"| TP

    %% Test Integration
    TA -.-> FIL
    TA -.-> EL
    TA -.-> FL

    %% Click Events
    click LM "https://github.com/inderpooni/orale/blob/master/loader.go"
    click FL "https://github.com/inderpooni/orale/blob/master/load.go"
    click EL "https://github.com/inderpooni/orale/blob/master/file.go"
    click FIL "https://github.com/inderpooni/orale/blob/master/file.go"
    click MU "https://github.com/inderpooni/orale/blob/master/get.go"
    click TP "https://github.com/inderpooni/orale/blob/master/go.mod"
    click TA "https://github.com/inderpooni/orale/tree/master/test-assets/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef test fill:#f8f9fa,stroke:#6c757d,color:#6c757d,stroke-dasharray:5 5
```
