# tinted-theming/ribboncurls architecture

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

- Interactive diagram: https://gitdiagram.com/tinted-theming/ribboncurls
- Repository: https://github.com/tinted-theming/ribboncurls

## Overview

##### Main Components
- **ribboncurls (Library crate)**
- Modules:
– token.rs (lexical tokens)
– syntax_tree.rs & syntax_tree/* (AST and tree utilities)
– utils.rs (helper routines)
– lib.rs (public API surface, orchestrates parsing+rendering)
- Build script (build.rs)
- Tests (ribboncurls/tests/* using spec files)
- **ribboncurls-cli (Binary crate)**
- cli.rs (argument parsing via Clap or similar)
- operations/render.rs (invokes library renderer)
- main.rs (entry point ties CLI → operations → library)
- Tests/fixtures (sample templates + data)
- **External Dependencies** (from Cargo.toml)
- Mustache spec conformance data
- CLI-helper crates (e.g., Clap)
- Serde or YAML parser for test fixtures
- **CI/CD & Packaging**
- GitHub workflows (.github/workflows/*.yml) for lint, test, release
- scripts/package_build for custom packaging
- **Documentation & Metadata**
- README.md files for each crate
- LICENSE, THIRD_PARTY_LICENSES
- CONTRIBUTING.md, CODEOWNERS, .gitignore

##### Relationships & Data Flow
- User invokes **Ribboncurls CLI** →
CLI parses flags/files →
calls **operations/render** →
which calls **ribboncurls::render(template, data)** →
library tokenizes & parses into AST →
library traverses AST to produce final output →
returns string to CLI →
CLI writes to stdout or file.
- Tests exercise both crates independently against Mustache spec fixtures.
- CI workflows trigger on commits/PRs to:
- Run tests for both crates
- Lint code
- Publish crates to crates.io

##### Architectural Patterns & Design Principles
- **Modular Crate Architecture**: separation of core logic (library) from user‐facing binary (CLI).
- **Layered Pipeline**:
1. Lexing → 2. Parsing → 3. AST Transformation → 4. Rendering.
- **Single Responsibility**: each module handles one stage of Mustache processing.
- **Test‐Driven Design**: Mustache spec compliance via spec fixtures.

9. Test fixtures connected to both library and CLI test suites.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Ribboncurls Workspace"
        direction TB
        subgraph "Library Crate (ribboncurls)" 
            direction TB
            lib["lib.rs"]:::libmodule
            token["token.rs"]:::libmodule
            parser["syntax_tree.rs"]:::libmodule
            astutils["syntax_tree/utils.rs"]:::libmodule
            helper["utils.rs"]:::libmodule
            build["build.rs"]:::libmodule
            subgraph "Library Tests"
                tests["tests/"]:::tests
            end
        end
        subgraph "CLI Crate (ribboncurls-cli)"
            direction TB
            cli["cli.rs"]:::clicomponent
            main["main.rs"]:::clicomponent
            subgraph "Operations"
                modops["mod.rs"]:::clicomponent
                render["render.rs"]:::clicomponent
            end
            subgraph "CLI Tests"
                clitest["operation_render.rs"]:::tests
                fixtures["fixtures/"]:::tests
            end
        end
        subgraph "External Dependencies"
            direction TB
            clap["Clap"]:::external
            serde["Serde/YAML"]:::external
            mustache["Mustache Spec"]:::external
        end
        subgraph "CI/CD & Packaging"
            direction TB
            workflows[".github/workflows/"]:::ci
            pkgscript["scripts/package_build"]:::ci
        end
        subgraph "Metadata & Manifests"
            direction TB
            rootmanifest["Cargo.toml"]:::metadata
            libmanifest["ribboncurls/Cargo.toml"]:::metadata
            climanifest["ribboncurls-cli/Cargo.toml"]:::metadata
            readmes["README.md, LICENSE, THIRD_PARTY_LICENSES.md, CONTRIBUTING.md, .gitignore, CODEOWNERS"]:::metadata
            crateREADMEs["ribboncurls/README.md, ribboncurls-cli/README.md"]:::metadata
        end
    end

    %% Data Flow & Dependencies
    main -->|invokes| cli
    cli -->|calls| render
    render -->|uses| lib
    lib -->|lexes| token
    token -->|parses| parser
    parser -->|transforms| astutils
    astutils -->|renders| lib
    clitest -->|tests| render
    fixtures -->|provides fixtures to| clitest
    fixtures -->|provides fixtures to| tests

    %% External deps arrows
    clap -->|used by| cli
    serde -->|used by| tests
    mustache -->|spec compliance in| tests

    %% CI/CD arrows
    workflows -->|run tests for| lib
    workflows -->|run tests for| cli
    workflows -->|lint & publish| lib
    workflows -->|lint & publish| cli
    pkgscript -->|packages workspace| workflows

    %% Metadata deps
    rootmanifest -->|defines workspace| lib
    rootmanifest -->|defines workspace| cli

    %% Click Events
    click lib "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls/src/lib.rs"
    click token "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls/src/token.rs"
    click parser "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls/src/syntax_tree.rs"
    click astutils "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls/src/syntax_tree/utils.rs"
    click helper "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls/src/utils.rs"
    click build "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls/build.rs"
    click tests "https://github.com/tinted-theming/ribboncurls/tree/main/ribboncurls/tests/"
    click cli "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls-cli/src/cli.rs"
    click main "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls-cli/src/main.rs"
    click modops "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls-cli/src/operations/mod.rs"
    click render "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls-cli/src/operations/render.rs"
    click clitest "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls-cli/tests/operation_render.rs"
    click fixtures "https://github.com/tinted-theming/ribboncurls/tree/main/ribboncurls-cli/tests/fixtures/"
    click workflows "https://github.com/tinted-theming/ribboncurls/tree/main/.github/workflows/"
    click pkgscript "https://github.com/tinted-theming/ribboncurls/tree/main/scripts/package_build"
    click rootmanifest "https://github.com/tinted-theming/ribboncurls/blob/main/Cargo.toml"
    click libmanifest "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls/Cargo.toml"
    click climanifest "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls-cli/Cargo.toml"
    click readmes "https://github.com/tinted-theming/ribboncurls/blob/main/README.md"
    click crateREADMEs "https://github.com/tinted-theming/ribboncurls/blob/main/ribboncurls/README.md"

    %% Styles
    classDef libmodule fill:#D6EFFF,stroke:#000,stroke-width:1px
    classDef clicomponent fill:#E0FFE0,stroke:#000,stroke-width:1px
    classDef tests fill:#FDEBD0,stroke-dasharray: 5 5,stroke:#000
    classDef external fill:#FFE0E0,stroke:#000,stroke-width:1px
    classDef ci fill:#F0F0F0,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef metadata fill:#EEEEEE,stroke:#000,stroke-width:1px
```
