Mobile Client Architecture - GERCIA Care (Kotlin Multiplatform)

1. Architectural Strategy: Kotlin Multiplatform (KMP)

The mobile client (GERCIA Care, accessible via care.gercia.com.br) serves as the premier patient and clinician companion application across the Healthcare Verticals Ecosystem (Ecossistema de Verticais de Saúde). Tailored specifically for Classes A and B seeking personalized medicine, clinical aesthetics, and functional longevity, GERCIA Care operates a mission-critical Dual-Persona Architecture:

Patient Mode: Longitudinal electronic health records (EHR), interactive compounding quotation timelines, real-time prescription tracking, and continuous smartwatch health telemetry ingestion.
Clinician Companion Mode: On-the-go patient triage, instant clinical appointment management, AI copilot consultation summaries, and hardware-backed biometric Push-to-Sign authorization for electronic prescriptions issued from the desktop Angular web portal.

In accordance with ADR-009, the application is engineered with Kotlin Multiplatform (KMP) utilizing a Shared Kotlin Domain Engine coupled with 100% Native Declarative UIs: SwiftUI for iOS/watchOS and Jetpack Compose for Android.

flowchart TD
    subgraph UI_TIER ["Native Declarative UI Tier (100% Platform Fidelity)"]
        IOS_UI["<b>iOS & watchOS App (apps/mobile/ios)</b><br>• 100% Native SwiftUI & Combine<br>• LocalAuthentication / Face ID<br>• Apple HealthKit Native Client<br>• CryptoKit / Secure Enclave (P-256 ECC)"]
        AND_UI["<b>Android App (apps/mobile/android)</b><br>• 100% Jetpack Compose & Material 3<br>• BiometricPrompt API<br>• Health Connect Native Client<br>• StrongBox Keymaster Keystore"]
    end

    subgraph SHARED_KMP ["Shared Kotlin Multiplatform Engine (apps/mobile/shared)"]
        direction TB
        KMP_STATE["<b>State & Presentation Layer</b><br>• KMP ViewModels & StateFlow<br>• MVI Architecture Pattern<br>• Reactive Event Pipeline"]
        KMP_DOMAIN["<b>Domain Layer</b><br>• Health Longitudinal Telemetry Models<br>• Compounding Quotation Pipeline Rules<br>• Push-to-Sign Cryptographic Verification"]
        KMP_DATA["<b>Offline-First Data Layer</b><br>• SQLDelight / Room KMP (Encrypted SQLCipher)<br>• Ktor Client (HTTP/3, TLS 1.3, SSL Pinning)<br>• kotlinx.serialization (JSON)<br>• Token Vault (Secure Storage Delegation)"]
    end

    subgraph OS_SUBSYSTEMS ["Native OS Subsystems"]
        HK["Apple HealthKit / watchOS"]
        SE["Apple Secure Enclave (P-256 ECC)"]
        HC["Google Health Connect"]
        SB["Android StrongBox HSM"]
    end

    subgraph BACKEND ["Cloud Native Backend (GCP & Cloudflare)"]
        SERVER["api.gercia.com.br<br>(Cloud Run Minimal APIs)"]
        PUSH["Firebase Cloud Messaging (FCM)<br>& Apple Push Notification Service (APNs)"]
    end

    IOS_UI --> KMP_STATE
    AND_UI --> KMP_STATE
    KMP_STATE --> KMP_DOMAIN
    KMP_DOMAIN --> KMP_DATA

    IOS_UI -- "Native Health Telemetry" --> HK
    IOS_UI -- "Biometric HSM Signature" --> SE
    AND_UI -- "Native Health Telemetry" --> HC
    AND_UI -- "Biometric HSM Signature" --> SB

    KMP_DATA -- "HTTPS / TLS 1.3 Pinning" --> SERVER
    PUSH -- "High-Priority Silent Wakeup" --> IOS_UI
    PUSH -- "High-Priority Silent Wakeup" --> AND_UI

2. Shared Kotlin Multiplatform Engine (`apps/mobile/shared`)

The shared engine contains 100% of the platform-agnostic business logic, network orchestration, and encrypted offline storage, eliminating code duplication while avoiding UI rendering abstractions:

A. Reactive State & ViewModels

Utilizes the Model-View-Intent (MVI) architectural pattern powered by Kotlin Coroutines and StateFlow.
Exposes unidirectional state streams cleanly consumed by SwiftUI views via Swift AsyncSequence and by Jetpack Compose via collectAsStateWithLifecycle().

B. High-Performance Networking (`Ktor`)

Ktor Client configured with HTTP/3 and TLS 1.3 certificate pinning.
Implements automated JWT Refresh Token Rotation (RTR) against Gercia.Server (OpenIddict STS).
Resilient offline request queueing with exponential backoff.

C. Zero-Knowledge Offline Persistence (`SQLCipher`)

Local caching of clinical history, patient profiles, and compounding quotations leverages SQLDelight backed by SQLCipher (256-bit AES encryption-at-rest).
Encryption keys are derived dynamically from native hardware keychains (iOS Keychain / Android Keystore) and never written to plain storage.

3. Native Health Telemetry: HealthKit & Health Connect

Continuous biometric synchronization operates directly against official OS health subsystems with zero third-party plugin abstractions:

Health Telemetry Dimension	Apple HealthKit (`apps/mobile/ios`)	Android Health Connect (`apps/mobile/android`)
Vitals Sync Engine	Direct `HKHealthStore` background queries via `HKObserverQuery`	Official Jetpack `HealthConnectClient` with `WorkManager`
Monitored Metrics	Heart Rate, HRV (SDNN), Resting Heart Rate, SpO2, Blood Pressure, Sleep Stages, Continuous Glucose (CGM), Steps	Heart Rate, Sleep Stages, Blood Glucose, Blood Pressure, Oxygen Saturation, Distance, Steps
Background Execution	`BGAppRefreshTask` with background delivery enablement	`PeriodicWorkRequest` with battery-optimized constraints
Permissions Model	Native Apple HealthKit modal sheet	Native Android Health Connect permission manager

4. Hardware-Backed Push-to-Sign (`ICP-Brasil` Compliance)

For remote prescription authorization governed by CFM Res. 2.314/2022 and Lei 14.510/2022, GERCIA Care implements hardware-backed digital signatures anchored directly to physical hardware security modules (HSM):

sequenceDiagram
    autonumber
    participant Doctor as "Doctor (Desktop Web)"
    participant Server as "Gercia.Server (Cloud Run)"
    participant Push as "APNs / FCM Push"
    participant Mobile as "GERCIA Care (KMP App)"
    participant HSM as "Hardware Enclave (Secure Enclave / StrongBox)"

    Doctor->>Server: Issue Digital Prescription (Save & Authorize)
    Server->>Server: Calculate SHA-256 Digest of Document
    Server->>Push: Dispatch High-Priority Silent Wakeup Notification
    Push->>Mobile: Wake App in Clinician Companion Mode
    Mobile->>Mobile: Render Signature Prompt (Patient Name, Drug Summary, Hash)
    Doctor->>Mobile: Biometric Authorization (Face ID / Fingerprint)
    Mobile->>HSM: Request Sign with P-256 ECC Private Key
    HSM->>HSM: Verify Biometric Match (User Presence Check)
    HSM-->>Mobile: Cryptographic Signature Bytes
    Mobile->>Server: POST /prescriptions/push-to-sign/verify (Signature + Cert)
    Server->>Server: Verify Signature against Enrolled Public Key
    Server-->>Doctor: Prescription Signed & Sealed (ICP-Brasil Compliant)

Cryptographic Security Invariants

Apple Secure Enclave (iOS): Uses CryptoKit to generate a P-256 ECC keypair with kSecAccessControlBiometryAny. The private key is generated within the isolated hardware security enclave and can never be exported or read by software.
Android Keystore with StrongBox (Android): Uses KeyGenParameterSpec.Builder configured with PURPOSE_SIGN, requiring setUserAuthenticationRequired(true) via BiometricPrompt. Keys are isolated in hardware security modules (HSM) on devices supporting StrongBox.

5. Directory Structure (`apps/mobile/`)

apps/mobile/
 ├── shared/                       # Shared Kotlin Multiplatform Engine
 │    ├── build.gradle.kts         # KMP build configuration targeting iOS and Android
 │    └── src/
 │         ├── commonMain/         # Shared domain, MVI ViewModels, Ktor client, SQLDelight
 │         ├── androidMain/        # Android-specific bindings (Room/SQLCipher drivers)
 │         └── iosMain/            # iOS-specific bindings (Apple Keychain adapters)
 ├── ios/                          # 100% Native iOS & watchOS Client
 │    ├── GerciaCare.xcodeproj     # Xcode project (Swift 6 / SwiftUI)
 │    └── Sources/
 │         ├── Views/              # SwiftUI views (Patient Mode & Clinician Companion)
 │         ├── HealthKit/          # HKHealthStore native background telemetry synchronizer
 │         └── Security/           # CryptoKit & Secure Enclave hardware signature engine
 └── android/                      # 100% Native Android Client
      ├── build.gradle.kts         # Android Application module
      └── src/main/
           ├── kotlin/
           │    ├── ui/            # Jetpack Compose UI (Material Design 3)
           │    ├── health/        # Health Connect native synchronizer
           │    └── security/      # BiometricPrompt & Android Keystore signature engine
           └── AndroidManifest.xml # Health & biometric hardware permission manifests

Mobile Client Architecture - GERCIA Care (Kotlin Multiplatform)

1. Architectural Strategy: Kotlin Multiplatform (KMP)

2. Shared Kotlin Multiplatform Engine (apps/mobile/shared)

A. Reactive State & ViewModels

B. High-Performance Networking (Ktor)

C. Zero-Knowledge Offline Persistence (SQLCipher)