React SDK architecture

The React adapter sits between your UI and the Orga core runtime. It owns WebRTC orchestration inside the browser, exposes state through hooks, and calls into your backend when ephemeral credentials are needed. Understanding these layers makes debugging and scaling dramatically easier.

Layer map

Layer	Responsibility
UI	Renders the experience, binds to hook outputs, decides when to start/stop sessions.
React SDK	Manages WebRTC transports, translates core state into React context, cleans up tracks.
Core	Stores config, validates options, sends SDP offers to Orga Cloud.
Backend	Keeps the permanent API key and issues short-lived credentials.

Provider + hook contract

<OrgaAIProvider> boots the SDK once per React tree, subscribes to lifecycle events (connect, reconnect, teardown), and exposes connection state to descendants.
useOrgaAI() provides imperative controls (startSession, endSession, toggle mic/camera) plus derived data (connection status, active tracks, conversation metadata).
Hooks are intentionally thin—they do not reimplement business logic already defined in @orga-ai/core; they simply project it into React.

Interaction with the backend

Security principle: the API key never reaches the browser. The only credential in flight is the short-lived token your backend just minted.

Notable design choices

WebRTC handling stays client-side – The adapter calls navigator.mediaDevices, attaches streams, and tears them down. Core is unaware of browser APIs.
Core reusability – Because config and request helpers live in @orga-ai/core, React and React Native stay in sync automatically.
Cleanup discipline – When the provider unmounts or endSession() runs, it stops tracks, closes the peer connection, and clears event listeners to avoid zombie media usage.

When to read other docs

Need to provision credentials? Revisit the Node SDK architecture explanation.
Want the conceptual background for WebRTC? See the WebRTC model explanation.
Ready to execute? Jump to the React tutorial or the React SDK reference.