# Mobile Platform SDK Decision

Status: active decision
Date: May 5, 2026
Decision: defer direct adoption of `@bytelyst/react-native-platform-sdk` for the production-readiness handoff.

## Context

NoteLett mobile already uses shared common-platform clients directly:

- `@bytelyst/auth-client` in `mobile/src/api/auth.ts`
- `@bytelyst/api-client` in `mobile/src/api/client.ts`
- `@bytelyst/platform-client` in `mobile/src/lib/platform-api.ts`
- telemetry, feature flags, kill switch, blob, diagnostics, billing, broadcast, survey, feedback, and offline queue clients in `mobile/src/lib/*`

The current `@bytelyst/react-native-platform-sdk` package in `../learning_ai/learning_ai_common_plat` exposes React Native providers/hooks for auth, telemetry, feature flags, kill switch, broadcasts, and surveys. It does not yet cover the full NoteLett mobile composition: product-backend API calls, blob uploads, diagnostics singleton metadata, billing, feedback, offline queue flushing, or the existing `@bytelyst/auth-client` token storage contract.

## Decision

Defer replacing NoteLett's direct shared clients with `@bytelyst/react-native-platform-sdk` until the shared SDK can be adopted without losing current behavior.

This is not a rejection of the SDK. It is a release-readiness choice: the direct clients already come from common platform, have product/auth/request propagation tests, and are closer to NoteLett's current Expo/MMKV architecture.

## Required Adoption Criteria

Adopt the React Native platform SDK later when it can provide or cleanly bridge:

- the same MMKV token keys as `createAuthClient({ storagePrefix: PRODUCT_ID })`
- product-backend API client access with `x-product-id`, bearer token, and request ID propagation
- blob upload/download parity with `@bytelyst/blob-client`
- diagnostics metadata parity for app version, build number, release channel, install ID, and auth token access
- billing, feedback, broadcast, survey, feature flag, kill-switch, telemetry, and offline queue integration without duplicate initialization
- testable hooks/providers that fit the existing Expo Router auth bootstrap and root-layout gating flow

## Current Guardrails

- Keep using direct `@bytelyst/*` clients in mobile for this handoff.
- Do not introduce a second auth/token source.
- Do not add `@bytelyst/react-native-platform-sdk` as a mobile dependency until a migration plan removes redundant direct initialization.
- Revisit this decision after P2/P7 production-readiness gates and mobile offline/sync decisions are complete.