# ufirstgroup/ymlr architecture

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

- Interactive diagram: https://gitdiagram.com/ufirstgroup/ymlr
- Repository: https://github.com/ufirstgroup/ymlr

## Overview

##### Project type and purpose
- **Type**: Open-source library/tool (Elixir package).
- **Purpose**: Provide a flexible, opinionated YAML encoding API (`Ymlr.document!`, `Ymlr.documents!`, etc.) with optional features (comments, atom support, sorted maps).
- **Key indicators**:
- `mix.exs` dependency file, `lib/ymlr` source folder, absence of “frontend/backend” directories → library.
- README describes API functions and benchmarks.

##### File structure
Top‐level directories and files:
- **lib/ymlr/**
– `encode.ex` (low-level emitter)
– `encoder.ex` (higher-level pipeline)
– `ymlr.ex` (public API module)
- **benchmark/**: stand-alone Elixir script to measure performance.
- **test/** & **test_support/**: unit tests and fixtures.
- **.github/**: CI workflows (code quality, Elixir matrix).
- Config files: `mix.exs`, `.tool-versions`, `.formatter.exs`, `.envrc`, Nix tooling (`flake.nix`).

##### README for additional insights
- Public API functions: `Ymlr.document!`, `Ymlr.documents!` and options (`atoms`, `sort_maps`).
- Benchmark workflow outlined (script under `benchmark/`).
- No external services at runtime; purely library.

##### Main components and their relationships
a. **Public API Layer**
- `Ymlr` module (entry points for users)
b. **Core Encoding Pipeline**
- `Ymlr.Encoder` – orchestrates options, handles multiple documents, invokes low‐level emitter
- `Ymlr.Encode` – transforms individual data structures to YAML strings (handles indentation, comments, value quoting)
c. **Supporting Components**
- **Benchmark Script** (`benchmark/run.exs`) – independent process measuring performance
- **Test Harness** (`test/`, `test_support/`) – confirms correctness via fixtures and helpers
- **CI/CD** (`.github/workflows/...`) – automates quality checks and publishing
d. **External Integrations**
- Hex.pm (package publishing)
- Coveralls, Codecov (coverage reporting)
- GitHub Actions (build/test matrix)

##### Architectural patterns and design principles
- **Layered design**: Public API → orchestration (Encoder) → low-level emitter (Encode)
- **Single responsibility**: Each module focuses on one aspect (API surface, pipeline logic, YAML emission)
- **Configuration via options**: non-intrusive flags (`atoms`, `sort_maps`), passed top-down
- **Testable units**: encode and encoder logic decoupled for targeted tests

##### Detailed component breakdown to capture
[User App]
→ calls → [Ymlr (Public API)]
→ delegates to → [Ymlr.Encoder (Pipeline OR Multi-doc Handler)]
→ invokes → [Ymlr.Encode (Emitter)]
→ produces → [YAML text]
● Option flags flow top‐down from API through Encoder to Encode.
● Benchmark harness calls API directly (side path).
● Test suite invokes Encoder/Encode modules (side path).
● CI/CD triggers test suite, coverage, benchmark.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Application Layer
    subgraph "User Application"
        UserApp["User Application"]
    end

    %% Runtime Modules
    subgraph "Runtime Modules"
        direction TB
        Ymlr["Ymlr\n(Public API)"]:::runtime
        Ymlr_Encoder["Ymlr.Encoder\n(Core Pipeline)"]:::runtime
        Ymlr_Encode["Ymlr.Encode\n(Low-Level Emitter)"]:::runtime
        YAML_Output["YAML Output\n(text)"]:::runtime
    end

    %% Scripts and Tests
    subgraph "Scripts and Tests"
        direction TB
        Benchmark["Benchmark Script"]:::script
        subgraph "Test Suite"
            direction TB
            Ymlr_test["ymlr_test.exs"]:::script
            Encode_test["encode_test.exs"]:::script
            Encoder_test["encoder_test.exs"]:::script
            Test_helper["test_helper.exs"]:::script
        end
        subgraph "Test Support"
            direction TB
            Fixture["iam_policy.yaml"]:::script
            Support_helper["encode_test_helper.ex"]:::script
            Structs["structs.ex"]:::script
        end
    end

    %% CI/CD & External Services
    subgraph "CI/CD & External Services"
        direction TB
        GitHubActions["GitHub Actions"]:::ci
        QualityWorkflow["Code Quality Workflow"]:::ci
        MatrixWorkflow["Elixir Matrix Workflow"]:::ci
        subgraph "Package Configuration"
            direction TB
            MixExs["mix.exs"]:::ci
            MixLock["mix.lock"]:::ci
        end
        HexPM["Hex.pm"]:::ci
        Coverage["Coveralls/Codecov"]:::ci
    end

    %% Relationships
    UserApp -->|"calls"| Ymlr
    Ymlr -->|"delegates to"| Ymlr_Encoder
    Ymlr_Encoder -->|"invokes"| Ymlr_Encode
    Ymlr_Encode -->|"produces"| YAML_Output

    Benchmark -->|"calls"| Ymlr
    Ymlr_test -->|"tests"| Ymlr
    Encode_test -->|"tests"| Ymlr_Encode
    Encoder_test -->|"tests"| Ymlr_Encoder
    Test_helper -->|"setup"| Ymlr
    Support_helper -->|"helper"| Ymlr_Encode
    Fixture -->|"fixture"| Ymlr
    Structs -->|"structs"| Ymlr

    GitHubActions -->|triggers| QualityWorkflow
    GitHubActions -->|triggers| MatrixWorkflow
    QualityWorkflow -->|runs tests & benchmarks| Benchmark
    MatrixWorkflow -->|runs tests| Benchmark
    QualityWorkflow -->|reports| Coverage
    MatrixWorkflow -->|publishes| HexPM
    GitHubActions -.->|reads| MixExs
    GitHubActions -.->|reads| MixLock

    %% Click Events
    click Ymlr "https://github.com/ufirstgroup/ymlr/blob/main/lib/ymlr.ex"
    click Ymlr_Encoder "https://github.com/ufirstgroup/ymlr/blob/main/lib/ymlr/encoder.ex"
    click Ymlr_Encode "https://github.com/ufirstgroup/ymlr/blob/main/lib/ymlr/encode.ex"
    click Benchmark "https://github.com/ufirstgroup/ymlr/blob/main/benchmark/run.exs"
    click Ymlr_test "https://github.com/ufirstgroup/ymlr/blob/main/test/ymlr_test.exs"
    click Encode_test "https://github.com/ufirstgroup/ymlr/blob/main/test/ymlr/encode_test.exs"
    click Encoder_test "https://github.com/ufirstgroup/ymlr/blob/main/test/ymlr/encoder_test.exs"
    click Test_helper "https://github.com/ufirstgroup/ymlr/blob/main/test/test_helper.exs"
    click Fixture "https://github.com/ufirstgroup/ymlr/blob/main/test_support/fixtures/iam_policy.yaml"
    click Support_helper "https://github.com/ufirstgroup/ymlr/blob/main/test_support/encode_test_helper.ex"
    click Structs "https://github.com/ufirstgroup/ymlr/blob/main/test_support/structs.ex"
    click QualityWorkflow "https://github.com/ufirstgroup/ymlr/blob/main/.github/workflows/code_quality.yaml"
    click MatrixWorkflow "https://github.com/ufirstgroup/ymlr/blob/main/.github/workflows/elixir_matrix.yaml"
    click MixExs "https://github.com/ufirstgroup/ymlr/blob/main/mix.exs"
    click MixLock "https://github.com/ufirstgroup/ymlr/blob/main/mix.lock"

    %% Styles
    classDef runtime fill:#blue,stroke:#000,color:#fff;
    classDef script fill:#8fbc8f,stroke:#000,color:#000;
    classDef ci fill:none,stroke:#888,stroke-dasharray: 5 5,color:#000;
```
