# plutolang/pluto architecture

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

- Interactive diagram: https://gitdiagram.com/plutolang/pluto
- Repository: https://github.com/plutolang/pluto

## Overview

##### Project Type and Purpose
- Pluto is a compiler/runtime for a Lua-derived programming language (“dialect of Lua”) that offers new syntax, an enhanced standard library, and bytecode compatibility with Lua 5.4.
- It includes both an interpreter (`pluto`) and a ahead-of-time compiler (`plutoc`), plus build scripts and packaging workflows for multiple targets (native, DLL, WebAssembly, NuGet, Debian, etc.).

##### File-Structure Analysis
- Top-level:
- .github/workflows → CI pipelines (build, test, docker)
- scripts/ → PHP scripts orchestrating compilation, linking, bundling (DLL, static, NuPkg, DEB, WASM)
- src/ → core C++ source code, divided by modules: lexer, parser, VM, standard libraries, utilities
- Makefile + Pluto.sln / *.vcxproj → cross-platform build definitions (Unix Makefile, Windows solution/project)
- operadores.pluto, *.sun files → language specs/macros processed at build time
- testes/ → test suite (functional and benchmark scripts in Pluto/Lua)
- Key patterns:
- Compiler pipeline (lexer → parser → AST → bytecode generator)
- VM runtime (instruction dispatch loop, garbage collector, standard-library bindings)
- Modular standard libs (crypto, JSON, HTTP, canvas, etc.)
- Build-time code generation via “.sun” templates and scripts

##### README Insights
- Emphasizes compatibility with Lua 5.4, extended syntax, and binary bytecode compatibility.
- Points to website/docs for language features and playground.

##### Detailed & Essential Coverage
- Build orchestration (Makefile, scripts, CI)
- Language-feature preprocessing (`.sun` files)
- Parser → AST → Bytecode → VM path
- Standard library modules as pluggable units
- Dual execution modes (interpreter vs. AOT compiler)
- Avoid over-fragmentation; group closely related C++ modules (e.g., all `l*lib.cpp` files) into a “Standard Library” block, while still calling out major categories (crypto, JSON, IO, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Compilation Pipeline
    Source["Source (.pluto/.lua)"]:::compilation
    Lexer["Lexer"]:::compilation
    Parser["Parser"]:::compilation
    AST["AST / IR"]:::compilation
    Macro["Macro Preprocessor / Template Engine"]:::compilation
    Bytecode["Bytecode Generator"]:::compilation

    subgraph "Compilation Stages"
        direction TB
        Source --> Lexer
        Lexer --> Parser
        Parser --> AST
        AST --> Macro
        Macro --> Bytecode
    end

    %% Runtime / VM
    Interpreter["pluto Interpreter"]:::runtime
    AOT["plutoc AOT Compiler"]:::runtime
    VM["pluto VM"]:::runtime
    GC["Garbage Collector & Memory Management"]:::runtime
    StdLib["Standard Library Modules"]:::runtime

    subgraph "Runtime / VM"
        direction TB
        Bytecode --> Interpreter
        Bytecode --> AOT
        Interpreter --> VM
        AOT --> VM
        VM --> GC
        VM --> StdLib
    end

    %% Build & Packaging
    BuildDefs["Core Build Definitions"]:::build
    PkgScripts["Packaging Scripts"]:::packaging

    subgraph "Build & Packaging"
        direction TB
        BuildDefs --> PkgScripts
    end

    %% CI/CD
    CI["GitHub Actions CI/CD"]:::ci

    subgraph "CI/CD Pipeline"
        direction TB
        CI --> BuildDefs
        CI --> Test
        CI --> PkgScripts
    end

    %% Test Suite
    Test["Test Suite"]:::test

    subgraph "Testing"
        direction TB
        Test --> Interpreter
    end

    %% Click Events
    click Lexer "https://github.com/plutolang/pluto/blob/main/src/llex.cpp"
    click Parser "https://github.com/plutolang/pluto/blob/main/src/lparser.cpp"
    click AST "https://github.com/plutolang/pluto/blob/main/src/lcode.cpp"
    click Macro "https://github.com/plutolang/pluto/blob/main/src/pluto.sun"
    click Bytecode "https://github.com/plutolang/pluto/blob/main/src/ldump.cpp"
    click Interpreter "https://github.com/plutolang/pluto/blob/main/src/lua.cpp"
    click AOT "https://github.com/plutolang/pluto/blob/main/src/luac.cpp"
    click VM "https://github.com/plutolang/pluto/blob/main/src/lvm.cpp"
    click GC "https://github.com/plutolang/pluto/blob/main/src/lgc.cpp"
    click StdLib "https://github.com/plutolang/pluto/blob/main/src/lbaselib.cpp"
    click BuildDefs "https://github.com/plutolang/pluto/tree/main/Makefile"
    click PkgScripts "https://github.com/plutolang/pluto/blob/main/scripts/compile.php"
    click CI "https://github.com/plutolang/pluto/blob/main/.github/workflows/all.yml"
    click Test "https://github.com/plutolang/pluto/blob/main/testes/_driver.pluto"

    %% Styles
    classDef compilation fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef runtime fill:#90EE90,stroke:#333,stroke-width:1px
    classDef build fill:#FFD580,stroke:#333,stroke-width:1px
    classDef packaging fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef ci fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef test fill:#D8BFD8,stroke:#333,stroke-width:1px
```
