Architecture and lifecycle
Understand SDK boundaries, provider lifetimes, and foreground and background data flows.
- Stable unknown
- Release candidate since 1.16.1-rc.1
- Development since 1.16.1-dev+97b2473
OVOK React Native 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 servicesThe host app composes the pieces. The Ovok client from @ovok/native provides the authenticated API boundary; the @ovok/native/<module> subpaths add 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. |
Ovok (@ovok/native) | Makes authenticated requests to OVOK services and keeps the session in the device's secure store. The app supplies it through OvokProvider from @ovok/core/react. |
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. |
BluetoothProvider | Gives its children one Bluetooth instance from createBluetooth, which finds, pairs and syncs devices and saves their readings through the Ovok client. |
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:
- Initialize the runtime from the app entry module before importing SDK modules; see Polyfills and runtime setup.
- Create the client with the app’s configuration and authentication strategy.
- Render the root providers around the part of the app that uses SDK components.
- 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:
- The app creates
BluetoothwithcreateBluetoothand renders the device workflow underBluetoothProvider. - Discovery checks Bluetooth permissions and availability, and lists the supported devices nearby.
- The user pairs a device, and the app gets a
Devicehandle for it. - Syncing and live streaming are methods on that handle. Each reading is saved through the
Ovokclient's outbox, which keeps it on the device until the server accepts it. - The host app decides which screens show the device and its readings.
Saving is built in, so the app does not handle each result. The outbox is the handoff point: it retries until the server accepts a reading. See Bluetooth for setup and details.
Health-data import
Health-data sync uses the active client and patient context:
- The app renders the health authorization and sync flow under the providers described in App shell and providers.
- The user grants or denies access through the platform’s health-data permission UI.
- The SDK reads the selected health data through the native platform integration.
DataSyncsubmits supported data for the active patient through theOvokclient'smeasurements.saveObservationGroups.- 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 keep-alive | A paired device set to keepInBackground connects, or the app leaves the foreground. | Keeps the link open, syncs the device, and saves its readings through the outbox, which retries until the server accepts them. | Call createBluetooth at app start and choose which devices stay connected. |
| 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 Ovok client. Import components and platform-specific integrations from their documented public subpaths. Avoid reaching into internal source paths: internal file layout is not a stable API.
For package entry points and exports, see the public API.
See also
- Public API map
- App shell and providers
- Troubleshooting: setup or runtime behavior that differs by platform.
Last updated on