# neozenith/injinja architecture

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

- Interactive diagram: https://gitdiagram.com/neozenith/injinja
- Repository: https://github.com/neozenith/injinja

## Overview

##### Project Type & Purpose
- Type: A Python-based CLI tool / library for “injectable” Jinja2 configuration templating.
- Purpose:
– Gather dynamic inputs (env flags, files)
– Load & template many small config files (YAML/JSON/TOML)
– Deep-merge them into one dict
– Render a target Jinja template with that merged config
– Optionally validate or output intermediate merged config

##### Top-Level Components
A. CLI Front-End (src/injinja/__main__.py)
B. Argument Parser & Dispatcher
C. Dynamic Config Collector
- Reads --env flags, optional .env files, prefix filtering
- Produces an in-memory dict
D. Static Config Collector
- Reads one or more config globs or explicit file paths
- Parses JSON/YAML/TOML, honors override ordering
- Produces a list of rendered dicts (each config file is itself a Jinja template)
E. Merger
- Uses deepmerge.always_merger to recursively combine dicts
- Result: merged_config (dict)
F. Template Renderer
- Loads the Jinja template file
- Renders it using merged_config
- Produces final_output (string or file)
G. Output & Validation
- Writes to stdout or output file
- If ‑-output config-json/yaml: serializes merged_config
- If ‑-validate: difflib diff against expectation file

##### External Dependencies & Data Stores
- File System (config files, templates, validation files)
- Environment Variables
- Jinja2 library
- deepmerge library
- Parsers: PyYAML, json, toml

##### Relationships & Interactions
- CLI Front-End calls Argument Parser
- Arg Parser fans out to Dynamic & Static Config Collectors in parallel
- Both collectors feed into the Merger
- Merger feeds the Template Renderer
- Renderer outputs final text, which then goes to Output subsystem
- If validation is requested, branch to the Validation module to produce a diff

##### Important Patterns & Principles
- Pipeline pattern: small independent stages chained by data flow
- Convention-over-configuration: config files treated uniformly as Jinja templates
- Deep immutable merge: ordering of flags determines override semantics

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI["CLI Front-End"]:::cli
        ArgParser["Argument Parser & Dispatcher"]:::cli
    end
    CLI --> ArgParser

    subgraph "Config Collection"
        ENV["Environment Variables"]:::data
        FS1["Sample Config File Store"]:::data
        Parsers["Parsers (YAML/JSON/TOML)"]:::data
        DynamicCollector["Dynamic Config Collector"]:::process
        StaticCollector["Static Config Collector"]:::process
    end

    ArgParser --> DynamicCollector
    ArgParser --> StaticCollector
    ENV --> DynamicCollector
    FS1 --> StaticCollector
    Parsers --> StaticCollector

    subgraph "Merging & Rendering"
        deepmergeLib["deepmerge library"]:::data
        Merger["Merger"]:::process
        JinjaLib["Jinja2 library"]:::data
        Renderer["Template Renderer"]:::process
    end

    DynamicCollector --> Merger
    StaticCollector --> Merger
    deepmergeLib --> Merger
    Merger --> Renderer
    JinjaLib --> Renderer

    subgraph "Output & Validation"
        Output["Output & Validation"]:::output
    end
    Renderer --> Output

    subgraph "Sample Artifacts & Tests"
        FS2["Sample Template Store"]:::data
        FS3["Sample Validation Expectations"]:::data
        CustomFunc["Custom Functions for Templates"]:::data
        TestConfs["Unit Tests for Config Collection & Merging"]:::data
        TestMain["Unit Tests for CLI & End-to-End Behavior"]:::data
    end

    FS2 --> StaticCollector
    CustomFunc --> StaticCollector
    FS3 --> Output
    TestConfs -.-> StaticCollector
    TestMain -.-> CLI

    click CLI "https://github.com/neozenith/injinja/blob/main/src/injinja/__main__.py"
    click ArgParser "https://github.com/neozenith/injinja/blob/main/src/injinja/injinja.py"
    click DynamicCollector "https://github.com/neozenith/injinja/blob/main/src/injinja/injinja.py"
    click StaticCollector "https://github.com/neozenith/injinja/blob/main/src/injinja/injinja.py"
    click Merger "https://github.com/neozenith/injinja/blob/main/src/injinja/injinja.py"
    click Renderer "https://github.com/neozenith/injinja/blob/main/src/injinja/injinja.py"
    click Output "https://github.com/neozenith/injinja/blob/main/src/injinja/injinja.py"
    click FS1 "https://github.com/neozenith/injinja/tree/main/samples/sample-1/config/"
    click FS2 "https://github.com/neozenith/injinja/tree/main/samples/sample-1/templates/"
    click FS3 "https://github.com/neozenith/injinja/tree/main/samples/sample-1/expectations/"
    click CustomFunc "https://github.com/neozenith/injinja/blob/main/samples/sample-1/functions/config_custom_functions.py"
    click TestConfs "https://github.com/neozenith/injinja/blob/main/tests/test_confs.py"
    click TestMain "https://github.com/neozenith/injinja/blob/main/tests/test_main.py"

    classDef cli fill:#b2f5ea,stroke:#006,stroke-width:1px
    classDef process fill:#bee3f8,stroke:#036,stroke-width:1px
    classDef data fill:#e2e8f0,stroke:#555,stroke-width:1px
    classDef output fill:#fed7d7,stroke:#c00,stroke-width:1px
```
