# wjakob/nanobind architecture

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

- Interactive diagram: https://gitdiagram.com/wjakob/nanobind
- Repository: https://github.com/wjakob/nanobind

## Overview

##### Project type and purpose
- nanobind is a C++ library for creating Python bindings. It exposes C++ types/functions to Python via a thin header-only API plus a small runtime core library.
- It ships as a Python package (PyPI) and supports CMake and Bazel build systems.

##### File structure
- Top-level directories:
- /nanobind → public headers (the binding API)
- src → core C++ implementation, small Python helper scripts (stubgen.py, version.py, __main__.py)
- ext/robin_map → third-party submodule for efficient hash maps
- cmake/ & CMakeLists.txt, .gitmodules → build scripts and configuration for CMake (and spinnable to Bazel)
- tests → C++ (Google Test) and Python (pytest) test suites exercising bindings
- docs → Sphinx documentation source
- Build artifacts: shared libraries (.so/.pyd) generated by CMake/Bazel
- Packaging: pyproject.toml defines Python packaging metadata

##### README for additional insights
- Emphasizes performance: faster compile times, smaller binaries, lower runtime overhead vs. pybind11 and Cython
- Highlights core features: header-only syntax, near-identical API to pybind11, cross-interpreter support (CPython & PyPy)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development Layer
    subgraph "Development"
        DevCpp["Developer C++ Code"]:::code
        NB_API["nanobind API"]:::code
        click NB_API "https://github.com/wjakob/nanobind/tree/master/include/nanobind/"
        Eigen["Eigen Support Headers"]:::storage
        click Eigen "https://github.com/wjakob/nanobind/tree/master/include/nanobind/eigen/"
        DevCpp -->|"#include"| NB_API
        DevCpp -->|"#include"| Eigen
    end

    %% Core Components
    NB_Core["nanobind Core"]:::code
    click NB_Core "https://github.com/wjakob/nanobind/tree/master/src/"
    RobinMap["robin_map Submodule"]:::storage
    click RobinMap "https://github.com/wjakob/nanobind/tree/master/ext/robin_map/"

    %% Build & Packaging Layer
    subgraph "Build & Packaging"
        BS["Build System (CMake & Bazel)"]:::build
        click BS "https://github.com/wjakob/nanobind/blob/master/CMakeLists.txt"
        click BS "https://github.com/wjakob/nanobind/tree/master/cmake/"
        click BS "https://github.com/wjakob/nanobind/blob/master/.gitmodules"
        PMC["pyproject.toml"]:::build
        click PMC "https://github.com/wjakob/nanobind/blob/master/pyproject.toml"
        BS -->|"pulls in headers & sources"| NB_API
        BS -->|"pulls in core"| NB_Core
        BS -->|"pulls in submodule"| RobinMap
        BS -->|"produces"| ExtMod
        BS -->|"configures package metadata"| PMC
    end

    %% Runtime Layer
    subgraph "Runtime"
        ExtMod["Extension Module (.so/.pyd)"]:::runtime
        PyInterp["Python Interpreter (CPython/PyPy)"]:::runtime
        Stub["stubgen.py"]:::script
        click Stub "https://github.com/wjakob/nanobind/blob/master/src/stubgen.py"
        Version["version.py"]:::script
        click Version "https://github.com/wjakob/nanobind/blob/master/src/version.py"
        Main["__main__.py"]:::script
        click Main "https://github.com/wjakob/nanobind/blob/master/src/__main__.py"

        ExtMod -->|"import → load"| PyInterp
        PyInterp -->|"executes"| Stub
        Stub -->|"emits .pyi stubs"| ExtMod
        PyInterp -->|"reads version"| Version
        PyInterp -->|"module entrypoint"| Main
    end

    %% Testing & Documentation Layer
    subgraph "Testing & Documentation"
        CppTest["C++ Test Harness (Google Test)"]:::test
        click CppTest "https://github.com/wjakob/nanobind/tree/master/tests/"
        PyTest["Python Test Suite (pytest)"]:::test
        click PyTest "https://github.com/wjakob/nanobind/tree/master/tests/"
        Docs["Documentation (Sphinx)"]:::doc
        click Docs "https://github.com/wjakob/nanobind/tree/master/docs/"

        CppTest -->|"invokes build"| BS
        PyTest -->|"imports extension"| ExtMod
        Docs -->|"reads headers & core"| NB_API
        Docs -->|"reads headers & core"| NB_Core
    end

    %% External Dependencies
    EigenDep["Python C-API & External Libraries"]:::storage

    %% Connections to External
    BS -->|"links against"| EigenDep
    NB_Core -->|"uses"| EigenDep
    ExtMod -->|"uses Python C-API"| EigenDep

    %% Styles
    classDef code fill:#D0E1F9,stroke:#4A90E2;
    classDef build fill:#C6E5B3,stroke:#3C763D;
    classDef runtime fill:#FDEBC4,stroke:#8A6D3B;
    classDef test fill:#F8D7DA,stroke:#A94442;
    classDef doc fill:#E2F0CB,stroke:#567D46;
    classDef storage fill:#CCCCCC,stroke:#666666;
    classDef script fill:#FBE4FA,stroke:#A64D79;
```
