# Architectural Specification: GLP-1 Companion Platform **Document Version:** 1.0.0 **Target Runtimes:** iOS, Android, Web (Wasm/CanvasKit), macOS, Windows **Framework:** Flutter 3.x (Dart 3.x) **Security & Compliance Level:** HIPAA & GDPR-Ready Tier 1 Health Application --- ## 1. System Vision & Domain Boundaries The GLP-1 Companion is designed to address the clinical and behavioral realities of GLP-1/GIP receptor agonist pharmacotherapy (Semaglutide, Tirzepatide, Liraglutide). The architecture is structured around five core pillars: 1. **Pharmacokinetics & Dose Logistics:** Modeling dosage curves, biological half-lives, titrations, and physical injection site rotation. 2. **Lean Mass Preservation:** Monitoring protein intake targets and hydration volumes to mitigate muscle atrophy and kidney/GI adverse events. 3. **Recipe Scraping & Pantry Ingestion:** De-duplicating grocery overhead via automated microdata extraction and local inventory delta checks. 4. **Decoupled Biometric Ingestion:** Unifying OS-native health ecosystems (HealthKit, Health Connect) with cloud APIs (MyFitnessPal, Withings) across mobile, desktop, and web. 5. **Zero-Knowledge / High-Privacy Local Persistence:** End-to-end encrypted local databases (SQLCipher) paired with passwordless federated authentication. --- ## 2. Architectural Paradigm: Feature-First Clean Architecture The platform rejects monolithic and layered-by-technical-type layouts in favor of **Bounded Contexts (Feature-First Clean Architecture)**. Each business domain operates as an autonomous module. ```text lib/ ├── app/ # Top-level application bootstrap │ ├── app.dart # Multiplatform root widget │ ├── observers/ # Routing & state lifecycle observers │ └── router/ # GoRouter route declarations & redirect guards ├── core/ # Shared foundation & cross-cutting concerns │ ├── error/ # Failures, exceptions, and error boundary handlers │ ├── network/ # HTTP/REST clients, retry policies, TLS pinning │ ├── platform/ # Abstract hardware & OS platform wrappers │ ├── security/ # SQLCipher key generation, biometric locks, keychain │ ├── theme/ # Dynamic Material 3 & Apple Cupertino theme engines │ └── utils/ # DateTime calculations, pharmacokinetics math, formatters └── features/ # Modular business domains ├── auth/ # Passwordless, OAuth SSO, passkey integration ├── medication/ # Titration tracking, dose logging, injection rotation ├── nutrition/ # Micro/macro logs, protein density, hydration ├── recipes/ # Schema.org JSON-LD web scraper, recipe catalog ├── meal_planner/ # Weekly calendar, portion scaler ├── pantry/ # Food inventory, expiration date manager └── health_sync/ # HealthKit, Health Connect, MFP abstraction ``` ### Clean Architecture Layers per Feature Within each feature module in `lib/features//`, separation of concerns is strictly enforced: ```text / ├── domain/ # Pure Dart - ZERO external framework imports │ ├── entities/ # Immutable domain business objects │ ├── value_objects/ # Validated value types (e.g., DosageMg, ProteinTarget) │ ├── repositories/ # Abstract repository interfaces │ └── usecases/ # Isolated business operations (single responsibility) ├── data/ # Infrastructure & data persistence │ ├── datasources/ │ │ ├── local/ # Drift tables, secure key-value stores │ │ └── remote/ # Supabase REST, GraphQL, third-party APIs │ ├── models/ # Data Transfer Objects (DTOs), JSON serialization │ └── repositories/ # Concrete repository implementations └── presentation/ # UI & State management ├── controllers/ # Riverpod AsyncNotifiers / StateNotifiers ├── screens/ # Responsive top-level views └── widgets/ # Reusable components (Adaptive Dialogs, Pickers, Cards) ``` --- ## 3. Technology Stack & Multiplatform Dependencies | Capability | Selection | Rationale | |---|---|---| | **Core UI Framework** | Flutter 3.x (Dart 3.x) | Native AOT compilation on iOS, Android, macOS, and Windows; CanvasKit/Wasm rendering on Web. | | **State Management** | Riverpod 2.x (`riverpod_generator`) | Compile-time safe dependency injection, automatic provider disposal, testability without `BuildContext`. | | **Navigation & Deep Linking** | `go_router` 14.x | Declarative routing, browser URL synchronizer, deep linking for dose alerts and magic links. | | **Encrypted Database** | `drift` + `sqlcipher_flutter_libs` | Type-safe reactive SQLite interface with AES-256 transparent database encryption at rest. | | **Secure Vault** | `flutter_secure_storage` | OS-native credential storage: Apple Keychain, Android EncryptedSharedPreferences, Windows Credential Manager, Linux Secret Service. | | **Backend & Identity** | Supabase (PostgreSQL + RLS + GoTrue) | Built-in passwordless authentication, OAuth provider support, Row-Level Security, Edge Functions. | | **Recipe Scraping** | Dart `html` parser + Supabase Edge Node | Client-side parsing of `application/ld+json` Schema.org/Recipe with cloud fallback for bot-protected sites. | | **Platform Health Sync** | `health` package (Mobile) + OAuth REST (Web/Desktop) | Unified interface isolating native HealthKit/Health Connect from cross-platform desktop/web code. | | **Push Notifications** | `flutter_local_notifications` | Cross-platform offline-scheduled alerts for injections and hydration checks. | --- ### 4.7 Phase 3B: Platform Health Integrations & HealthGateway Architecture #### 4.7.1 System Overview The `HealthGateway` subsystem provides an abstracted, platform-agnostic bridge between application domains (Nutrition, Biometrics, Exercise) and external health telemetry ecosystems. It decouples high-level clinical metric analysis from platform-specific APIs (Apple HealthKit, Google Health Connect, Samsung Health) and external enterprise standards (SMART on FHIR), ensuring full cross-platform stability across iOS, Android, macOS, Windows, and Web. ```text ┌──────────────────────────────────┐ │ IHealthGateway (Core) │ └─────────────────┬────────────────┘ │ ┌─────────────────────────┬───────────────┴────────────────┬────────────────────────┐ │ (iOS / macOS) │ (Android) │ (Cloud / Enterprise) │ (Windows / Web) ▼ ▼ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ Apple HealthKit │ │ Health Connect │ │ SMART on FHIR │ │ Local Fallback │ │ - Weight (lbs) │ │ & Samsung Health│ │ OAuth2 / REST │ │ - Manual inputs │ │ - Active Energy │ │ - Weight (lbs) │ │ - HbA1c panels │ │ - Local SQLite │ │ - Blood Glucose │ │ - Active Burn │ │ - Lipid markers │ │ persistence │ └──────────────────┘ └──────────────────┘ └──────────────────┘ └──────────────────┘ ``` #### 4.7.2 Core Gateway Contracts & Data Payloads ```dart // lib/core/platform/health_gateway.dart import 'dart:io'; import 'package:flutter/foundation.dart'; enum HealthProviderType { appleHealth, healthConnect, samsungHealth, enterpriseFhir, manualFallback, } enum HealthConnectionStatus { notConfigured, permissionDenied, connected, unsupportedPlatform, } class HealthDataPayload { final double? weightLbs; final double? activeCaloriesToday; final double? bloodGlucoseMgDl; final DateTime timestamp; final HealthProviderType source; const HealthDataPayload({ this.weightLbs, this.activeCaloriesToday, this.bloodGlucoseMgDl, required this.timestamp, required this.source, }); } abstract class IHealthGateway { /// Verifies current OS entitlement and read permissions. Future checkStatus(HealthProviderType provider); /// Triggers native OS permission request prompt. Future requestAuthorization(HealthProviderType provider); /// Queries biometrics aggregated across the current calendar day. Future fetchLatestBiometrics(); /// Revokes active session bindings or tears down local connections. Future disconnect(HealthProviderType provider); } ``` #### 4.7.3 Platform Support & Fallback Strategy | Target Platform | Health Provider Bridge | Mechanism / Fallback | |---|---|---| | **iOS** | Apple HealthKit | Native `package:health` querying `HKQuantityTypeIdentifierBodyMass`, `HKQuantityTypeIdentifierActiveEnergyBurned`, `HKQuantityTypeIdentifierBloodGlucose`. | | **Android** | Health Connect | `androidx.health.connect.client` routing both Google Pixel and Samsung Health sensor feeds via Health Connect runtime. | | **Windows / macOS** | Local Mock / Manual DB Driver | Native SDKs bypassed via `kIsWeb || (!Platform.isIOS && !Platform.isAndroid)` compile-time and runtime guards. Biometrics route to local Drift SQLCipher storage without crash exceptions. | | **Web** | Web Storage Fallback | Direct Supabase cloud-synced biometrics and manual modal logging; SDK initialization omitted. | | **Enterprise Cloud** | SMART on FHIR | Headless OAuth2 code grant returning standardized HL7 FHIR `Observation` bundles (HbA1c, metabolic panels, weight). | #### 4.7.4 Native Entitlements & Manifest Configurations ##### Android (`android/app/src/main/AndroidManifest.xml`) ```xml ``` ##### iOS (`ios/Runner/Info.plist`) ```xml NSHealthShareUsageDescription GLP-1 Companion uses read-only HealthKit data to track lean body mass trends, active caloric expenditure, and glycemic markers alongside your dosing schedule. NSHealthUpdateUsageDescription GLP-1 Companion records weight and dose timings into Apple Health to keep clinical history synchronized. ``` #### 4.7.5 Security, Authorization & Key Management 1. **Zero Raw Token Exposure:** Enterprise SMART on FHIR refresh and access tokens are held exclusively in hardware-backed storage (`flutter_secure_storage` utilizing Android Keystore and Apple Keychain). 2. **Read-Only Minimal Principle:** Scopes requested from HealthKit and Health Connect are strictly restricted to read permissions for weight, blood glucose, and active burn to maximize user trust and prevent third-party telemetry leakage. 3. **Local Encryption at Rest:** Any synced telemetry data cached locally is stored inside the SQLCipher-encrypted SQLite database (`glp1_encrypted.db`), keyed by the hardware-derived master key managed by `CryptoManager`. ## 4. Multiplatform UX/UI Adaptation Engine The UI layer implements an **Adaptive Design Strategy** rather than a lowest common denominator approach: ```text ┌────────────────────────────────────┐ │ Platform Theme Director │ └─────────────────┬──────────────────┘ │ ┌───────────────────────┴───────────────────────┐ ▼ ▼ [Apple: iOS & macOS] [Material: Android, Web, Win] ┌─────────────────────────────────┐ ┌─────────────────────────────────┐ │ Cupertino Engine │ │ Material 3 Engine │ │ • CupertinoNavigationBar │ │ • NavigationRail / NavigationBar│ │ • CupertinoSliverRefreshControl │ │ • FloatingActionButtons │ │ • SF Pro System Typography │ │ • Roboto / Adaptive Font Scaler │ │ • Haptic Feedback & Swipe-Back │ │ • Dynamic Color / ColorScheme │ └─────────────────────────────────┘ └─────────────────────────────────┘ ``` ### Breakpoint Matrix - **Compact (< 600dp - Mobile):** Bottom `CupertinoTabBar` or `NavigationBar`. Full-screen sheets for dose logging. - **Medium (600dp - 1024dp - Foldables / Tablets):** Persistent navigation rail, split-view list/detail pane for recipe browsing and pantry audits. - **Expanded (> 1024dp - Desktop / Web):** Multi-column dashboard, persistent sidebar navigation rail, keyboard shortcuts (e.g., `Cmd/Ctrl + N` for quick food logging), modal popovers rather than full-screen sheets. --- ## 5. Security & Passwordless Authentication Architecture Password-based login is explicitly deprecated to eliminate credential-stuffing vectors and streamline onboarding. ```text User Device Supabase Auth Gateway OAuth Identity Provider │ │ │ ├─── Selects Provider ───────────┼───────────────────────────────────>│ (Apple / Google / MS) │ (Apple/Google/Microsoft) │ │ │<── Returns Auth Token/Nonce ───┼────────────────────────────────────┤ │ │ │ ├─── Exchange Nonce / Verify ───>│ │ │<── Issue JWT + Refresh Token ──┤ │ │ │ │ │─── Or Request Magic Link ─────>│ │ │ (Email OTP / Deep Link) ├───── Dispatches Secure Link ──────>│ (User Email Box) │<── Deep Link Activated ────────┤ │ │ │ │ └─── Store Session in Keychain ──┴────────────────────────────────────┘ ``` ### Zero-Knowledge Local Storage Scheme Local encryption relies on a three-tier lifecycle: 1. On initial app bootstrap, a cryptographic salt and 256-bit AES master key are generated via `core/security/crypto_manager.dart`. 2. The master key is committed directly to the platform hardware vault. 3. The SQLCipher SQLite instance initializes using this hardware-backed key. Platform vault targets: - **iOS / macOS:** Apple Keychain Services (`kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`) - **Android:** Android KeyStore backing `EncryptedSharedPreferences` (AES-256 GCM) - **Windows:** Windows Data Protection API (DPAPI / Credential Manager) - **Web:** Ephemeral in-memory key unlocked by biometric WebAuthn / session credentials SQLCipher database initialization parameters: ```sql PRAGMA key = 'x2C5D8F91B4E6A30C8D7E1F2A5B8C0D3E...'; PRAGMA cipher_page_size = 4096; PRAGMA kdf_iter = 256000; PRAGMA cipher_hmac_algorithm = HMAC_SHA512; ``` --- ## 6. Pharmacokinetics & GLP-1 Tracking Engine The `medication` feature models drug serum concentration to deliver realistic physiological insights rather than simple calendar alarms. ### Half-Life Modeling Formulation Active serum levels are calculated using standard single-compartment open pharmacokinetic decay curves: $$C(t) = \sum_{i=1}^{n} D_i \cdot \left(\frac{1}{2}\right)^{\frac{t - t_i}{t_{1/2}}}$$ Where: - $D_i$ = Dose administered at timestamp $t_i$ (mg) - $t_{1/2}$ = Elimination half-life of compound: - **Semaglutide (Ozempic / Wegovy):** $\approx 168\text{ hours (7 days)}$ - **Tirzepatide (Mounjaro / Zepbound):** $\approx 120\text{ hours (5 days)}$ - **Liraglutide (Saxenda):** $\approx 13\text{ hours}$ - $t$ = Current evaluation timestamp ### Injection Site Rotation Matrix To prevent lipohypertrophy, injection events map to a 12-quadrant anatomical topological matrix: - **Abdomen:** Right Upper, Right Lower, Left Upper, Left Lower - **Thighs:** Right Anterior/Lateral, Left Anterior/Lateral - **Upper Arms:** Right Tricep/Lateral, Left Tricep/Lateral Rotation alerts automatically flag and suggest the least recently utilized site. --- ## 7. Recipe Parsing & Smart Pantry Delta Engine ```text ┌────────────────────────────────────────────────────────┐ │ Web Scraping Pipeline (Recipes) │ └───────────────────────────┬────────────────────────────┘ │ 1. Fetch HTML Document ───────┴───────> 2. Query