Mobile Architecture — React Native (Expo) Monorepo Integration¶

Status: Deferred (design complete, implement post-seed) Date: 2026-04-17 Session: 41 Decision: React Native with Expo, integrated into frontend monorepo

Decision: React Native (Expo) over SwiftUI or Flutter¶

Why not SwiftUI¶

• iOS only — Android would need a separate Kotlin/Jetpack Compose codebase
• Zero code sharing with existing React/TypeScript web apps
• No official Clerk Swift SDK — custom JWT handling needed
• Maintaining Swift + Kotlin + TypeScript = three languages for a solo developer
• SwiftUI's native performance advantage is irrelevant for a chat + document upload app

Why not Flutter¶

• Dart is a separate language — zero code sharing with TypeScript stack
• No official Clerk Flutter SDK
• Strong choice if starting from scratch, but Curaway has an existing React/TypeScript monorepo

Why React Native (Expo)¶

• Same language (TypeScript) as entire stack
• 40-60% code sharing with web apps via shared-core/
• Official @clerk/clerk-expo SDK
• Slots into monorepo as packages/mobile-patient/
• Expo EAS: cloud builds (no Xcode/Android Studio for most development), OTA JS updates without App Store review
• AI-assisted development (Claude Code, Cursor) works natively with TypeScript
• Near-native performance — uses real iOS UIKit and Android Views under the hood
• Single codebase → iOS + Android

When SwiftUI might revisit¶

If Curaway integrates Apple Health (patient vitals import) or Apple Wallet (appointment cards, boarding passes), a thin Swift native module handles those specific APIs. Expo supports native modules for this — the rest of the app stays React Native.

Monorepo Structure¶

frontend/
  packages/
    shared-core/           ← Types, API client, business logic (pure TypeScript)
    shared-web/            ← Web UI components (React + DOM)
    shared-native/         ← React Native UI components (future)
    patient-app/           ← curaway.ai (web)
    coordinator-app/       ← coordinator.curaway.ai (web)
    provider-app/          ← provider.curaway.ai (web, Phase 1)
    mobile-patient/        ← React Native Expo (this spec)
    mobile-coordinator/    ← React Native Expo (if field use warrants)

shared-core/ (platform-agnostic)¶

Pure TypeScript — no DOM, no React Native. Imports work on both web and native.

shared-web/ (web only)¶

React components using DOM elements (div, button, span). Used by patient-app, coordinator-app, provider-app.

shared-native/ (React Native only)¶

React Native equivalents of shared-web components. Created when mobile ships.

Migration path from today¶

Step 1: Initialize pnpm workspace in frontend/ (curaway-frontend/)
Step 2: Extract shared types + API client → packages/shared-core/
Step 3: Move patient app → packages/patient-app/
Step 4: Create packages/shared-web/ (extract reusable web components)
Step 5: Create packages/mobile-patient/ (Expo app)
Step 6: Create packages/shared-native/ (RN equivalents of shared-web)

Steps 1-4 are prerequisites (monorepo setup). Steps 5-6 are the mobile build.

Mobile Patient App — Feature Scope¶

P0 — Core experience (launch)¶

P1 — Enhanced (post-launch)¶

P2 — Extended¶

Technical Architecture¶

Expo configuration¶

{
  "expo": {
    "name": "Curaway",
    "slug": "curaway",
    "version": "1.0.0",
    "platforms": ["ios", "android"],
    "plugins": [
      "expo-camera",
      "expo-document-picker",
      "expo-notifications",
      "expo-local-authentication",
      "expo-secure-store"
    ]
  }
}

Auth flow¶

App launch
  → Check SecureStore for Clerk session token
  → Valid → Load case list
  → Expired/missing → Clerk sign-in screen (@clerk/clerk-expo)
  → Optional: biometric unlock (expo-local-authentication) for returning users

Chat architecture¶

Same API (POST /api/v1/cases/{id}/chat) as web. Differences:

Push notification setup¶

Registration:
  App launch → expo-notifications.getExpoPushTokenAsync()
  → POST /api/v1/devices/register { token, platform, device_id }
  → Stored in device_registrations table (existing)

Delivery:
  Backend event (booking_confirmed, driver_assigned, escalation)
  → Notification service checks patient preferences
  → Routes to push channel
  → Expo Push API → APNs/FCM → device

Offline support (P1)¶

expo-sqlite local database:
  ├── message_queue (unsent messages, queued when offline)
  ├── upload_queue (files selected offline, uploaded when connected)
  └── case_cache (last-fetched case data for offline viewing)

Sync strategy:
  - On reconnect: flush message_queue → API, flush upload_queue → R2
  - Conflict resolution: server wins (append-only chat model, no conflicts)
  - Cache invalidation: re-fetch case data on reconnect

Document upload flow¶

Patient taps camera icon
  → expo-camera opens (or expo-document-picker for existing files)
  → Image/PDF captured
  → Client-side validation (size, type — shared-core/validation)
  → POST /api/v1/uploads/presign → get presigned URL
  → Upload directly to R2 (same as web)
  → POST /api/v1/uploads/confirm → triggers OCR pipeline
  → SSE/polling for processing status
  → Rich card appears in chat with results

Development Workflow¶

Local development¶

cd packages/mobile-patient
npx expo start          # Expo dev server with hot reload
                        # Scan QR code with Expo Go app on device
                        # Or press 'i' for iOS simulator / 'a' for Android emulator

No Xcode or Android Studio needed for JS-only development. Only needed if adding native modules.

Cloud builds (EAS)¶

eas build --platform ios      # Cloud build for iOS (no Mac required for Android)
eas build --platform android  # Cloud build for Android
eas submit                    # Submit to App Store / Play Store

OTA updates¶

For JavaScript-only changes (no native module changes):

eas update --branch production    # Push JS update to all users
                                   # No App Store review needed
                                   # Users get update on next app open

This is powerful for: - Chat UI fixes - Rich card rendering updates - API client changes - Scoring display changes - Bug fixes in business logic

Native module changes (camera, notifications, biometrics) require a full App Store build.

Coordinator Mobile App¶

Priority: P2 — responsive web first. Native only if field coordinator use proves significant.

When to build: If coordinators at airports or hospitals need: - Quick booking confirmations on the go - Push alerts for escalations (faster than email/web) - Offline vendor contact lookup

Architecture: Same monorepo pattern — packages/mobile-coordinator/ imports shared-core/ + shared-native/.

Scope: Subset of coordinator-app — case queue, escalation alerts, quick booking actions. Not the full timeline manager or vendor directory.

Stakeholder Mobile Matrix¶

Estimated Effort¶

Prerequisites (monorepo setup — needed regardless of mobile)¶

Mobile build¶

Total: ~24-30 days (5-6 weeks)¶

Monorepo setup is a one-time cost that benefits all stakeholder apps.

Edge Cases¶

Flagsmith Flags¶

App Store Strategy¶

iOS (App Store)¶

• Category: Health & Fitness or Medical (coordination, not clinical)
• Privacy labels: Collects name, email, health records (with consent)
• App Tracking Transparency: Not required — no cross-app tracking (PostHog is first-party, UUID-only)
• Review considerations: Emphasize coordination platform, not medical advice. Include disclaimer.

Android (Play Store)¶

• Category: Health & Fitness
• Health data policy: Declare health data collection, point to privacy policy
• Data safety section: Encryption in transit + at rest, user can request deletion (GDPR cascade)

Both platforms¶

• Minimum viable store listing: Screenshots of chat, transport panel, progress view
• TestFlight / Internal Testing: SD + team test before public release
• Staged rollout: 10% → 50% → 100% on both platforms