# vberlier/rukt architecture

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

- Interactive diagram: https://gitdiagram.com/vberlier/rukt
- Repository: https://github.com/vberlier/rukt

## Overview

##### Project Type and Purpose
- Project Type: A Rust library crate that implements a domain-specific language (DSL) for token-based scripting using compile-time macros.
- Purpose: To allow users to store and manipulate token trees at compile time, emulating compile-time scripting in Rust. It’s designed to mirror well-established Rust idioms within a macro-based system.

##### File Structure
- Top-level Directories/Files:
- .github – Contains CI/CD configurations (workflows for testing and releasing).
- Cargo.toml and Cargo.lock – Describe the crate metadata and dependencies.
- LICENSE files – Define the open-source licensing (MIT/Apache-2.0).
- README.md and CHANGELOG.md – Provide documentation and release history.
- Source Code Directory (src):
- lib.rs – Serves as the primary entry point exposing the public API.
- eval.rs – Contains the core evaluation logic that interprets or transforms token trees.
- builtins.rs – Defines built-in token operations (like add, sub, etc.) available in the DSL.
- utils.rs – Provides utility functions to support the evaluation and builtin functionalities.
- Tests Directory:
- Contains integration tests (e.g., tests/rukt.rs) to validate the DSL behaviors.

##### README for Additional Insights
- The README illustrates usage examples of the rukt macros, emphasizing the compile-time expansion and token manipulation.
- It highlights that the crate is implemented entirely using declarative macros (macro_rules), ensuring simplicity and stability.
- Documentation links indicate separate internal components such as statements, expressions, and builtins, suggesting modular handling within the evaluation flow.

##### Components and Relationships
a. Main Components:
- Macro Interface: The public facing macros (rukt!) that user code invokes.
- Library API (src/lib.rs): The layer that abstracts and exposes the DSL functionalities.
- Evaluation Module (src/eval.rs): Processes and manipulates token trees at compile time.
- Builtins Module (src/builtins.rs): Houses the built-in operations (e.g., arithmetic operators) that can be applied within the DSL.
- Utilities (src/utils.rs): Contains helper functions supporting the evaluation and builtins.
- Testing Framework: The test module that automates tests, ensuring compilation and correct macro behavior.
- CI/CD Configuration: GitHub workflows managing build, test, and release pipelines.

b. Relationships and Interactions:
- The user writes code using the rukt macro, which directly interfaces with the Macro Interface.
- The Macro Interface calls into the Library API (lib.rs), which orchestrates the evaluation process.
- The Evaluation Module (eval.rs) is responsible for parsing token trees, conducting control flow/expressions, and integrating built-in operations.
- The Builtins Module (builtins.rs) is invoked by the Evaluation Module to process specific token operations.
- The Utility functions (utils.rs) are used by both the Evaluation and Builtins modules to perform common tasks.
- The CI/CD workflows ensure the entire codebase is continuously tested and released according to changes in the code.

c. Architectural Patterns or Design Principles:
- Modularity: Each core function (evaluation, builtins, utility) is separated into its dedicated module.
- Lightweight: No external dependencies and reliance solely on compile-time techniques using macro_rules.
- Declarative Programming: Emphasizes using Rust’s macro system for compile-time logic.

d. Relevant Technologies and Frameworks:
- Rust and Cargo – for building, testing, and publishing the crate.
- GitHub Actions – for automated testing and deployment.
- Declarative macros (macro_rules) – for DSL implementation.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External
    UC("User Code"):::external

    %% Compile-time Components
    subgraph "Compile-time Components"
        LIB("Macro Interface & Library API (src/lib.rs)"):::compile
        EVAL("Evaluation Module (src/eval.rs)"):::compile
        BUILT("Builtins Module (src/builtins.rs)"):::compile
        UTILS("Utilities (src/utils.rs)"):::compile
    end

    %% Support Systems
    subgraph "Support Systems"
        TEST("Testing Framework (tests/rukt.rs)"):::support
        CICD("CI/CD Configuration (.github/workflows)"):::support
    end

    %% Data Flow Connections
    UC -->|"invokes_macro"| LIB
    LIB -->|"orchestrates_evaluation"| EVAL
    LIB -->|"calls_builtins"| BUILT
    EVAL -->|"invokes_builtins"| BUILT
    EVAL -->|"uses_utilities"| UTILS
    BUILT -->|"uses_utilities"| UTILS
    TEST -->|"validates"| LIB
    CICD -->|"triggers_tests"| TEST

    %% Click Events
    click LIB "https://github.com/vberlier/rukt/blob/main/src/lib.rs"
    click EVAL "https://github.com/vberlier/rukt/blob/main/src/eval.rs"
    click BUILT "https://github.com/vberlier/rukt/blob/main/src/builtins.rs"
    click UTILS "https://github.com/vberlier/rukt/blob/main/src/utils.rs"
    click TEST "https://github.com/vberlier/rukt/blob/main/tests/rukt.rs"
    click CICD "https://github.com/vberlier/rukt/tree/main/.github/workflows"

    %% Styles
    classDef compile fill:#DAE8FC,stroke:#6C8EBF,stroke-width:2px;
    classDef support fill:#E1D5E7,stroke:#9673A6,stroke-width:2px;
    classDef external fill:#F8CECC,stroke:#B85450,stroke-width:2px;
```
