# margelo/nitro architecture

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

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

## Overview

Nitro Modules provides a React Native runtime for statically compiled JSI bindings, plus the optional `nitrogen` generator used by module authors. The main author workflow is to declare a HybridObject in TypeScript, generate platform bindings, implement it natively, then create and call it from JavaScript. Runtime support includes native object registration, JSI method conversion, platform type bridges, and hybrid views. The README documents the product-level workflow; source-index references and excerpts support only selected internal links, so unsampled relationships are omitted.

Main entry points: [`packages/nitrogen/src/syntax/types/Type.ts`](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/types/Type.ts) (Native type model), [`packages/nitrogen/src/index.ts`](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/index.ts) (Generator entry), [`packages/nitrogen/src/syntax/HybridObjectSpec.ts`](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/HybridObjectSpec.ts) (HybridObject model), [`packages/react-native-nitro-modules/cpp/core/HybridFunction.hpp`](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/cpp/core/HybridFunction.hpp) (JSI method calls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Module authoring"]
  node_ts_spec["TypeScript specs"]
end

subgraph group_generator["Nitrogen generator"]
  node_nitrogen_cli["Generator entry<br/>[index.ts]"]
  node_config["Generator config<br/>[NitroConfig.ts]"]
  node_platform_specs["Platform analysis"]
  node_hybrid_spec["HybridObject model"]
  node_type_model["Native type model<br/>[Type.ts]"]
  node_type_factory["Type analysis<br/>[createType.ts]"]
  node_source_file["Generated source model<br/>[SourceFile.ts]"]
  node_cpp_bindings["C++ bindings"]
  node_kotlin_bridge["Kotlin bridge"]
  node_swift_bridge["Swift bridge"]
  node_view_codegen["Hybrid view generation"]
end

subgraph group_runtime["Core runtime"]
  node_js_api["JavaScript API<br/>[NitroModules.ts]"]
  node_js_proxy["Hybrid object proxy"]
  node_native_registry[("Object registry")]
  node_jsi_methods["JSI method calls<br/>[HybridFunction.hpp]"]
  node_object_prototype["Object prototype<br/>[Prototype.hpp]"]
end

subgraph group_platforms["Native platforms"]
  node_android_runtime["Android runtime<br/>[JHybridObject.cpp]"]
  node_ios_runtime["iOS runtime<br/>[HybridObject.swift]"]
  node_hybrid_views["Native hybrid views<br/>[HybridView.ts]"]
end

node_module_author(("Module author"))

node_module_author -->|"declares interface"| node_ts_spec
node_ts_spec -->|"generates bindings"| node_nitrogen_cli
node_nitrogen_cli -.->|"uses configuration"| node_config
node_nitrogen_cli -.->|"analyzes platforms"| node_platform_specs
node_platform_specs -.->|"identifies platforms"| node_hybrid_spec
node_type_factory -->|"creates types"| node_type_model
node_hybrid_spec -.->|"models members"| node_type_model
node_type_model -->|"describes generated files"| node_source_file
node_type_model -->|"requests declarations"| node_cpp_bindings
node_type_model -->|"converts types"| node_kotlin_bridge
node_type_model -.->|"converts types"| node_swift_bridge
node_hybrid_spec -->|"supplies view spec"| node_view_codegen
node_module_author -->|"uses module"| node_js_api
node_js_api -.->|"delegates access"| node_js_proxy
node_js_proxy -.->|"requests object"| node_native_registry
node_native_registry -.->|"exposes methods"| node_jsi_methods
node_object_prototype -->|"uses functions"| node_jsi_methods
node_jsi_methods -->|"returns result"| node_module_author
node_module_author -->|"implements natively"| node_android_runtime
node_module_author -->|"implements natively"| node_ios_runtime
node_module_author -->|"uses view components"| node_hybrid_views

click node_ts_spec "https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-test/src/specs/TestObject.nitro.ts"
click node_nitrogen_cli "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/index.ts"
click node_config "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/config/NitroConfig.ts"
click node_platform_specs "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/getPlatformSpecs.ts"
click node_hybrid_spec "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/HybridObjectSpec.ts"
click node_type_model "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/types/Type.ts"
click node_type_factory "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/createType.ts"
click node_source_file "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/SourceFile.ts"
click node_cpp_bindings "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/c%2B%2B/getForwardDeclaration.ts"
click node_kotlin_bridge "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/kotlin/KotlinCxxBridgedType.ts"
click node_swift_bridge "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/swift/SwiftCxxBridgedType.ts"
click node_view_codegen "https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/views/CppHybridViewComponent.ts"
click node_js_api "https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/src/NitroModules.ts"
click node_js_proxy "https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/src/NitroModulesProxy.ts"
click node_native_registry "https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/cpp/registry/HybridObjectRegistry.cpp"
click node_jsi_methods "https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/cpp/core/HybridFunction.hpp"
click node_object_prototype "https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/cpp/prototype/Prototype.hpp"
click node_android_runtime "https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/android/src/main/cpp/core/JHybridObject.cpp"
click node_ios_runtime "https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/ios/core/HybridObject.swift"
click node_hybrid_views "https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/src/views/HybridView.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ts_spec toneBlue
class node_nitrogen_cli,node_config,node_platform_specs,node_hybrid_spec,node_type_model,node_type_factory,node_source_file,node_cpp_bindings,node_kotlin_bridge,node_swift_bridge,node_view_codegen toneAmber
class node_js_api,node_js_proxy,node_native_registry,node_jsi_methods,node_object_prototype toneMint
class node_android_runtime,node_ios_runtime,node_hybrid_views toneRose
class node_module_author toneIndigo
```

## Components

### Module authoring

- [TypeScript specs](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-test/src/specs/TestObject.nitro.ts): `packages/react-native-nitro-test/src/specs/TestObject.nitro.ts`

### Nitrogen generator

- [Generator entry](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/index.ts): `packages/nitrogen/src/index.ts`
- [Generator config](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/config/NitroConfig.ts): `packages/nitrogen/src/config/NitroConfig.ts`
- [Platform analysis](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/getPlatformSpecs.ts): `packages/nitrogen/src/getPlatformSpecs.ts`
- [HybridObject model](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/HybridObjectSpec.ts): `packages/nitrogen/src/syntax/HybridObjectSpec.ts`
- [Native type model](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/types/Type.ts): `packages/nitrogen/src/syntax/types/Type.ts`
- [Type analysis](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/createType.ts): `packages/nitrogen/src/syntax/createType.ts`
- [Generated source model](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/SourceFile.ts): `packages/nitrogen/src/syntax/SourceFile.ts`
- [C++ bindings](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/c%2B%2B/getForwardDeclaration.ts): `packages/nitrogen/src/syntax/c++/getForwardDeclaration.ts`
- [Kotlin bridge](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/kotlin/KotlinCxxBridgedType.ts): `packages/nitrogen/src/syntax/kotlin/KotlinCxxBridgedType.ts`
- [Swift bridge](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/syntax/swift/SwiftCxxBridgedType.ts): `packages/nitrogen/src/syntax/swift/SwiftCxxBridgedType.ts`
- [Hybrid view generation](https://github.com/margelo/nitro/blob/main/packages/nitrogen/src/views/CppHybridViewComponent.ts): `packages/nitrogen/src/views/CppHybridViewComponent.ts`

### Core runtime

- [JavaScript API](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/src/NitroModules.ts): `packages/react-native-nitro-modules/src/NitroModules.ts`
- [Hybrid object proxy](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/src/NitroModulesProxy.ts): `packages/react-native-nitro-modules/src/NitroModulesProxy.ts`
- [Object registry](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/cpp/registry/HybridObjectRegistry.cpp): `packages/react-native-nitro-modules/cpp/registry/HybridObjectRegistry.cpp`
- [JSI method calls](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/cpp/core/HybridFunction.hpp): `packages/react-native-nitro-modules/cpp/core/HybridFunction.hpp`
- [Object prototype](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/cpp/prototype/Prototype.hpp): `packages/react-native-nitro-modules/cpp/prototype/Prototype.hpp`

### Native platforms

- [Android runtime](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/android/src/main/cpp/core/JHybridObject.cpp): `packages/react-native-nitro-modules/android/src/main/cpp/core/JHybridObject.cpp`
- [iOS runtime](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/ios/core/HybridObject.swift): `packages/react-native-nitro-modules/ios/core/HybridObject.swift`
- [Native hybrid views](https://github.com/margelo/nitro/blob/main/packages/react-native-nitro-modules/src/views/HybridView.ts): `packages/react-native-nitro-modules/src/views/HybridView.ts`

### Other components

- **Module author**

## Connections

- Module author → TypeScript specs: declares interface (evidence: `README.md`)
- TypeScript specs → Generator entry: generates bindings (evidence: `README.md`)
- Generator entry → Generator config: uses configuration
- Generator entry → Platform analysis: analyzes platforms
- Platform analysis → HybridObject model: identifies platforms
- Type analysis → Native type model: creates types (evidence: `packages/nitrogen/src/syntax/createType.ts`)
- HybridObject model → Native type model: models members
- Native type model → Generated source model: describes generated files (evidence: `packages/nitrogen/src/syntax/SourceFile.ts`)
- Native type model → C++ bindings: requests declarations (evidence: `packages/nitrogen/src/syntax/types/HybridObjectType.ts`)
- Native type model → Kotlin bridge: converts types (evidence: `packages/nitrogen/src/syntax/kotlin/KotlinCxxBridgedType.ts`)
- Native type model → Swift bridge: converts types (evidence: `packages/nitrogen/src/syntax/swift/SwiftCxxBridgedType.ts`)
- HybridObject model → Hybrid view generation: supplies view spec (evidence: `packages/nitrogen/src/views/swift/SwiftHybridViewManager.ts`)
- Module author → JavaScript API: uses module (evidence: `README.md`)
- JavaScript API → Hybrid object proxy: delegates access
- Hybrid object proxy → Object registry: requests object
- Object registry → JSI method calls: exposes methods
- Object prototype → JSI method calls: uses functions (evidence: `packages/react-native-nitro-modules/cpp/prototype/Prototype.hpp`)
- JSI method calls → Module author: returns result (evidence: `README.md`)
- Module author → Android runtime: implements natively (evidence: `README.md`)
- Module author → iOS runtime: implements natively (evidence: `README.md`)
- Module author → Native hybrid views: uses view components (evidence: `README.md`)
