# Architecture and lifecycle

Canonical page: https://docs.ovok.com/native-sdk/guide/architecture

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](./how-to/app-shell.md).

## System boundaries [#system-boundaries]

```text
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. 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 [#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](./how-to/app-shell.md).

## Startup and context lifetime [#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](./components/polyfills/index.md).
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](./how-to/installation.md) for package setup and [App shell and providers](./how-to/app-shell.md) for a complete provider example.

## Foreground lifecycle [#foreground-lifecycle]

### Bluetooth device data [#bluetooth-device-data]

The Bluetooth flow runs inside the foreground React Native tree:

1. The app creates `Bluetooth` with `createBluetooth` and renders the device workflow under `BluetoothProvider`.
2. Discovery checks Bluetooth permissions and availability, and lists the supported devices nearby.
3. The user pairs a device, and the app gets a `Device` handle for it.
4. Syncing and live streaming are methods on that handle. Each reading is saved through the `Ovok` client's outbox, which keeps it on the device until the server accepts it.
5. 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](./modules/bluetooth.md) for setup and details.

### Health-data import [#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](./how-to/app-shell.md).
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 the `Ovok` client's `measurements.saveObservationGroups`.
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](./modules/data-sync.md) for supported data and platform details.

### Forms and app records [#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](./public-api.md) for component props and callback signatures.

## Background lifecycle [#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](./modules/background-sync.md) for platform setup and operational details.

## State boundaries [#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 [#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](./public-api.md).

## See also [#see-also]

- [Public API map](./public-api.md)
- [App shell and providers](./how-to/app-shell.md)
- [Troubleshooting](./how-to/troubleshooting.md): setup or runtime behavior that differs by platform.
