# Overview

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

This is the source-of-truth integration guide for @ovok/native. It describes what the
package exports, what the host app must configure, and how data moves from a native
device or health platform into Ovok Core.

The guides explain how to use each part of the SDK and link to the
[API reference](../reference/index.mdx), which is generated from the SDK's doc comments and
lists every export with its signature, props and types. Guides do not repeat signatures;
when in doubt, the reference is the contract.

- [Getting started](./getting-started.md) gets a first sign-in screen running.
- [How-to guides](./how-to/app-building.md) cover installation, the app shell, whole app
  flows, observability and troubleshooting.
- [Modules](./modules/auth.md) has one page per import path, such as
  `@ovok/native/bluetooth` or `@ovok/native/data-sync`.
- Component pages show how each component is composed, styled and localized.

## What belongs where [#what-belongs-where]

@ovok/native is the React Native and native-integration layer:

- UI components for authentication, patients, measurements, content, questionnaires,
  themes, navigation helpers, and health workflows.
- Bluetooth Low Energy discovery, device protocols, measurement decoding, and device UI.
- Apple HealthKit and Android Health Connect authorization and import components.
- Background Bluetooth and Health Connect orchestration.
- Expo-compatible runtime polyfills used by the mobile client.

The root import is the `Ovok` client. Components, Bluetooth and optional integrations
are published as subpaths so an app can avoid loading unrelated native peers. The exact mapping is in the
[public API map](./public-api.md).

@ovok/core owns the client API, FHIR/authentication state, profile context, and the
server-facing data model. A working app normally mounts OvokProvider from
@ovok/core/react and ThemeProvider from @ovok/native/theme.

## Supported runtime shape [#supported-runtime-shape]

The repository example is a native Expo development build, not Expo Go. The SDK uses
native modules for BLE, HealthKit, Health Connect, PDF rendering, permissions, and
social sign-in. Adding the JavaScript package without rebuilding the native app is not
enough.

The supported path in this repository is:

1. Install @ovok/native and the peer dependencies for the features you use.
2. Add the required Expo config plugins and platform permissions.
3. Build a development or production binary.
4. Initialize the Ovok web API polyfills before creating the app's Ovok provider.
5. Mount the providers once at the app root.
6. Add feature components below the providers.

Continue with [installation](./how-to/installation.md), then [app shell and providers](./how-to/app-shell.md).

## Choose a path [#choose-a-path]

- Follow [Quick start](./getting-started.md) for the first working app shell.
- Follow [Build an app with the SDK](./how-to/app-building.md) for the complete composition path
  from authentication through measurements, health import, forms, and background work.
- Use the [how-to guides](./how-to/installation.md) for a focused integration task.
- Use the [App UI guide](./modules/ui.md), [Reusable flows](./how-to/reusable-flows.md), and component categories for UI integration.
- Use the [SDK feature index](./sdk-features.md) to find a guide for every published module.
- Read [Architecture and lifecycle](./architecture.md) when you need to understand
  provider ownership, native boundaries, or delivery guarantees.

## End-to-end paths [#end-to-end-paths]

| Path | Start here | Result |
| --- | --- | --- |
| Login and app shell | [App shell](./how-to/app-shell.md) and [authentication](./modules/auth.md) | Authenticated @ovok/core client and themed UI |
| Complete application path | [Build an app with the SDK](./how-to/app-building.md) | A host-owned app composed from the SDK's runtime, auth, device, health, UI, and background surfaces |
| Bluetooth measurement | [Bluetooth](./modules/bluetooth.md) and [supported devices](./supported-devices.md) | Find, pair, sync, and save readings |
| BLE background sync | [Bluetooth](./modules/bluetooth.md#syncing-by-itself) and [Background sync](./modules/background-sync.md) | Kept devices reconnect and save through the offline outbox, with iOS restoration and an Android foreground service |
| Apple HealthKit | [Health data](./modules/data-sync.md) | Authorized, incremental HealthKit import |
| Android Health Connect | [Health data](./modules/data-sync.md) | Authorized, incremental Health Connect import and optional headless scheduling |
| App UI | [App UI guide](./modules/ui.md) | Component-by-component usage and shared theme behavior |
| CMS content and translations | [CMS](./modules/cms.md) | Localized CMS data and translation loading |
| Progress indicators | [Progress bar](./modules/progress-bar.md) · [Progress ring](./modules/progress-ring.md) | Linear and circular indicators |
| Reusable UI flows | [Reusable flows](./how-to/reusable-flows.md) | Pairing, manual entry, and health-access integration examples |

## Important distinctions [#important-distinctions]

- A catalog entry is a `DeviceModel`. `BUILT_IN_MODELS` lists every model the SDK can
  pair; the catalog is fixed, and a new device on a known protocol is a new model row.
- A supported device family is not a promise that every product sold under that brand
  uses the same advertisement name or wire protocol. The catalog records the exact
  names and declarations known to this SDK.
- Background work is OS-controlled. The SDK persists results and provides the native
  hooks, but iOS and Android can still defer or stop work according to system policy.
- Health permissions are separate from Ovok authentication. A signed-in user can still
  refuse individual HealthKit or Health Connect data types.

## See also [#see-also]

- [Getting started](./getting-started.md)
- [Build an app with the SDK](./how-to/app-building.md)
- [Architecture and lifecycle](./architecture.md)
- [Public API map](./public-api.md)
