# natalie-lang/natalie architecture

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

- Interactive diagram: https://gitdiagram.com/natalie-lang/natalie
- Repository: https://github.com/natalie-lang/natalie

## Overview

##### Main components
- Compiler Frontend: This part parses Ruby source code (the “src/” and parts of “lib/natalie/compiler”) and produces an intermediate representation. It manages elements like parsing, macro expansion, and method dispatch.
- C++ Code Generator / Backend: Once the IR is formed, the system translates Ruby code into C++ code (as seen in many “src/*.cpp” files). This backend then uses a system compiler (gcc/clang) to produce executables.
- Runtime & Core Libraries: The runtime is composed of many C++ implementations of Ruby objects and core libraries (found in “src/,” “include/,” and parts of “lib/”). This includes implementations for arrays, strings, classes, modules, threads, and more.
- Build and Test Infrastructure: There is a comprehensive test suite (in “spec/” and “test/”) and CI configurations (GitHub Actions, Dockerfile, etc.) that help ensure conformance and stability. The “Makefile” and “Rakefile” are used for building the project.
- REPL Interface: The “bin/natalie” binary, which enters an interactive Read-Eval-Print Loop, is an integral part of the user interface. It handles incremental compilation and immediate execution.
- Extensions & External Integrations: The “ext/” directory contains additional components (like onigmo, prism, tm, zlib) which hint at native extensions for extra functionality in the language.

##### Relationships and interactions
– User Input/Script: Ruby source code is input either via the REPL or via a Ruby script.
– Compiler Frontend: The input goes into the frontend (parsing, lexing – see “src/parser.cpp” and related modules) that produces an internal abstract representation of the code.
– Compiler Pipeline: This IR is then processed in multiple compilation passes (for example, the “pass1” to “pass4” in “lib/natalie/compiler/”) and transformed into either bytecode (the “bytecode” directories/tests) or directly to C++ code.
– Code Generation and Linking: The generated C++ code is compiled by the system C++ compiler (clang/gcc) to produce an executable.
– Runtime System: At runtime, the process uses the core libraries (the “src/”, “include/” directories) to handle Ruby’s object system, garbage collection, method dispatch, thread handling, etc.
– Test and CI: The tests (under “spec/” and “test/”) verify that implemented language features conform to MRI expectations. The CI workflow files ensure that every commit/build is exercised against these tests.

##### Architectural patterns/design principles
– Modular Design: Files are organized by functionality (compilation, runtime, core objects, extensions) which simplifies expansion and maintenance.
– Separation of Concerns: The components for user interface (REPL), language compilation, runtime, and testing are kept largely distinct.
– Layered Architecture: At the top is the user-facing REPL/CLI interface; below it sits the compiler/front-end, then the code generation/back-end; and finally, the runtime core libraries and native integrations.
– Extensibility Points: The “ext/” directory and modular layout of the compiler pipeline suggest that adding additional language features or backends is supported.

- User Interaction Layer: REPL, CLI, script invocation.
- Compilation Layer: Frontend, IR, compilation passes, code generation.
- Runtime Layer: Core object system, memory management, thread and process management.
- Auxiliary Layer: Test framework, Continuous Integration, and build scripts.
– For each component, list key files or directories as annotations (e.g., “bin/natalie” for REPL, “src/” for runtime implementation, “lib/natalie/compiler/” for compilation passes).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction Layer"
        A["Ruby Source Code (REPL/Script)"]:::input
        B["bin/natalie (REPL Interface)"]:::interface
        A -->|"provides"| B
    end

    %% Compilation Layer
    subgraph "Compilation Layer"
        C["Compiler Frontend (lib/natalie/compiler/)"]:::compiler
        D["Intermediate Representation & Compiler Passes"]:::ir
        E["C++ Code Generator / Backend (lib/natalie/compiler/backends/cpp_backend/ & src/*.cpp)"]:::backend
        B -->|"triggers"| C
        C -->|"parses & produces"| D
        D -->|"translates to C++"| E
        E -->|"invokes"| SC["System Compiler (gcc/clang)"]:::external
    end

    %% Runtime Layer
    subgraph "Runtime Layer"
        F["Runtime & Core Libraries (src/, include/)"]:::runtime
        SC -->|"generates executable"| F
        B -->|"interactive execution"| F
    end

    %% Auxiliary Layer
    subgraph "Auxiliary Layer"
        G["Build Tools & CI (Makefile, Rakefile, Dockerfile, .github/workflows/)"]:::build
        H["Test Suite (spec/, test/)"]:::test
        %% Build infrastructure drives the build process
        G -->|"orchestrates"| C
        G -->|"orchestrates"| E
        %% Test suite validates the runtime executable
        H -->|"validates"| F
    end

    %% Extensions & External Integrations
    I["Extensions & Native Integrations (ext/)"]:::extensions
    D -->|"integrates with"| I

    %% Click Events
    click C "https://github.com/natalie-lang/natalie/tree/master/lib/natalie/compiler/"
    click E "https://github.com/natalie-lang/natalie/tree/master/lib/natalie/compiler/backends/cpp_backend/"
    click F "https://github.com/natalie-lang/natalie/tree/master/src/"
    click G "https://github.com/natalie-lang/natalie/tree/master/Makefile"
    click H "https://github.com/natalie-lang/natalie/tree/master/spec/"
    click B "https://github.com/natalie-lang/natalie/tree/master/bin/natalie"
    click I "https://github.com/natalie-lang/natalie/tree/master/ext/"

    %% Styles
    classDef input fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef interface fill:#FAD4A5,stroke:#333,stroke-width:2px;
    classDef compiler fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef ir fill:#D7BDE2,stroke:#333,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#333,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef runtime fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef build fill:#F5CBA7,stroke:#333,stroke-width:2px;
    classDef test fill:#E8DAEF,stroke:#333,stroke-width:2px;
    classDef extensions fill:#D1F2EB,stroke:#333,stroke-width:2px;
```
