# mrousavy/nitro architecture

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

- Interactive diagram: https://gitdiagram.com/mrousavy/nitro
- Repository: https://github.com/mrousavy/nitro

## Overview

##### Project type and purpose
- This is an open-source, full-stack monorepo for building “Nitro Modules”—high-performance, typesafe native modules for React Native—consisting of two core parts:
- react-native-nitro-modules: a C++/JSI runtime library that powers modules at runtime
- nitrogen: a Node/TypeScript-based CLI code generator that turns a high-level spec into platform-specific glue code
- It also includes example modules (react-native-nitro-image), a template for new modules, documentation (Docusaurus), and CI/CD workflows.

##### High-level file-structure analysis
- Top level
- config, scripts, .github/workflows → linting, formatting, CI/CD
- docs → Docusaurus site for end-user and contributor docs
- example → a React Native app showing how to consume a generated module
- packages
– nitrogen → code generator (TS, syntax trees, autolinking, platform specs)
– react-native-nitro-modules → core C++ library + TypeScript binding APIs + native platform integration
– react-native-nitro-image → sample module built with nitrogen, showing how to write specs and native implementations
– template → starter boilerplate for new Nitro modules
- Each package has its own src, native code (cpp, android, ios), build scripts (Gradle, CMake, Podspec), tests, and TS configs.

##### Key insights from README
- End-users write a TypeScript interface (“spec”) describing their API
- nitrogen generates ahead-of-time type converters, hybrid object “spec” classes, and autolinking scripts for iOS/Android
- Native authors implement C++/Swift/Kotlin overrides of the generated Spec classes
- JS consumers call NitroModules.createHybridObject<Spec>(name) to get a fully typesafe object whose methods are bridged via JSI to native code

##### Main components
a. Developer workstation (VS Code/CLI)
b. nitrogen CLI (Node.js/TypeScript)
c. Spec definitions (.nitro.ts files)
d. Generated output
- Platform code:
- iOS: Swift bridge files, C++ spec bindings, CocoaPods/Ruby autolinking
- Android: C++, Kotlin/Java spec bindings, CMake/Gradle fragments
- Shared C++ types (cpp headers)
e. Core runtime: react-native-nitro-modules
- JSI binding layer (C++)
- JS API (TypeScript wrapper, NitroModules.ts)
- Native core (C++ code, fbjni for Android, Swift↔C++ interop for iOS)
f. React Native runtime
- Metro bundler packages JS + generated TypeScript glue
- JavaScriptCore or Hermes with JSI interface
g. Example module: react-native-nitro-image
- Shows end-to-end flow: spec → codegen → native → JS consumption
h. CI/CD pipelines (.github/workflows) & documentation site (docs)

##### Relationships and interactions
- Developer runs `nitrogen init` / `nitrogen generate` on spec files
→ nitrogen reads spec definitions → emits platform-specific source and build fragments
→ those files are checked into a module package (template or example)
- Building the RN app
→ Gradle/CMake builds Android native library → produces a .so with JSI exports
→ Xcode/CocoaPods builds iOS framework with JSI symbols
- Running the RN app
→ Metro bundles JS+TS glue → at runtime, JS calls NitroModules.createHybridObject
→ JSI layer routes calls through the native runtime (C++), invoking the user’s HybridSpec implementation
→ Data flows back via statically generated converters (no dynamic reflection)

##### Architectural patterns & design principles
- Monorepo with well-scoped packages (Generator, Runtime, Examples, Templates)
- Code-generation pipeline: high-level specs → static binding code → zero-overhead interop
- Hybrid object pattern: abstract Spec base classes in C++/Swift/Kotlin that the author extends
- JSI bridging: direct C++ ↔ JavaScriptCore/Hermes communication for minimal overhead
- Autolinking: generated platform integration scripts (Podspec, CMake, Gradle) for frictionless installs

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Developer/CLI Layer
  subgraph "Developer / CLI Layer"
    nitrogen["nitrogen CLI\n(Node.js/TypeScript)"]:::node
    spec["Spec Definitions\n(.nitro.ts)"]:::node
  end
  nitrogen -->|"reads specs"| spec

  %% Codegen for Example Module
  subgraph "Example Module Generation"
    ex_mod["react-native-nitro-image\n(sample module)"]:::node
    ex_gen_and["Android Generated\n(packages/react-native-nitro-image/nitrogen/generated/android)"]:::orange
    ex_gen_ios["iOS Generated\n(packages/react-native-nitro-image/nitrogen/generated/ios)"]:::orange
    ex_gen_shared["Shared C++ Types\n(packages/react-native-nitro-image/nitrogen/generated/shared/c++)"]:::cpp
  end
  spec -->|"generate code"| nitrogen
  nitrogen --> ex_gen_and
  nitrogen --> ex_gen_ios
  nitrogen --> ex_gen_shared
  click ex_mod "https://github.com/mrousavy/nitro/tree/main/packages/react-native-nitro-image"
  click ex_gen_and "https://github.com/mrousavy/nitro/tree/main/packages/react-native-nitro-image/nitrogen/generated/android/"
  click ex_gen_ios "https://github.com/mrousavy/nitro/tree/main/packages/react-native-nitro-image/nitrogen/generated/ios/"
  click ex_gen_shared "https://github.com/mrousavy/nitro/tree/main/packages/react-native-nitro-image/nitrogen/generated/shared/c++/"

  %% Template Module
  subgraph "Template for New Modules"
    template["Template Module\n(packages/template)"]:::node
  end
  spec -->|"generate boilerplate"| template
  click template "https://github.com/mrousavy/nitro/tree/main/packages/template"

  %% Build Layer
  subgraph "Build Layer"
    cmake["CMake/Gradle\n(Android Build)"]:::tool
    xcode["Xcode/CocoaPods\n(iOS Build)"]:::tool
  end
  ex_gen_and --> cmake
  ex_gen_shared --> cmake
  ex_gen_ios --> xcode
  cmake -->|"produces .so"| native_android
  xcode -->|"produces framework"| native_ios

  %% Runtime Layer
  subgraph "Core Runtime (react-native-nitro-modules)"
    runtime_js["JS API Wrapper\nNitroModules.ts"]:::node
    jsi_layer["JSI Binding Layer\n(C++)"]:::cpp
    native_android["Native Core Android\n(C++/Kotlin)"]:::orange
    native_ios["Native Core iOS\n(C++/Swift)"]:::orange
  end
  runtime_js -->|"calls"| jsi_layer
  jsi_layer -->|"invokes"| native_android
  jsi_layer -->|"invokes"| native_ios
  click runtime_js "https://github.com/mrousavy/nitro/blob/main/packages/react-native-nitro-modules/src/NitroModules.ts"
  click jsi_layer "https://github.com/mrousavy/nitro/tree/main/packages/react-native-nitro-modules/cpp/jsi/"
  click native_android "https://github.com/mrousavy/nitro/tree/main/packages/react-native-nitro-modules/android/src/main/cpp/"
  click native_ios "https://github.com/mrousavy/nitro/tree/main/packages/react-native-nitro-modules/ios/core/"

  %% App Layer
  subgraph "App Layer"
    app_example["Example App\n(example/)"]:::node
    metro["Metro Bundler\n(JS + Generated Glue)"]:::node
    rn_runtime["React Native Runtime\n(JSCore/Hermes)"]:::node
  end
  app_example --> metro
  metro --> rn_runtime
  rn_runtime --> runtime_js
  click app_example "https://github.com/mrousavy/nitro/tree/main/example/"

  %% Other Packages
  subgraph "Generator Package"
    nitrogen
  end
  click nitrogen "https://github.com/mrousavy/nitro/tree/main/packages/nitrogen"

  %% Docs & CI/CD
  subgraph "Docs & CI/CD"
    docs["Documentation Site\n(docs/)"]:::gray
    ci["CI/CD Workflows\n(.github/workflows/)"]:::gray
    lint["Lint & Format Config\n(config/)"]:::gray
  end
  click docs "https://github.com/mrousavy/nitro/tree/main/docs/"
  click ci "https://github.com/mrousavy/nitro/tree/main/.github/workflows/"
  click lint "https://github.com/mrousavy/nitro/tree/main/config/"

  %% Module Integrations
  ex_mod --> ex_gen_and
  ex_mod --> ex_gen_ios
  ex_mod --> ex_gen_shared

  classDef node fill:#D0E8FF,stroke:#0366d6;
  classDef cpp fill:#DFF2BF,stroke:#4F8A10;
  classDef orange fill:#FEEFB3,stroke:#9F6000;
  classDef tool fill:#EFEFEF,stroke:#000000;
  classDef gray fill:#F4F4F4,stroke:#AAAAAA;
```
