# napi-rs/napi-rs architecture

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

- Interactive diagram: https://gitdiagram.com/napi-rs/napi-rs
- Repository: https://github.com/napi-rs/napi-rs

## Overview

##### Project type and purpose
- This is a monorepo for a polyglot toolkit (“napi-rs”) that lets Rust code compile to Node-API modules and ships a companion JavaScript/TypeScript CLI, supporting benchmarks, examples, WASM runtime, target-triple utilities, CI configurations, and Dockerfiles.

##### File structure
- Top-level divides into:
- “crates/”: five Rust crates—sys (low-level bindings to Node C-API), macro (procedural macro for #[napi] annotations), napi (the Rust → N-API façade building on sys + macro), build (build scripts for various targets), backend (code-generation library used by the CLI).
- “cli/”: a Node.js/TS CLI wrapper that calls into the backend crate to scaffold projects, generate bindings, and publish NPM artifacts.
- “examples/”, “bench/”, “memory-testing/”, “wasm-runtime/”, “triples/”: demonstration, performance, testing, and auxiliary packages.
- CI & infra: .github/workflows for tests, Dockerfiles for Alpine/Debian/Zig toolchains, Yarn/Cargo workspace configs.

##### README insights
- The crates/napi README details the Rust → Node integration, features (async callbacks, type conversions, module registration), and target support. It confirms the layered architecture: sys → napi → user code.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI / Tooling
    subgraph "CLI / Tooling"
        direction TB
        CLI["Developer CLI (TS/Node)"]:::js
    end

    %% Rust Crates
    subgraph "Rust Crates"
        direction TB
        Backend["Backend Codegen Crate"]:::rust
        Macro["Macro Crate"]:::rust
        Build["Build Crate"]:::rust
        NAPI["N-API Crate"]:::rust
        Sys["Sys Crate"]:::rust
    end

    %% Runtime & Examples
    subgraph "Runtime & Examples"
        direction TB
        NodeRT["Node.js Runtime"]:::runtime
        NodeModule["*.node Module"]:::runtime
        Bench["Bench Harnesses"]:::js
        Examples["Examples"]:::js
        WASM["WASM Runtime"]:::js
        Triples["Target-Triple Utilities"]:::js
        MemTest["Memory-Testing"]:::js
    end

    %% CI & Deployment
    subgraph "CI & Deployment"
        direction TB
        CI["GitHub Actions"]:::infra
        DockerAgents["Docker Build Agents"]:::infra
        Registries["Registries"]:::registry
    end

    %% Relationships
    CLI -->|"invokes codegen"| Backend
    Macro -->|"#[napi] macro expansion"| NAPI
    Build -->|"cargo build"| NAPI
    Build -->|"cargo build"| Sys
    NAPI -->|produces| NodeModule
    Sys -->|produces| NodeModule
    NodeRT -->|"require('module.node')"| NodeModule

    Bench -->|"uses"| NAPI
    Examples -->|"uses"| NAPI
    WASM -->|"uses"| NAPI
    Triples -->|"uses"| NAPI
    MemTest -->|"uses"| NAPI

    CI -->|"runs workflows"| DockerAgents
    CI -->|"runs workflows"| Registries
    CI -->|"runs workflows"| CLI
    CI -->|"orchestrates"| Build

    %% Click Events
    click CLI "https://github.com/napi-rs/napi-rs/tree/main/cli/"
    click Backend "https://github.com/napi-rs/napi-rs/tree/main/crates/backend/"
    click Macro "https://github.com/napi-rs/napi-rs/tree/main/crates/macro/"
    click Build "https://github.com/napi-rs/napi-rs/tree/main/crates/build/"
    click NAPI "https://github.com/napi-rs/napi-rs/tree/main/crates/napi/"
    click Sys "https://github.com/napi-rs/napi-rs/tree/main/crates/sys/"
    click Bench "https://github.com/napi-rs/napi-rs/tree/main/bench/"
    click Examples "https://github.com/napi-rs/napi-rs/tree/main/examples/"
    click WASM "https://github.com/napi-rs/napi-rs/tree/main/wasm-runtime/"
    click Triples "https://github.com/napi-rs/napi-rs/tree/main/triples/"
    click MemTest "https://github.com/napi-rs/napi-rs/tree/main/memory-testing/"
    click CI "https://github.com/napi-rs/napi-rs/tree/main/.github/workflows/"
    click DockerAgents "https://github.com/napi-rs/napi-rs/tree/main/Dockerfile"

    %% Styles
    classDef rust fill:#e0f2e9,stroke:#2e7d32,color:#2e7d32;
    classDef js fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
    classDef runtime fill:#fff3e0,stroke:#f57c00,color:#f57c00;
    classDef infra fill:#eceff1,stroke:#607d8b,color:#607d8b,stroke-dasharray: 5 5;
    classDef registry fill:#f3e5f5,stroke:#8e24aa,color:#8e24aa;
    class Registries registry;
```
