# ro80t/envl architecture

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

- Interactive diagram: https://gitdiagram.com/ro80t/envl
- Repository: https://github.com/ro80t/envl

## Overview

##### Project type and purpose
- This is an open-source, multi-language toolchain—a monorepo providing a domain-specific “Environment Language” (envl) with:
– A core Rust library for parsing, representing, and generating code/configurations (packages/envl, envl-config, envl-vars, envl-codeblock, envl-utils)
– A Rust-based CLI (packages/envl-cli)
– A JavaScript/TypeScript package (packages/envl-js)
- Purpose: define, validate, and generate code/config from a typed, structured .envl DSL.

##### File structure
Top-level “packages” directory contains self-contained crates/packages:
- envl             – core generator library
- envl-config      – parser/lexer for .envlconf settings/vars
- envl-vars        – parser for typed variable definitions
- envl-codeblock   – runtime support & codeblock embedding
- envl-utils       – shared helpers (error handling, naming, casing)
- envl-cli         – command-line interface wrapping the core crates
- envl-js          – JS/TS wrapper integrating core functionality in Node
Common patterns:
- Each crate has src/lib.rs (public API), src/parser & src/lexer (for parsing stages), tests, and Cargo.toml
- The core crate (envl) depends on config, vars, codeblock, utils

##### README for additional insights
- It shows syntax examples (.envl and .envlconf files)
- It enumerates the available packages and their roles (Rust lib, CLI, JS)

##### Main components & their relationships
a. Components
1. Input files (.envl, .envlconf)
2. envl-config & envl-vars (lexing → parsing .envlconf DSL)
3. Core AST & validation (shared types in envl)
4. envl-codeblock (runtime embedding, code-block evaluation support)
5. envl-utils (shared helpers)
6. Code generator (packages/envl/src/generator) → emits target code (Rust, potentially others)
7. User-facing layers:
- envl-cli (CLI binary)
- envl-js (JavaScript/TypeScript package)
8. Output: generated code or runtime execution results

b. Relationships & data flow
– CLI or JS layer accepts user input (.envl, .envlconf)
– Delegates to envl-config and envl-vars for parsing → produces an abstract model (AST, Config structs)
– Core envl library uses that model + codeblock runtime to generate code or execute values
– envl-utils supports error formatting, naming conventions at each stage
– Generated artifacts are returned to user (console, file, in-memory JS object)

c. Architectural patterns & principles
- Modular crates: single responsibility (parsing, validation, generation, CLI, JS)
- “Front controller” at CLI/JS layer
- Pipeline style: Lexing → Parsing → AST → Generation/Runtime
- Shared utility library prevents duplication

d. Key technologies
- Rust (core crates, CLI)
- Node.js/TypeScript (envl-js)
- Cargo monorepo with workspaces
- tsup/ESLint/Prettier for JS packaging

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input files
    subgraph "Input Files" 
        direction TB
        EnvFile[".envl"]:::input
        ConfFile[".envlconf"]:::input
    end

    %% Parsing crates
    subgraph "Parsing Crates"
        direction TB
        ENVL_CONFIG["envl-config"]:::parsing
        ENVL_VARS["envl-vars"]:::parsing
    end

    %% Core & Generation & Runtime & Utils
    subgraph "Core & Generation"
        direction TB
        CORE_AST["envl\n(AST & Validation)"]:::core
        GENERATOR["Code Generator"]:::core
        CODEBLOCK["envl-codeblock\n(Runtime Support)"]:::core
    end

    subgraph "Shared Utilities"
        direction TB
        UTILS["envl-utils"]:::utils
    end

    %% Frontends
    subgraph "Frontends"
        direction TB
        CLI["envl-cli"]:::frontend
        JS["envl-js"]:::frontend
    end

    %% Output
    Output["Generated Code / Results"]:::output

    %% Data flow
    EnvFile --> ENVL_CONFIG
    ConfFile --> ENVL_CONFIG
    EnvFile --> ENVL_VARS
    ConfFile --> ENVL_VARS

    ENVL_CONFIG --> CORE_AST
    ENVL_VARS --> CORE_AST

    CORE_AST --> GENERATOR
    CORE_AST --> CODEBLOCK

    GENERATOR --> Output
    CODEBLOCK --> Output

    CLI --> ENVL_CONFIG
    CLI --> ENVL_VARS
    CLI --> CORE_AST
    CLI --> GENERATOR

    JS --> ENVL_CONFIG
    JS --> ENVL_VARS
    JS --> CORE_AST
    JS --> GENERATOR

    %% Utility support
    UTILS -.-> ENVL_CONFIG
    UTILS -.-> ENVL_VARS
    UTILS -.-> CORE_AST
    UTILS -.-> GENERATOR
    UTILS -.-> CODEBLOCK
    UTILS -.-> CLI
    UTILS -.-> JS

    %% Click Events
    click EnvFile "https://github.com/ro80t/envl/blob/main/tests/envl-rs-test/.envl"
    click ConfFile "https://github.com/ro80t/envl/blob/main/tests/envl-rs-test/.envlconf"

    click ENVL_CONFIG "https://github.com/ro80t/envl/blob/main/packages/envl-config/src/lib.rs"
    click ENVL_CONFIG "https://github.com/ro80t/envl/tree/main/packages/envl-config/src/lexer/"
    click ENVL_CONFIG "https://github.com/ro80t/envl/tree/main/packages/envl-config/src/parser/"

    click ENVL_VARS "https://github.com/ro80t/envl/blob/main/packages/envl-vars/src/lib.rs"
    click ENVL_VARS "https://github.com/ro80t/envl/tree/main/packages/envl-vars/src/lexer/"
    click ENVL_VARS "https://github.com/ro80t/envl/tree/main/packages/envl-vars/src/parser/"

    click CORE_AST "https://github.com/ro80t/envl/blob/main/packages/envl/src/lib.rs"
    click CORE_AST "https://github.com/ro80t/envl/tree/main/packages/envl/src/var/"
    click CORE_AST "https://github.com/ro80t/envl/blob/main/packages/envl/src/misc/vars.rs"

    click GENERATOR "https://github.com/ro80t/envl/blob/main/packages/envl/src/generator/mod.rs"
    click GENERATOR "https://github.com/ro80t/envl/tree/main/packages/envl/src/generator/rust/"
    click GENERATOR "https://github.com/ro80t/envl/tree/main/packages/envl/src/generator/rust/types/"
    click GENERATOR "https://github.com/ro80t/envl/tree/main/packages/envl/src/generator/rust/utils/"
    click GENERATOR "https://github.com/ro80t/envl/tree/main/packages/envl/src/generator/rust/var/"

    click CODEBLOCK "https://github.com/ro80t/envl/blob/main/packages/envl-codeblock/src/lib.rs"
    click CODEBLOCK "https://github.com/ro80t/envl/blob/main/packages/envl-codeblock/src/runtime.rs"

    click UTILS "https://github.com/ro80t/envl/blob/main/packages/envl-utils/src/lib.rs"
    click UTILS "https://github.com/ro80t/envl/blob/main/packages/envl-utils/src/error.rs"
    click UTILS "https://github.com/ro80t/envl/blob/main/packages/envl-utils/src/case.rs"
    click UTILS "https://github.com/ro80t/envl/blob/main/packages/envl-utils/src/name.rs"
    click UTILS "https://github.com/ro80t/envl/blob/main/packages/envl-utils/src/types.rs"

    click CLI "https://github.com/ro80t/envl/blob/main/packages/envl-cli/src/cli.rs"

    click JS "https://github.com/ro80t/envl/blob/main/packages/envl-js/src/index.ts"
    click JS "https://github.com/ro80t/envl/blob/main/packages/envl-js/package.json"
    click JS "https://github.com/ro80t/envl/blob/main/packages/envl-js/tsconfig.json"
    click JS "https://github.com/ro80t/envl/blob/main/packages/envl-js/tsup.config.ts"
    click JS "https://github.com/ro80t/envl/blob/main/packages/envl-js/eslint.config.js"
    click JS "https://github.com/ro80t/envl/blob/main/packages/envl-js/prettier.config.js"

    %% Styles
    classDef input fill:#f9f,stroke:#333,stroke-width:1px
    classDef parsing fill:#b2f2bb,stroke:#333,stroke-width:1px
    classDef core fill:#74c0fc,stroke:#333,stroke-width:1px
    classDef utils fill:#adb5bd,stroke:#333,stroke-width:1px
    classDef frontend fill:#ffd43b,stroke:#333,stroke-width:1px
    classDef output fill:#fa5252,stroke:#333,stroke-width:1px
```
