# r-near/nearc architecture

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

- Interactive diagram: https://gitdiagram.com/r-near/nearc
- Repository: https://github.com/r-near/nearc

## Overview

##### Main Components Identification
- Compiler CLI Interface – represented by the cli.py module. This is the primary entrypoint for users running NEARC from the command line.
- Code Analyzer – modules such as analyzer.py and utils.py manage the detection of exported functions (via decorators like @near.export), dependency detection, and the analysis of Python code.
- Manifest and Metadata Management – the manifest.py, metadata.py, and exports.py files handle the generation of a MicroPython manifest (containing module and dependency details) and inject NEP-330 compliant metadata.
- Code Builder and WebAssembly Compiler – the builder.py module (which leverages a customized version of MicroPython located in src/nearc/micropython) coordinates the creation of C wrappers, integration with Emscripten, and optimization to produce a final WebAssembly (WASM) file.
- Reproducible Build Support – reproducible.py (and the related reproducible-builds.md document) along with Dockerfile and Git actions ensure that builds can be recreated exactly for contract verification.
- External Integrations – include integration with uv (Python package management), Docker (for reproducible builds), and Emscripten (the WASM compiler driver).

##### Architectural Relationships and Data Flow
- User invokes the CLI (cli.py) which parses command-line options and identifies the contract entrypoint (using auto-detection rules such as looking for __init__.py or main.py).
- The CLI module then calls the Analyzer component to scan code for decorators and dependencies.
- The Manifest Generator (manifest.py) collects module information, while the Metadata Generator (metadata.py) prepares and injects NEP-330 compliant metadata based on project configurations (including potentially reading pyproject.toml).
- The Builder (builder.py) receives the processed abstract representation and, working with the integrated MicroPython runtime, generates C wrappers and triggers Emscripten to compile to WASM.
- If reproducible builds are requested, the process enters a Docker-centered build environment (as configured in Dockerfile, reproducible.py, and via Docker-based GitHub workflows) to ensure deterministic builds and subsequent verification.
- Finally, outputs such as the final WASM file and metadata information are generated and returned.

##### Important Architectural Patterns and Principles
- Modular Design – each stage of compilation (analysis, manifest creation, metadata injection, building) is separated into its own module.
- Decorator-Driven Functionality – the use of decorators (ex: @near.export) is central to exporting functions, which is a distinctive pattern in this design.
- Reproducible and Deterministic Builds – architectural emphasis on build reproducibility is supported via Docker configurations and Git integration.
- Integration with External Tools – such as Emscripten for WebAssembly compilation and uv for dependency management reflects a hybrid on-premise/CI workflow approach.

##### Technologies, Frameworks, and Tools
- Python (with MicroPython subset) is the language of choice.
- Emscripten serves as the WebAssembly compilation tool.
- Docker is used to guarantee reproducible builds.
- Git and uv are used for source control and package management respectively.
- GitHub Actions and associated workflow configurations (.github/workflows) streamline CI/CD and testing.

##### Detailing the Essential Architectural Elements
- Sequential processing: from code analysis (detecting functions and dependencies) to generating manifests and metadata, and then moving to the build/output stage.
- Incorporate annotations or notes that mention the NEP-330 metadata injection and the fact that all stateful changes (via decorators and the manifest) lead to the final WASM bytecode.
- Configuration dependencies (reproducible build settings and Docker image verification in the metadata).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    A["User Command"]:::external
    B["Compiler CLI (cli.py)"]:::internal
    subgraph "Code Analysis"
        C["Analyzer (analyzer.py)"]:::internal
        R["Utils (utils.py)"]:::internal
    end
    subgraph "Pre-Build Processing"
        D["Manifest Generator (manifest.py)"]:::internal
        E["Metadata Injector (metadata.py)"]:::internal
        F["Exports Handler (exports.py)"]:::internal
    end
    G["Code Builder (builder.py)"]:::internal
    H["MicroPython Runtime (src/nearc/micropython)"]:::internal
    I["Emscripten"]:::external
    J["WASM Output"]:::external
    K["Reproducible Build Support (reproducible.py)"]:::internal
    L["Reproducible Docs (reproducible-builds.md)"]:::external
    M["Docker Environment (Dockerfile)"]:::external
    N["Git CI Workflows (.github/workflows)"]:::external
    O["uv Package Management (uv.lock)"]:::external

    %% Flow Connections
    A -->|"initiates"| B
    B -->|"triggers"| C
    B -->|"triggers"| R
    C -->|"analyzes"| D
    C -->|"manages_dependencies"| O
    R --> D
    D -->|"generates"| E
    E -->|"injects"| F
    F -->|"passes IR to"| G
    G -->|"integrates"| H
    H -->|"compiles_with"| I
    I -->|"produces"| J
    %% Reproducible build branch from Builder
    G -->|"optional"| K
    K --> L
    L --> M
    M --> N

    %% Click Events
    click B "https://github.com/r-near/nearc/blob/main/src/nearc/cli.py"
    click C "https://github.com/r-near/nearc/blob/main/src/nearc/analyzer.py"
    click R "https://github.com/r-near/nearc/blob/main/src/nearc/utils.py"
    click D "https://github.com/r-near/nearc/blob/main/src/nearc/manifest.py"
    click E "https://github.com/r-near/nearc/blob/main/src/nearc/metadata.py"
    click F "https://github.com/r-near/nearc/blob/main/src/nearc/exports.py"
    click G "https://github.com/r-near/nearc/blob/main/src/nearc/builder.py"
    click H "https://github.com/r-near/nearc/tree/main/src/nearc/micropython"
    click K "https://github.com/r-near/nearc/blob/main/src/nearc/reproducible.py"
    click L "https://github.com/r-near/nearc/blob/main/docs/reproducible-builds.md"
    click M "https://github.com/r-near/nearc/tree/main/Dockerfile"
    click N "https://github.com/r-near/nearc/tree/main/.github/workflows"
    click O "https://github.com/r-near/nearc/blob/main/uv.lock"

    %% Styles
    classDef internal fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef external fill:#fce4ec,stroke:#ad1457,stroke-width:2px;
```
