From bea7579f60e80a3d3136c28a7c5b474ecd8e9ed5 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Tue, 5 May 2026 09:34:34 -0700 Subject: [PATCH] docs(mobile): defer react native platform sdk --- docs/MOBILE_DELEGATION_ROADMAP.md | 4 ++- docs/MOBILE_PLATFORM_SDK_DECISION.md | 40 ++++++++++++++++++++++++++++ docs/ROADMAP.md | 4 +-- docs/roadmaps/04_MOBILE_ROADMAP.md | 6 ++--- 4 files changed, 48 insertions(+), 6 deletions(-) create mode 100644 docs/MOBILE_PLATFORM_SDK_DECISION.md diff --git a/docs/MOBILE_DELEGATION_ROADMAP.md b/docs/MOBILE_DELEGATION_ROADMAP.md index 8df3600..de11fb2 100644 --- a/docs/MOBILE_DELEGATION_ROADMAP.md +++ b/docs/MOBILE_DELEGATION_ROADMAP.md @@ -88,7 +88,9 @@ Block I → Optional — @bytelyst/sync or deeper sync (last; needs API contra ### A.3 Optional (platform SDK parity) -If the team standardizes on **`@bytelyst/react-native-platform-sdk`**: either integrate **`AuthProvider`** with the **same MMKV keys** as `createAuthClient({ storagePrefix: PRODUCT_ID })`, or document a minimal bridge (same approach as NomGap Block A in `learning_ai_fastgap`). +Decision for this handoff: defer direct **`@bytelyst/react-native-platform-sdk`** adoption and keep mobile on direct shared `@bytelyst/*` clients. See [`MOBILE_PLATFORM_SDK_DECISION.md`](./MOBILE_PLATFORM_SDK_DECISION.md). + +If the team standardizes on the SDK later: either integrate **`AuthProvider`** with the **same MMKV keys** as `createAuthClient({ storagePrefix: PRODUCT_ID })`, or document a minimal bridge (same approach as NomGap Block A in `learning_ai_fastgap`). ### A.4 Done criteria diff --git a/docs/MOBILE_PLATFORM_SDK_DECISION.md b/docs/MOBILE_PLATFORM_SDK_DECISION.md new file mode 100644 index 0000000..7c4f517 --- /dev/null +++ b/docs/MOBILE_PLATFORM_SDK_DECISION.md @@ -0,0 +1,40 @@ +# 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. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 73f39a2..929cc48 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -481,7 +481,7 @@ Detailed implementation plans live under `docs/roadmaps/`. - SAS-based upload/download via platform-service blob endpoints - 2026-03-10 — QA / release hardening: - AGENTS.md and README.md created following ecosystem conventions -- 2026-03-11 — Mobile platform SDK integration (`878c644`): +- 2026-03-11 — Mobile direct shared-client integration (`878c644`): - Added @bytelyst/telemetry-client, feature-flag-client, kill-switch-client, blob-client to mobile deps - Created mobile/src/lib/platform.ts — centralized platform init (telemetry, flags, kill-switch, blob) - Refactored web blob-client.ts to use shared @bytelyst/blob-client (DRY) @@ -509,7 +509,7 @@ Detailed implementation plans live under `docs/roadmaps/`. - **Active lint blocker** — backend lint is missing `@eslint/js`, web lint has React compiler rule violations, and mobile lint has one unresolved shared billing-client import. Tracked by production-readiness P0.5, P4.3, P7.4, P8.1, and P8.5. - **Active runtime smoke gap** — platform-service, extraction-service, mcp-server, blob, telemetry, diagnostics, flags, kill switch, and NoteLett backend health need documented and automated smoke checks. Tracked by production-readiness P2.2-P2.4 and P8.4. - ~~**Blocker** — Product identity not finalized~~ **Resolved:** locked as NoteLett (`e1fde25`) -- ~~**Blocker** — `@bytelyst/react-native-platform-sdk` not wired~~ **Resolved:** platform.ts with telemetry, flags, kill-switch, blob (`878c644`) +- **Deferred** — `@bytelyst/react-native-platform-sdk` adoption is intentionally deferred for release handoff; mobile uses direct shared `@bytelyst/*` clients instead. See `docs/MOBILE_PLATFORM_SDK_DECISION.md`. - ~~**Deferred** — Blob-backed artifacts and upload/download flows~~ **Resolved:** SAS-based blob client (`196b210`) - ~~**Deferred** — Fully integrated approval/review/audit UX~~ **Resolved:** batch review, review notes, agent timeline across web + mobile (`ca3cdba`, `f8a4c18`) - ~~**Deferred** — Persisted saved views~~ **Resolved:** backend CRUD + web client + UI (`bdbf387`, `12d9009`) diff --git a/docs/roadmaps/04_MOBILE_ROADMAP.md b/docs/roadmaps/04_MOBILE_ROADMAP.md index 84e5b91..bc5b9f2 100644 --- a/docs/roadmaps/04_MOBILE_ROADMAP.md +++ b/docs/roadmaps/04_MOBILE_ROADMAP.md @@ -7,7 +7,7 @@ Stack: React Native + Expo + TypeScript # Phase M0 — Scaffold - [x] Create Expo app structure -- [ ] Wire `@bytelyst/react-native-platform-sdk` +- [ ] Defer direct `@bytelyst/react-native-platform-sdk` adoption until shared SDK parity is ready - [ ] Wire `@bytelyst/api-client` - [x] Wire `@bytelyst/platform-client` - [x] Wire `@bytelyst/offline-queue` @@ -103,8 +103,8 @@ Stack: React Native + Expo + TypeScript # Blockers -- `@bytelyst/react-native-platform-sdk` is referenced as a planned shared dependency, but the current workspace package does not appear ready for direct runtime consumption in this new app yet. -- Product identity and backend contract details remain provisional in the planning docs, so mobile config values are placeholders. +- `@bytelyst/react-native-platform-sdk` direct adoption is deferred for the production-readiness handoff; mobile currently uses direct shared `@bytelyst/*` clients. See [`../MOBILE_PLATFORM_SDK_DECISION.md`](../MOBILE_PLATFORM_SDK_DECISION.md). +- ~~Product identity and backend contract details remain provisional in the planning docs, so mobile config values are placeholders.~~ **Resolved:** NoteLett identity and backend URLs are now canonical. # Deferred