Architecture
The React SDK connects your React app to Orga’s real‑time AI runtime.
It builds on @orga-ai/core for configuration, implements WebRTC for the browser, and coordinates with a backend service that mints credentials.
Understanding these roles helps you debug, extend, and design reliable integrations.
Layers at a Glance
Division of Responsibilities
| Layer | Description |
|---|---|
| App UI | Your React app: gets context values and renders UX for calls or conversations. |
| React SDK (@orga-ai/react) | Platform adapter that manages WebRTC setup, media streams, and event lifecycles. Provides hooks and providers that wrap the core layer. |
| Core (@orga-ai/core) | Shared foundation for all SDKs — owns configuration, validation, and common types. It defines ports and contracts that each SDK implements. |
| Server SDK / REST API | Backend component that authenticates using your API key and issues short‑lived ephemeral tokens and ICE configurations. |
Context Providers and Hooks
<OrgaAIProvider>bootstraps the client, sets up configuration, and shares context with descendants.
It accepts agetSessionConfig()callback that provides tokens and ICE servers.useOrgaAI()gives direct access to session control — connect, disconnect, and access active track info.
Relationship to the Server SDK
Your backend mints ephemeral tokens and returns session configuration (tokens + ICE servers).
Implement this with:
- @orga-ai/node – for Node.js environments
- Direct REST calls – if you already maintain an integration pipeline
The React SDK never handles privileged API keys.
Instead, it invokes your provided getSessionConfig() function, receives an ephemeral token, and passes it downstream to Orga for authentication.
Key Takeaways
- WebRTC negotiation and media handling live inside @orga-ai/react (and other platform SDKs).
- @orga-ai/core never constructs
RTCPeerConnection— it only manages shared configuration and event contracts. - When
disconnect()runs (automatically or by user action), the provider cleans up peer connections, event listeners to avoid leaks.
Platform Adaptation
Each SDK implements the same shared contracts from @orga-ai/core, customized for its environment:
| Platform | Implementation Details |
|---|---|
| Web (React) | Uses WebRTC APIs, navigator.mediaDevices, and browser storage. |
| React Native | Uses react-native-webrtc, AsyncStorage, and native permission prompts. |
| Future SDKs | Other environments (Vue, Svelte, Unity, etc.) can implement the same ports to extend Orga’s core runtime. |
Conditional exports in each package’s package.json ensure frameworks like Next.js, Metro, and Vite load the correct entry point automatically.
Monorepo Integration
The SDKs live in a single TypeScript monorepo with project references.
This keeps types synchronized — any change in @orga-ai/core immediately flows to @orga-ai/react builds.
Avoid breaking references when customizing; it enables fast incremental builds and shared typing.
Next Steps
- Quick Start → Step‑by‑step setup and backend integration.
- API Reference → Reference for the OrgaAI class.
- Troubleshooting → Troubleshooting guide.