# lambdaclass/cairo_native architecture

> Architecture diagram of the GitHub repository lambdaclass/cairo_native, 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/lambdaclass/cairo_native
- Repository: https://github.com/lambdaclass/cairo_native

## Overview

##### Main Components
- Compiler Core and Pipeline:
- Central compilation process that translates Sierra code into MLIR and then to native machine code. This pipeline is mainly implemented within the src/ directory (e.g., compiler.rs, context.rs, module.rs, runtime.rs, and more).
- Within this pipeline, highlight components such as:
⁃ Frontend: Parsing and intermediate representation management (Sierra input).
⁃ Conversion: The transformation phase that leverages MLIR and LLVM (notice dependencies, environment variables, and the integration of MLIR/LLVM as seen in the README).
⁃ Backend: Code generation and optimizations using LLVM toolchain.
- Execution Engines:
- The project provides two execution methods – Just-in-time (JIT) and Ahead-of-time (AOT) compilation. Components for these are found in src/executor (both aot.rs and jit.rs).
- Caching modules (src/cache directory) that store compiled libraries or AOT caches.
- Command-Line Tools:
- Several binaries (found in src/bin) act as user-facing interfaces: cairo-native-compile, cairo-native-dump, cairo-native-run, cairo-native-test, cairo-native-stress, as well as scarb-native variants.
- How these tools interact with the core library, essentially acting as wrappers to invoke the underlying compiler and execution engines.
- Supporting Libraries and Utilities:
- Under src/libfuncs and src/types, a number of library functions and types are implemented that likely support built-in operations for Cairo programs (from arrays and booleans to cryptographic functions).
- Auxiliary utilities (in src/utils) for memory tracing, safe runner functionality, and debugging.
- Testing & Benchmarks:
- The tests/ and benches/ directories showcase thorough testing including integration and benchmark tests (including stress tests with cairo-native-stress).
- A note that external benchmarking scripts, as well as continuous integration (GitHub workflows), are integrated with the project.
- Documentation and Examples:
- Directories such as docs/, examples/, and programs/ illustrate usage examples, walkthroughs, and test programs that serve as a guideline for end users.

##### Relationships and Interactions
- User Interaction: Command-line tools (frontend wrappers) invoke the compiler library.
- Data Flow:
⁃ Input: Cairo (Sierra) source code provided by users or test cases.
⁃ Processing: The compiler core processes the input, leveraging internal modules for conversion and optimization, and then passes through MLIR/LLVM for code generation.
⁃ Output: Machine code (or shared libraries), as produced by the backend, and test results when running programs.
- How the environment’s configuration (LLVM and MLIR installation, as set by env.sh or environment variables) is a prerequisite that feeds into the pipeline.

##### Architectural Patterns and Notable Design Principles
- Modular design: Clear separation between core libraries (in src), CLI tools (in src/bin), and tests or examples.
- Layered architecture:
1. Frontend CLI layer,
2. Compiler core layer with submodules for IR handling, caching, and execution,
3. Backend integration with external toolchains (MLIR, LLVM).
- Emphasis on extensibility: Directories like libfuncs and types imply a pluggable system for new operations, which can easily be integrated without affecting the core pipeline.
- Use of caching strategies (AOT/JIT modules found in src/cache and in executor subdirectories) to improve performance.

##### Technologies and External Dependencies
- MLIR, LLVM, Clang toolchain are critical for machine code generation.
- Rust is the primary programming language, documented by the Cargo files and rust-toolchain.
- Additional system dependencies from the README (e.g., dependency installation instructions, environment scripts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Command-Line Tools Group
    subgraph "Command-Line Tools"
        CLI_Compile["CLI Compile"]:::cli
        CLI_Dump["CLI Dump"]:::cli
        CLI_Run["CLI Run"]:::cli
        CLI_Test["CLI Test"]:::cli
        CLI_Stress["CLI Stress"]:::cli
        CLI_ScarbDump["Scarb-native Dump"]:::cli
        CLI_ScarbTest["Scarb-native Test"]:::cli
        CLI_Starknet["Starknet-native Compile"]:::cli
    end

    %% Compiler Core & Pipeline Group
    subgraph "Compiler Core & Pipeline"
        CompilerFrontend["Compiler Frontend (Sierra Parsing & IR Generation)"]:::pipeline
        MLIRConversion["MLIR/LLVM Conversion"]:::pipeline
        RuntimeModule["Runtime & Module Handling"]:::pipeline
    end

    %% Execution Engines Group
    subgraph "Execution Engines"
        ExecJIT["Execution Engine (JIT)"]:::executor
        JITCache["Caching Module (JIT)"]:::executor
        ExecAOT["Execution Engine (AOT)"]:::executor
        AOTCache["Caching Module (AOT)"]:::executor
    end

    %% Supporting Libraries & Utilities Group
    subgraph "Supporting Libraries & Utilities"
        LibFuncs["Library Functions & Types"]:::library
        AuxUtils["Auxiliary Utilities"]:::library
    end

    %% External Dependencies & Environment Group
    subgraph "External & Environment"
        Toolchain["MLIR/LLVM Toolchain"]:::external
        EnvConfig["Environment Configuration"]:::external
    end

    %% Testing & Documentation Group
    subgraph "Testing & Documentation"
        Tests["Tests"]:::test
        Benchmarks["Benchmarks"]:::test
        Documentation["Documentation"]:::doc
        Examples["Examples"]:::doc
        UsageProgs["Usage Programs"]:::doc
    end

    %% Flow Connections
    CLI_Compile --> CompilerFrontend
    CompilerFrontend --> MLIRConversion
    MLIRConversion --> RuntimeModule
    MLIRConversion -->|"uses"| Toolchain
    EnvConfig --> MLIRConversion
    RuntimeModule --> ExecJIT
    RuntimeModule --> ExecAOT
    ExecJIT --> JITCache
    ExecAOT --> AOTCache
    LibFuncs --> CompilerFrontend
    AuxUtils --> CompilerFrontend
    Tests -.-> CompilerFrontend
    Benchmarks -.-> ExecJIT
    Benchmarks -.-> ExecAOT
    Documentation -.-> CLI_Compile
    Examples -.-> CLI_Compile
    UsageProgs -.-> CLI_Compile

    %% Click Events for Command-Line Tools
    click CLI_Compile "https://github.com/lambdaclass/cairo_native/blob/main/src/bin/cairo-native-compile.rs"
    click CLI_Dump "https://github.com/lambdaclass/cairo_native/blob/main/src/bin/cairo-native-dump.rs"
    click CLI_Run "https://github.com/lambdaclass/cairo_native/blob/main/src/bin/cairo-native-run.rs"
    click CLI_Test "https://github.com/lambdaclass/cairo_native/blob/main/src/bin/cairo-native-test.rs"
    click CLI_Stress "https://github.com/lambdaclass/cairo_native/blob/main/src/bin/cairo-native-stress/main.rs"
    click CLI_ScarbDump "https://github.com/lambdaclass/cairo_native/blob/main/src/bin/scarb-native-dump.rs"
    click CLI_ScarbTest "https://github.com/lambdaclass/cairo_native/blob/main/src/bin/scarb-native-test.rs"
    click CLI_Starknet "https://github.com/lambdaclass/cairo_native/blob/main/src/bin/starknet-native-compile.rs"

    %% Click Events for Compiler Core & Pipeline
    click CompilerFrontend "https://github.com/lambdaclass/cairo_native/blob/main/src/compiler.rs"
    click MLIRConversion "https://github.com/lambdaclass/cairo_native/blob/main/src/compiler.rs"
    click RuntimeModule "https://github.com/lambdaclass/cairo_native/blob/main/src/module.rs"

    %% Click Events for Execution Engines
    click ExecJIT "https://github.com/lambdaclass/cairo_native/blob/main/src/executor/jit.rs"
    click JITCache "https://github.com/lambdaclass/cairo_native/blob/main/src/cache/jit.rs"
    click ExecAOT "https://github.com/lambdaclass/cairo_native/blob/main/src/executor/aot.rs"
    click AOTCache "https://github.com/lambdaclass/cairo_native/blob/main/src/cache/aot.rs"

    %% Click Events for Supporting Libraries & Utilities
    click LibFuncs "https://github.com/lambdaclass/cairo_native/tree/main/src/libfuncs/"
    click AuxUtils "https://github.com/lambdaclass/cairo_native/tree/main/src/utils/"

    %% Click Events for Testing & Documentation
    click Tests "https://github.com/lambdaclass/cairo_native/tree/main/tests/"
    click Benchmarks "https://github.com/lambdaclass/cairo_native/tree/main/benches/"
    click Documentation "https://github.com/lambdaclass/cairo_native/tree/main/docs/"
    click Examples "https://github.com/lambdaclass/cairo_native/tree/main/examples/"
    click UsageProgs "https://github.com/lambdaclass/cairo_native/tree/main/programs/"

    %% Styles
    classDef cli fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef pipeline fill:#e6f0ff,stroke:#0055cc,stroke-width:2px;
    classDef executor fill:#e6ffe6,stroke:#009900,stroke-width:2px;
    classDef library fill:#ffe6ff,stroke:#cc0099,stroke-width:2px;
    classDef external fill:#fff5cc,stroke:#cc9900,stroke-width:2px;
    classDef test fill:#e6ffff,stroke:#00cccc,stroke-width:2px;
    classDef doc fill:#f0ffe6,stroke:#669900,stroke-width:2px;
```
