Architecture and lifecycle

OVOK Mobile SDK connects a React Native app to OVOK services and native device capabilities. The app owns its navigation, screens, and product decisions; the SDK provides reusable UI, client access, and integrations for health data and Bluetooth devices.

This page maps those responsibilities and shows how the main flows move through the app. For the recommended provider setup, see App shell and providers.

System boundaries

Host React Native app
        │ public components and hooks
        ▼
@ovok/native ◄──────────────────────► OS and device APIs
        │ shared models and services
        ▼
@ovok/core ◄────────────────────────► OVOK services

The host app composes the pieces. OvokClient provides the authenticated API boundary; @ovok/native adds mobile-specific workflows and components; @ovok/core contains shared client behavior and types. Native integrations also communicate with operating-system services such as Bluetooth and HealthKit.

Who owns what

Boundary	Responsibility
Host app	Creates the client, chooses when and where SDK components appear, owns navigation, and decides how records are stored or presented.
OvokClient	Makes authenticated requests to OVOK services. The app supplies it through the client context.
OvokThemeProvider	Supplies theme values to SDK UI. Place it above SDK components that render themed UI.
Authentication components	Collect credentials and invoke the configured authentication callbacks. The host app decides how successful authentication changes its session or navigation.
BTProvider	Owns the in-app Bluetooth scanning and device-connection experience. It checks required permissions and exposes device results to its children.
DataSync	Coordinates health-data authorization and sync against the active client and patient context.
Background helpers	Bridge native background events into sync work. The operating system controls when those events run.
SDK UI components	Render reusable forms and flows. The host app supplies domain choices such as questionnaire, patient, and navigation behavior.

Provider composition and initialization order are shown in App shell and providers.

Startup and context lifetime

Initialize the SDK at the app boundary:

1. Initialize the runtime from the app entry module before importing SDK modules; see Polyfills and runtime setup.
2. Create the client with the app’s configuration and authentication strategy.
3. Render the root providers around the part of the app that uses SDK components.
4. Keep the client identity stable for the authenticated session. When the user signs out or changes account, update the app’s session and client context accordingly.

The providers make client and theme context available to descendants. They do not replace the app’s navigation or session state. Avoid creating a new client on every render; doing so can reset state or interrupt work that depends on the current client.

See Installation for package setup and App shell and providers for a complete provider example.

Foreground lifecycle

Bluetooth device data

The Bluetooth flow runs inside the foreground React Native tree:

1. The app renders the device workflow under BTProvider.
2. The provider checks Bluetooth permissions and availability before exposing the scanning experience.
3. The user selects or connects a device, and the provider receives device data.
4. The configured result callback receives a stable id, deviceData, and the decoded data payload.
5. The host app decides how to associate that result with a patient and whether to persist or upload it.

The callback is the handoff point between the SDK’s device workflow and app-owned record handling. Treat the stable id as an idempotency key when the same result may be delivered again. See Bluetooth for setup and callback details.

Health-data import

Health-data sync uses the active client and patient context:

1. The app renders the health authorization and sync flow under the providers described in App shell and providers.
2. The user grants or denies access through the platform’s health-data permission UI.
3. The SDK reads the selected health data through the native platform integration.
4. DataSync submits supported data for the active patient through OvokClient.
5. The app remains responsible for its surrounding UX, such as showing sync status or deciding when to offer the flow.

Health permissions are controlled by the operating system and can change outside the app. Handle authorization and sync errors as normal states. See Health data for supported data and platform details.

Forms and app records

SDK form components handle reusable form presentation and submission mechanics. The host app supplies the relevant resource or values and chooses how a successful submission affects app state. Depending on the component, submission can use an SDK callback such as onSuccess(response) or an app-owned handler such as onSubmit(values, helpers).

The app owns navigation after submission and any product-specific persistence or follow-up. See the public API for component props and callback signatures.

Background lifecycle

Background work has a different lifecycle from the foreground React tree. Native operating systems schedule and constrain execution, so a background task may run later than requested or be stopped before finishing.

Workflow	What starts it	What the SDK does	App responsibility
Bluetooth result queue	A device result is received while background delivery is configured.	Queues result handling and retries work that has not been acknowledged. Delivery is at least once, so a result may be seen more than once.	Make processing idempotent using the result id; handle persistence and upload in the callback.
Android Health Connect task	The platform invokes the registered headless task.	Runs the configured health sync without mounting the normal React UI tree.	Restore the authentication, client, and patient context needed for the task. Do not rely on in-memory state from the foreground app.
Apple HealthKit observer	HealthKit reports a change through its observer mechanism.	Wakes the native integration to process eligible health data.	Configure the app and permissions correctly, and tolerate delayed or repeated notifications.

Background execution is not a promise of immediate delivery. Persist the minimum state needed to resume safely, make writes idempotent, and surface the last sync status when the app returns to the foreground. See Background sync for platform setup and operational details.

State boundaries

Keep these lifetimes separate when designing app state:

• Authentication belongs to the host app’s session model. SDK requests use the client supplied for the current session.
• Bluetooth permissions and connections are platform state and may change while the app is open or in the background.
• Health permissions are granted by the user through OS settings and can be revoked independently of app authentication.
• Network availability is transient. A failed request does not necessarily mean the user’s session is invalid.
• Background execution is scheduled by the OS and may not share the foreground JavaScript runtime or in-memory state.

Model these as independent states in the host app. For example, an authenticated user may still have denied HealthKit permission, and a permitted Bluetooth device may be temporarily unreachable.

Import boundaries

Use the package root for the main client and commonly used components. Use documented public subpaths when a feature requires a platform-specific integration. Avoid reaching into internal source paths: internal file layout is not a stable API.

For package entry points and exports, see the public API. For recovery guidance when setup or runtime behavior differs by platform, see Troubleshooting.