React Native & Flutter Bridges

Relevant source files

The following files were used as context for generating this wiki page:

• bindings/react-native/packages/core/cpp/HybridRunAnywhereCore.cpp
• bindings/react-native/Docs/ARCHITECTURE.md
• bindings/react-native/AGENTS.md
• bindings/kotlin/AGENTS.md
• bindings/react-native/Docs/Documentation.md
• AGENTS.md
• bindings/flutter/packages/runanywhere/README.md

The RunAnywhere bridges provide a thin communication layer between cross-platform application frameworks and the high-performance C++ core library (runanywhere-commons). These bridges allow React Native and Flutter applications to execute on-device AI inference, manage model lifecycles, and handle secure storage by routing calls through optimized native interfaces.

The architecture prioritizes native ownership of SDK state. While the application UI interacts with TypeScript or Dart facades, the underlying auth, device identity, model registry, and inference orchestration live in the C++ core.
Sources: bindings/react-native/Docs/ARCHITECTURE.md:1-12, AGENTS.md:52-70

Bridge Architecture and Layers

The integration uses a multi-layered stack to ensure performance and portability. The React Native bridge specifically utilizes NitroModules, a JSI-based zero-serialization bridge, rather than the legacy React Native bridge or TurboModules.

5-Layer Stack Overview

Layer	Component	Responsibility
Layer 1	TypeScript / Dart API	Public facade, namespace modules (LLM, STT, etc.), and result marshalling.
Layer 2	Nitro / FFI Bridge	JSI handles for React Native; Dart FFI for Flutter. Zero-serialization calls.
Layer 3	C++ Bridge Code	HybridRunAnywhereCore.cpp and bridge slices (Auth, HTTP, Registry).
Layer 4	Platform Native	Platform-specific I/O (iOS Keychain, Android Keystore, OkHttp).
Layer 5	C++ Commons	Core AI logic, plugin registry, and event system.

Sources: bindings/react-native/AGENTS.md:86-107, AGENTS.md:104-122

Data Flow Diagram

The following diagram illustrates the flow of a request from the application UI down to the C++ core.

The bridge architecture enforces that logic lives at the lowest layer possible.
Sources: AGENTS.md:36-50, bindings/react-native/Docs/Documentation.md:88-93

Native Bridge Contracts

Communication across the bridge primarily uses encoded Protobuf bytes rather than JSON. This ensures type safety and performance across different programming languages.

Implementation Details

• Zero Serialization: React Native uses NitroModules to get a direct JSI handle to HybridRunAnywhereCore. This bypasses the serialization overhead of the standard bridge.
• FFI Mapping: Flutter uses Dart FFI to map directly to the rac_* C ABI symbols in the shared library.
• Protobuf Marshalling: TypeScript and Dart code encode request objects into bytes, which are passed as std::vector<uint8_t> or similar buffers to the C++ layer. The C++ core returns results as encoded bytes for the facade to decode.

Sources: bindings/react-native/AGENTS.md:110-118, bindings/react-native/Docs/ARCHITECTURE.md:83-94, AGENTS.md:73-83

Native Object Singletons

In React Native, the SDK initializes NitroModules and creates a singleton instance of HybridRunAnywhereCore.

// native/NativeRunAnywhereCore.ts
const native = NitroModules.createHybridObject<RunAnywhereCore>("RunAnywhereCore");

Sources: bindings/react-native/AGENTS.md:144-148, bindings/react-native/Docs/Documentation.md:90-93

Initialization Sequence

The bridges follow a consistent two-phase initialization pattern to ensure platform services are ready before inference begins.

Phase 1: Synchronous Native Setup

1. Loads native libraries (librunanywhere_jni.so or XCFrameworks).
2. Registers the rac_platform_adapter_t (C struct of function pointers for I/O).
3. Configures logging and telemetry sinks.
4. Sets the isReady flag for local inference.

Phase 2: Asynchronous Service Setup

1. Performs network-dependent tasks (Auth, device registration).
2. Fetches model assignments and populates the model catalog.
3. Discovers downloaded models through the native registry.

Sources: bindings/react-native/Docs/ARCHITECTURE.md:63-74, bindings/kotlin/AGENTS.md:70-85

Initialization Sequence Diagram

Bridge Interface Methods

The HybridRunAnywhereCore class provides the C++ implementation for approximately 60 methods covering SDK capabilities.

Key Functional Areas

Category	Description	Source File
Lifecycle	initialize, reset, completeServicesInitialization	HybridRunAnywhereCore.cpp
Model Registry	modelRegistryList, modelLifecycleLoad, modelRegistryRegister	Docs/Documentation.md
Inference	llmGenerateStream, sttTranscribe, ttsSynthesize	AGENTS.md
Storage	secureStorageSet, fileManagerExists, storageGetStats	Docs/ARCHITECTURE.md
Events	subscribeProtoEvents, unsubscribe	AGENTS.md

Sources: bindings/react-native/AGENTS.md:110-120, bindings/react-native/Docs/Documentation.md:43-58

Streaming and Async Iteration

A significant constraint in the React Native bridge is that the Hermes JS engine does not support for await...of loops with NitroModules-backed async iterables.

Manual Iteration Pattern

Developers must use a manual Symbol.asyncIterator loop for all streaming APIs (LLM, TTS, STT, Download):

const stream = await RunAnywhere.llm.generateStream(prompt);
const iterator = stream[Symbol.asyncIterator](https://github.com/RunanywhereAI/runanywhere-sdks/blob/067778a3832647ba05fb02ec9234822f6797d452/Symbol.asyncIterator);
while (true) {
  const { value, done } = await iterator.next();
  if (done) break;
  // Process value
}

Sources: bindings/react-native/AGENTS.md:126-136, bindings/react-native/Docs/Documentation.md:76-86

Streaming Components

• HybridLLM / HybridVoiceAgent: These native objects expose a subscribeProtoEvents method.
• Adapters: TypeScript/Dart adapters wrap native proto-byte callbacks into AsyncIterable or Stream objects.

Sources: bindings/react-native/AGENTS.md:120-124, bindings/kotlin/AGENTS.md:179-183

Summary

The React Native and Flutter bridges serve as high-performance conduits to the RunAnywhere C++ core. By utilizing zero-serialization mechanisms like NitroModules and Dart FFI, they maintain near-native inference speeds. The bridges strictly enforce native ownership of AI state and model management, ensuring that cross-platform applications behave consistently with the source-of-truth iOS Swift implementation.
Sources: AGENTS.md:52-59, bindings/react-native/Docs/ARCHITECTURE.md:14-23