# deb4sh/yart architecture

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

- Interactive diagram: https://gitdiagram.com/deb4sh/yart
- Repository: https://github.com/deb4sh/yart

## Overview

##### Project type and purpose
- YART is an open-source, schema-based command-line templating tool (Java CLI application) that:
- Validates a YAML config against a JSON schema
- Renders Jinja2 templates (via Jinjava) into files and directories
- Supports one-level dynamic folder generation
- Offers an extension mechanism (ExtensionProvider subclasses loaded via reflection)

##### Key components from file structure & README
- Entry point & CLI parsing:
- `de.b4sh.yart.Runtime` uses **picocli** for parsing `--templatedirectory`, `--schemadirectory`, `--configfile`, `--outputdirectory`
- Schema handling:
- **snakeyaml** loads YAML config
- **justify** (JSON-schema) validates against the entry schema and any subschemas
- Template processing:
- `de.b4sh.yart.Templater` wraps **Jinjava**
- Data model (validated config) + loaded extensions → template rendering
- Extension mechanism:
- `ExtensionLoader` uses **reflections** to find all subclasses of `ExtensionProvider` under `de.b4sh.yart.extensions`
- Each provider exposes a namespace, function name, and implementation for use in templates
- File I/O & directory logic:
- `FileHelper` reads/writes files & directories
- Dynamic folder generation: directories prefixed with `$` in the template tree are replicated per array element in config
- Packaging & deployment:
- Built with Maven (`pom.xml`), produces “jar-with-dependencies”
- Dockerfile under `src/docker/` for containerized distribution
- GitHub Actions workflow for build & publish

##### Main components & interactions (
- User / CI pipeline → CLI Invocation (picocli)
↓
- Runtime Orchestrator
- Parses CLI args
- Delegates to modules in sequence:
1. **Schema Validator** (snakeyaml → justify)
2. **Extension Loader** (reflections → load ExtensionProviders)
3. **Template Scanner** (FileHelper scans template directory, detects dynamic dirs)
4. **Templater Engine** (Jinjava + extensions + validated data)
5. **Output Writer** (FileHelper writes files/folders to output directory)
↓
- File System (template directory, schema directory, config file) → Output Directory

##### Architectural patterns & design principles
- Modular pipeline: clear separation of concerns (validation, templating, I/O, extensibility)
- Reflection-based plugin architecture for extensions
- Single responsibility classes (`Runtime`, `Templater`, `ExtensionLoader`, `FileHelper`)
- Immutable data flow: load → validate → render → write

##### Technologies & external libraries
- CLI: picocli
- YAML parsing: snakeyaml
- JSON-schema validation: justify
- Templating: Jinjava
- Extension discovery: reflections
- Build: Maven (jar-with-dependencies), Docker

##### Essential elements
- Clear labels for: CLI Parser, Runtime, Schema Validator, Extension Loader, Templater, FileHelper
- CLI args → Runtime
- Runtime → Schema Validator → validated data
- Runtime → Extension Loader → list of functions → Jinjava
- Runtime → FileHelper (scan templates) → template tree + dynamic markers
- Templater + data + extensions → rendered file content → FileHelper (write)
- Blue: core modules
- Green: external libraries
- Gray: filesystem components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    UserCI(["User / CI Pipeline"]):::external
    UserCI -->|“CLI args”| CLI

    %% Core Modules
    subgraph "Runtime Orchestrator"
        direction TB
        CLI["CLI Parser & Runtime"]:::core
        SV["Schema Validator"]:::core
        EL["Extension Loader"]:::core
        TS["Template Scanner"]:::core
        TE["Templater Engine"]:::core
        OW["Output Writer"]:::core
    end

    CLI --> SV
    SV --> EL
    EL --> TS
    TS --> TE
    TE --> OW

    %% Filesystem Components
    SchemaDir(["Schema Directory"]):::fs
    TemplateDir(["Template Directory"]):::fs
    ConfigFile(["Config File"]):::fs
    OutputDir(["Output Directory"]):::fs

    SV -->|“schema + config”| SV
    SV -->|“config.yaml”| ConfigFile
    SV -->|“schemas”| SchemaDir
    TS -->|“templates”| TemplateDir
    OW -->|“rendered files”| OutputDir

    %% External Libraries
    Picocli(["picocli"]):::lib
    SnakeYAML(["snakeyaml"]):::lib
    Justify(["justify"]):::lib
    Reflections(["reflections"]):::lib
    Jinjava(["Jinjava"]):::lib

    Picocli --> CLI
    SnakeYAML --> SV
    Justify --> SV
    Reflections --> EL
    Jinjava --> TE

    %% Deployment
    subgraph Deployment
        direction TB
        BuildConfig["Build Config (Maven)"]:::deployment
        Jar["JAR with Dependencies"]:::deployment
        Docker["Docker Image"]:::deployment
        CIWorkflow["GitHub Actions Workflow"]:::deployment
    end

    OW --> BuildConfig
    BuildConfig --> Jar
    Jar --> Docker
    CIWorkflow --> Jar

    %% Click Events
    click CLI "https://github.com/deb4sh/yart/blob/main/src/main/java/de/b4sh/yart/Runtime.java"
    click SV "https://github.com/deb4sh/yart/blob/main/src/main/java/de/b4sh/yart/Runtime.java"
    click EL "https://github.com/deb4sh/yart/blob/main/src/main/java/de/b4sh/yart/ExtensionLoader.java"
    click ExtensionProvider "https://github.com/deb4sh/yart/blob/main/src/main/java/de/b4sh/yart/extensions/ExtensionProvider.java"
    click HelloWorld "https://github.com/deb4sh/yart/blob/main/src/main/java/de/b4sh/yart/extensions/example/HelloWorld.java"
    click ArrayContentStringify "https://github.com/deb4sh/yart/blob/main/src/main/java/de/b4sh/yart/extensions/terraform/ArrayContentStringify.java"
    click DictionaryObjectParser "https://github.com/deb4sh/yart/blob/main/src/main/java/de/b4sh/yart/extensions/terraform/DictionaryObjectParser.java"
    click TE "https://github.com/deb4sh/yart/blob/main/src/main/java/de/b4sh/yart/Templater.java"
    click TS "https://github.com/deb4sh/yart/blob/main/src/main/java/de/b4sh/yart/FileHelper.java"
    click BuildConfig "https://github.com/deb4sh/yart/blob/main/pom.xml"
    click Docker "https://github.com/deb4sh/yart/tree/main/src/docker/Dockerfile"
    click CIWorkflow "https://github.com/deb4sh/yart/blob/main/.github/workflows/build-and-publish.yml"

    %% Styles
    classDef core fill:#D6E9FE,stroke:#31708F,color:#31708F;
    classDef lib fill:#D5F5E3,stroke:#27AE60,color:#216D25,stroke-dasharray: 5 5;
    classDef fs fill:#F2F3F4,stroke:#AAAAAA,color:#555555,stroke-dasharray: 2 2;
    classDef deployment fill:#FEF5E7,stroke:#F39C12,color:#8A6D3B;
    classDef external fill:#FCF8E3,stroke:#8A6D3B,color:#8A6D3B,stroke-dasharray: 5 5;
```
