# skinny85/graalvm-truffle-tutorial architecture

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

- Interactive diagram: https://gitdiagram.com/skinny85/graalvm-truffle-tutorial
- Repository: https://github.com/skinny85/graalvm-truffle-tutorial

## Overview

##### Project type and purpose
- This is a compiler/language‐implementation tutorial, not a web or full‐stack app.
- It implements “EasyScript,” a small JavaScript subset, on top of GraalVM’s Truffle framework.
- The README confirms it is a series of Gradle submodules (part-01…part-16), each adding features (parsing, globals, functions, arrays, classes, exceptions, debugger, benchmarking).

##### File structure
- Top‐level is a Gradle multi‐project build (settings.gradle, build.gradle, gradle wrapper, .github/workflows).
- Each part-XX folder is a Gradle submodule with its own build.gradle, src/main/java, src/main/antlr (from part-04 onward), and src/jmh in benchmark modules (part-09+).
- Key patterns:
- ANTLR grammars (EasyScript.g4) drive parser generation.
- Java packages com.endoflineblog.truffle.part_XX contain:
– TruffleLanguage subclass (EasyScriptTruffleLanguage)
– Parser wrapper (EasyScriptTruffleParser)
– LanguageContext (EasyScriptLanguageContext)
– TypeSystem definitions
– AST nodes (root, exprs, stmts, specialized nodes)
– Runtime objects (GlobalScopeObject, FunctionObject, ArrayObject, etc.)
- JMH benchmarks in src/jmh for measuring interpreter performance.
- Test code in src/test for unit tests of parsing, execution, and benchmarks.

##### README for additional insights
- The tutorial’s structure: each part builds on the previous, adding new language features.
- Dependencies: GraalVM SDK (Truffle API), ANTLR, JMH, JUnit.
- Build and run via Gradle wrapper.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & IDE Layer
    subgraph "Build & IDE Layer"
        direction TB
        GradleBuild["Gradle Multi-Project Build"]:::build
        ANTLRGen["ANTLR Grammar Generator"]:::build
    end

    %% Language Implementation Layer
    subgraph "Language Implementation" 
        direction TB
        ESLang["EasyScriptTruffleLanguage"]:::impl
        ESContext["EasyScriptLanguageContext"]:::impl
        ESTypeSys["EasyScriptTypeSystem"]:::impl
        ParserWrapper["EasyScriptTruffleParser"]:::impl
        subgraph "AST"
            direction TB
            StmtBlockRoot["StmtBlockRootNode"]:::impl
            BuiltInRoot["BuiltInFuncRootNode"]:::impl
            ExprStmtNodes["Expression & Statement Nodes"]:::impl
        end
        subgraph "Runtime Objects"
            direction TB
            GlobalObj["GlobalScopeObject"]:::impl
            ArrayObj["ArrayObject"]:::impl
            ObjProto["ObjectPrototype"]:::impl
        end
    end

    %% Runtime Platform Layer
    subgraph "Runtime Platform"
        direction TB
        TruffleInterp["Truffle Interpreter & CallTarget"]:::runtime
        GraalJIT["GraalVM JIT Engine"]:::runtime
    end

    %% Tooling Layer
    subgraph "Tooling"
        direction TB
        JMHRunner["JMH Benchmark Runner"]:::tooling
        JUnitSuite["JUnit Test Suite"]:::tooling
    end

    %% Execution Flow
    ScriptInput["Script Input"]:::impl

    %% Connections
    GradleBuild -->|"builds grammar"| ANTLRGen
    ANTLRGen -->|"generates parser"| ParserWrapper
    ScriptInput -->|"parse()"| ParserWrapper
    ParserWrapper -->|"produces AST"| StmtBlockRoot
    StmtBlockRoot --> ExprStmtNodes
    ExprStmtNodes --> TruffleInterp
    ESContext --> TruffleInterp
    ESLang --> ESContext
    TruffleInterp --> GraalJIT

    JMHRunner -->|"executes AST"| TruffleInterp
    JUnitSuite -->|"tests parser & AST"| ParserWrapper
    JUnitSuite --> TruffleInterp

    %% Click Events
    click GradleBuild "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/settings.gradle"
    click ANTLRGen "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/antlr/com/endoflineblog/truffle/part_16/parsing/antlr/EasyScript.g4"
    click ParserWrapper "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/java/com/endoflineblog/truffle/part_16/parsing/EasyScriptTruffleParser.java"
    click ESLang "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/java/com/endoflineblog/truffle/part_16/EasyScriptTruffleLanguage.java"
    click ESContext "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/java/com/endoflineblog/truffle/part_16/EasyScriptLanguageContext.java"
    click ESTypeSys "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/java/com/endoflineblog/truffle/part_16/EasyScriptTypeSystem.java"
    click StmtBlockRoot "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/java/com/endoflineblog/truffle/part_16/nodes/root/StmtBlockRootNode.java"
    click BuiltInRoot "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/java/com/endoflineblog/truffle/part_16/nodes/root/BuiltInFuncRootNode.java"
    click GlobalObj "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/java/com/endoflineblog/truffle/part_16/runtime/GlobalScopeObject.java"
    click ArrayObj "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/java/com/endoflineblog/truffle/part_16/runtime/ArrayObject.java"
    click ObjProto "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/main/java/com/endoflineblog/truffle/part_16/runtime/ObjectPrototype.java"
    click JMHRunner "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/jmh/java/com/endoflineblog/truffle/part_16/TruffleBenchmark.java"
    click JMHRunner "https://github.com/skinny85/graalvm-truffle-tutorial/blob/master/part-16/src/jmh/java/com/endoflineblog/truffle/part_16/FibonacciBenchmark.java"
    click JUnitSuite "https://github.com/skinny85/graalvm-truffle-tutorial/tree/master/part-16/src/test/java/com/endoflineblog/truffle/part_16"

    %% Styles
    classDef build fill:#D0E6FF,stroke:#4A90E2,color:#000;
    classDef impl fill:#DFFFE0,stroke:#3DBE29,color:#000;
    classDef runtime fill:#FFE6CC,stroke:#F5A623,color:#000;
    classDef tooling fill:#EEEEEE,stroke:#888888,color:#000;
```
