# Frontend Framework Research: Mobile-First Approach

**Date**: 2026-02-14
**Focus**: Mobile-first health platform with web companion app

---

## Platform Strategy Clarification

### Primary Platform: Mobile Apps (iOS & Android)
- **Main interaction**: Quick data entry, sensor integration, daily health tracking
- **Health sensors**: Apple HealthKit, Google Health Connect
- **Use cases**:
  - Quick health data entry (weight, steps, mood)
  - Medication reminders and tracking
  - QR code scanning (lab results)
  - Real-time health sensor data (steps, heart rate, sleep)
  - Push notifications for reminders
  - Background sync with server
  - "Nuke option" (instant data deletion)

### Secondary Platform: Web Browser
- **Complementary role**: Extensive reporting, visualization, profile management
- **Use cases**:
  - Complex data visualization and charts
  - Historical trend analysis
  - Comprehensive profile management
  - Family structure management
  - Extensive reporting and data export
  - Detailed configuration settings
  - Desktop/laptop user preference

---

## Mobile Development Options

### 1. React Native
**Description**: Facebook's cross-platform framework using React/JavaScript

**Pros for Normogen**:
- **Code sharing**: Share logic with web frontend (React)
- **Large ecosystem**: Extensive library ecosystem
- **Health integration**: 
  - React Native Health (Apple HealthKit)
  - Google Health Connect integration
- **QR code scanning**: react-native-camera, react-native-qrcode-scanner
- **Encryption**: Native crypto libraries available
- **Community**: Largest cross-platform mobile community
- **Performance**: Good enough for health data apps

**Cons**:
- Performance overhead compared to native
- Larger app bundle size
- Potential dependency issues (npm chaos)
- JavaScript engine overhead

**Health Sensor Integration**:
- iOS: [react-native-health](https://github.com/anthonyecamps/react-native-health)
- Android: [react-native-google-fit](https://github.com/StasDoskalenko/react-native-google-fit)
- Background location/sensors: [react-native-background-job](https://github.com/jamesisaac/react-native-background-job)

**Code Sharing Potential**:
- Business logic: 70-80% shared with web
- State management: 90%+ shared
- API client: 100% shared
- Encryption: 100% shared
- UI components: 0% (separate native UI)

---

### 2. Flutter
**Description**: Google's cross-platform framework using Dart

**Pros for Normogen**:
- **Excellent performance**: Compiled to native ARM64
- **Small app bundle**: Smaller than React Native
- **Hot reload**: Fast development iteration
- **Health integration**:
  - health (Apple HealthKit, Google Health Connect)
  - Provides unified API for both platforms
- **Beautiful UI**: Material Design and Cupertino widgets
- **Stable**: Mature and production-ready
- **Single codebase**: Better platform parity

**Cons**:
- **No code sharing** with web frontend
- Dart learning curve (if team only knows JavaScript)
- Smaller ecosystem than React Native
- Less flexibility for native modules

**Health Sensor Integration**:
- [health](https://pub.dev/packages/health) - Apple HealthKit + Google Health Connect
- Unified API for both platforms
- Background task support
- Step counting, heart rate, sleep tracking

**Code Sharing Potential**:
- Business logic: 0% (Dart vs JavaScript)
- API client: 0% (must rewrite)
- Encryption: 0% (must rewrite)
- UI components: 0% (separate UI framework)

---

### 3. Native (Swift + Kotlin)
**Description**: Separate native apps for iOS and Android

**Pros for Normogen**:
- **Best performance**: Native ARM64 code
- **Best sensor integration**: Direct platform APIs
- **Best user experience**: Platform-native feel
- **Smallest app bundle**: No framework overhead
- **Swift**: Native crypto libraries (CryptoKit)
- **Kotlin**: Native crypto libraries

**Cons**:
- **Double development cost**: Separate codebases
- **No code sharing**: 0% code sharing between platforms
- **Longer time to market**: Two separate implementations
- **Higher maintenance**: Two codebases to maintain
- **Team skill requirements**: Swift + Kotlin + JavaScript (for web)

**Health Sensor Integration**:
- iOS: HealthKit (native, best integration)
- Android: Google Health Connect (native)
- Background tasks: Native support

**Code Sharing Potential**:
- Business logic: 0% (different languages)
- API client: 0% (must implement twice)
- Encryption: 0% (different crypto libraries)
- UI components: 0% (completely separate)

---

### 4. Progressive Web App (PWA)
**Description**: Web app that can be installed on mobile devices

**Pros for Normogen**:
- **Single codebase**: Works on mobile and desktop
- **Health sensors**: Web Bluetooth, Generic Sensor API (limited)
- **No app store**: Direct deployment, instant updates
- **Small bundle**: Just web assets
- **Easy updates**: No app store review process

**Cons**:
- **Limited sensor access**: Cannot access HealthKit/Health Connect
- **Poor offline**: Limited background sync
- **Poor push notifications**: Limited support
- **iOS limitations**: Safari PWA restrictions
- **Poor user experience**: Not native-feeling

**Health Sensor Integration**:
- Limited to web sensor APIs
- No HealthKit integration
- No Health Connect integration
- Poor for health sensor use case

**Code Sharing Potential**:
- Business logic: 100% shared
- API client: 100% shared
- Encryption: 100% shared
- UI: 100% shared

**Verdict**: Not suitable for Normogen's mobile sensor requirements

---

## Web Companion Framework Options

### Option 1: React (if mobile is React Native)
**Description**: Most popular JavaScript UI library

**Pros**:
- **Code sharing**: 70-80% with React Native
- **Ecosystem**: Largest npm ecosystem
- **Charts**: Chart.js, Recharts, D3.js
- **State management**: Redux, Zustand, Jotai
- **Encryption**: Web Crypto API, crypto-js

**Cons**:
- Large bundle size
- Complexity for simple apps

---

### Option 2: Svelte/SvelteKit
**Description**: Modern compiler-based framework

**Pros**:
- **Small bundle**: Compiled, minimal runtime
- **Great DX**: Simple, clean syntax
- **Charts**: Svelte-chartjs, Plotly
- **Performance**: Excellent for charts/visualization
- **SSR**: Built-in server-side rendering

**Cons**:
- **No code sharing** with React Native
- Smaller ecosystem
- Less mature than React

---

### Option 3: Vue.js
**Description**: Progressive JavaScript framework

**Pros**:
- **Simple learning curve**: Easier than React
- **Charts**: Chart.js, ECharts
- **Performance**: Good for visualizations
- **Ecosystem**: Growing but smaller than React

**Cons**:
- **No code sharing** with React Native
- Smaller ecosystem than React
- Less job market demand

---

## Comparison Matrix

| Criteria | React Native + React | Flutter + React/Svelte | Native + React |
|----------|---------------------|------------------------|----------------|
| **Development Cost** | Low (code sharing) | Medium | High (2x platforms) |
| **Time to Market** | Fast | Medium | Slow |
| **Mobile Performance** | Good | Excellent | Excellent |
| **Web Performance** | Good | Good | Good |
| **Code Sharing** | 70-80% | 0% | 0% |
| **Health Sensors** | ✅ Excellent | ✅ Excellent | ✅ Excellent |
| **QR Scanning** | ✅ Excellent | ✅ Excellent | ✅ Excellent |
| **Crypto** | ✅ Excellent | ✅ Good | ✅ Excellent |
| **Bundle Size** | Medium | Small | Small |
| **Maintenance** | Medium | Medium | High |
| **Team Skills** | JavaScript only | Dart + JS | Swift + Kotlin + JS |
| **Ecosystem** | Largest | Large | Native |

---

## Research Questions

### For Mobile Framework

1. **Health Sensor Integration Quality**
   - How well does each framework integrate with HealthKit?
   - How well does each framework integrate with Google Health Connect?
   - Background sensor data collection?
   - Step counting, heart rate, sleep tracking support?

2. **QR Code Scanning**
   - Camera API integration quality
   - QR scanning library availability
   - Performance and accuracy

3. **Encryption Capabilities**
   - Client-side AES-256-GCM encryption
   - PBKDF2 key derivation
   - Web Crypto API bridging (for code sharing)
   - Secure key storage (Keychain/Keystore)

4. **Background Sync**
   - Background task scheduling
   - Sync reliability
   - Battery efficiency
   - Data transfer optimization

5. **Push Notifications**
   - Local notifications (reminders)
   - Push notifications (server-triggered)
   - Scheduling accuracy

### For Web Framework

1. **Chart Visualization**
   - Chart library compatibility
   - Performance with large datasets
   - Real-time data streaming
   - Beautiful, interactive charts

2. **Encrypted Data Handling**
   - Client-side decryption
   - Large encrypted data handling (10MB+)
   - Streaming response support
   - Zero-knowledge architecture support

3. **Complex State Management**
   - Family structure management
   - Multi-person profiles
   - Access control and permissions
   - Offline data synchronization

4. **Performance**
   - Bundle size and load time
   - Rendering performance for complex charts
   - Memory usage for large datasets

---

## Health Sensor Integration Deep Dive

### Apple HealthKit

**Data Types to Integrate**:
- Steps (count, distance)
- Heart rate (resting, walking, variability)
- Sleep analysis (duration, quality, stages)
- Weight, height, BMI
- Blood pressure
- Temperature
- Oxygen saturation
- Respiratory rate
- Menstrual cycle data
- Workouts and activity
- Nutrition (water, caffeine)

**Integration Requirements**:
- Authorization request handling
- Background delivery (HKHealthStore)
- Query historical data
- Write data to HealthKit (if needed)
- Sample queries (filtered by date, type)

### Google Health Connect

**Data Types to Integrate**:
- Steps (count, distance)
- Heart rate (resting, variability)
- Sleep (sessions, stages)
- Weight, height
- Blood pressure
- Temperature
- Oxygen saturation
- Nutrition
- Menstrual cycle
- Exercise sessions

**Integration Requirements**:
- Permission request handling
- Background reading (WorkManager)
- Historical data queries
- Write data to Health Connect (if needed)

---

## Recommended Architecture

### Mobile-First, Web-Complementary

#### Recommended Stack: **React Native + React**

**Rationale**:

1. **Code Sharing (70-80%)**
   - Business logic: User management, data sync, encryption
   - State management: Redux/Zustand store
   - API client: Axios/Fetch wrapper
   - Encryption utilities: AES-GCM, PBKDF2, keys
   - Data validation: Zod schemas
   - Date handling: date-fns, luxon

2. **Health Sensors**
   - React Native Health (iOS)
   - React Native Google Fit (Android)
   - Background task support
   - Excellent sensor integration

3. **QR Scanning**
   - react-native-camera
   - Fast, accurate scanning

4. **Encryption**
   - react-native-quick-crypto
   - Secure key storage (Keychain/Keystore)
   - Web Crypto API compatible

5. **Web Charts**
   - Recharts (React)
   - D3.js (if needed)
   - Chart.js (simple charts)
   - Excellent visualization

6. **Team Skills**
   - Single language: JavaScript/TypeScript
   - Single ecosystem: npm
   - Lower hiring cost

#### Architecture Diagram

```
┌─────────────────────────────────────────────────────┐
│                   Shared Layer                       │
│  (Business Logic, State, API, Encryption)           │
│                                                     │
│  - Redux/Zustand Store                              │
│  - API Client (Axios)                               │
│  - Encryption Utilities (AES-GCM, PBKDF2)            │
│  - Data Validation (Zod)                            │
│  - Date Handling (date-fns)                          │
└─────────────────────────────────────────────────────┘
                        │
        ┌───────────────┴───────────────┐
        │                               │
        ▼                               ▼
┌──────────────────┐         ┌──────────────────┐
│  React Native    │         │  React (Web)      │
│  (Mobile)        │         │  (Companion)     │
│                  │         │                  │
│  - Native UI     │         │  - DOM UI        │
│  - Camera       │         │  - Charts        │
│  - HealthKit    │         │  - Tables        │
│  - Health Conn. │         │  - Forms         │
│  - Push Notif.  │         │  - Settings UI   │
│  - Background  │         │                  │
└──────────────────┘         └──────────────────┘
        │                               │
        │                               │
        ▼                               ▼
┌──────────────────┐         ┌──────────────────┐
│  iOS App         │         │  Browser         │
│  (App Store)     │         │  (Web)           │
└──────────────────┘         └──────────────────┘
┌──────────────────┐
│  Android App     │
│  (Play Store)    │
└──────────────────┘
```

---

## Proof of Concept Requirements

### Mobile POC

1. **Health Sensor Integration**
   - Read steps from HealthKit (iOS)
   - Read steps from Health Connect (Android)
   - Display last 7 days of step data
   - Sync with backend API

2. **Encryption Test**
   - Encrypt health data on device
   - Send to backend
   - Decrypt on device
   - Verify zero-knowledge (backend stores encrypted)

3. **QR Scanning**
   - Scan QR code
   - Parse lab result data
   - Encrypt and sync

4. **Background Sync**
   - Sync every 5 minutes
   - Handle offline mode
   - Conflict resolution

### Web POC

1. **Chart Visualization**
   - Display 30 days of health data
   - Line chart (weight trends)
   - Bar chart (steps per day)
   - Responsive design

2. **Profile Management**
   - Create/edit profile
   - Add family members
   - Set permissions

3. **Encrypted Data Handling**
   - Load 10MB encrypted data
   - Decrypt and display
   - Stream large datasets

---

## Implementation Timeline

### Phase 1: Mobile MVP (8-12 weeks)
- [ ] Setup React Native project
- [ ] Integrate HealthKit (iOS)
- [ ] Integrate Health Connect (Android)
- [ ] Implement encryption utilities
- [ ] Build API client
- [ ] Implement authentication
- [ ] Build core UI (profile, data entry, sync)
- [ ] Test QR scanning
- [ ] Implement background sync

### Phase 2: Web Companion (4-6 weeks)
- [ ] Setup React project
- [ ] Share business logic from mobile
- [ ] Build chart visualization
- [ ] Build profile management UI
- [ ] Build family structure UI
- [ ] Build reporting interface

### Phase 3: Polish & Launch (4-6 weeks)
- [ ] Performance optimization
- [ ] Security audit
- [ ] App store submission
- [ ] Marketing materials
- [ ] User testing
- [ ] Beta launch

---

## Alternative Considered: Flutter

### Why Flutter is a strong alternative

**Pros**:
- Excellent performance (compiled to native)
- Beautiful UI out of the box
- Unified health package (HealthKit + Health Connect)
- Small app bundle size
- Fast development (hot reload)

**Why React Native wins for Normogen**:

1. **Code Sharing (Critical Advantage)**
   - 70-80% code sharing vs 0%
   - Faster time to market
   - Lower development cost
   - Easier maintenance

2. **Team Skills**
   - Single language (JavaScript/TypeScript)
   - Single ecosystem (npm)
   - Lower hiring cost
   - Faster onboarding

3. **Ecosystem Maturity**
   - React Native: More mature, larger community
   - Better health sensor integration
   - More third-party libraries
   - More production experience

4. **Web Companion**
   - React for web companion (code sharing)
   - Flutter web: Less mature, not recommended

**Flutter would be better if**:
- Web companion was not needed
- Team had Dart experience
- Performance was critical (not the case for health app)
- UI polish was the top priority

---

## Final Recommendation

### Primary Recommendation: **React Native + React**

**Score**: 9/10

**Justification**:

1. **Code Sharing** (Critical)
   - 70-80% shared between mobile and web
   - Single language (JavaScript/TypeScript)
   - Faster development, easier maintenance

2. **Health Sensors** (Excellent)
   - React Native Health (iOS HealthKit)
   - React Native Google Fit (Android Health Connect)
   - Background sensor data collection
   - Comprehensive health data support

3. **Encryption** (Excellent)
   - react-native-quick-crypto
   - Web Crypto API compatible
   - Secure key storage (Keychain/Keystore)

4. **QR Scanning** (Excellent)
   - react-native-camera
   - Fast, accurate scanning

5. **Web Charts** (Excellent)
   - Recharts (React)
   - Beautiful, interactive visualizations
   - Great for health data

6. **Team & Cost** (Excellent)
   - Single language (JS/TS)
   - Single ecosystem (npm)
   - Lower development cost
   - Faster time to market

### Risk Assessment

**Risk: React Native Performance**
- **Severity**: Low
- **Mitigation**: Good enough for health data apps
- **Mitigation**: Performance optimization techniques
- **Mitigation**: Native modules for critical paths

**Risk: JavaScript Engine Overhead**
- **Severity**: Low
- **Mitigation**: Hermes engine (faster, smaller)
- **Mitigation**: Modern phones are fast enough

**Risk: Dependency Issues**
- **Severity**: Medium
- **Mitigation**: Careful dependency management
- **Mitigation**: Use stable, well-maintained libraries
- **Mitigation**: Monorepo for better control

---

## Next Steps

1. ✅ **Mobile Framework Selected**: React Native
2. ⏭️ **Select State Management**: Redux vs Zustand vs Jotai
3. ⏭️ **Select Navigation**: React Navigation vs React Native Navigation
4. ⏭️ **Select Charts**: Recharts vs Chart.js
5. ⏭️ **Design Database Schema**: MongoDB collections
6. ⏭️ **Create POC**: Health sensor integration test
7. ⏭️ **Implement Authentication**: JWT + recovery phrase

---

## Technology Stack Summary

### Mobile
- **Framework**: React Native 0.73+
- **Language**: TypeScript
- **State Management**: TBD (Redux/Zustand)
- **Navigation**: React Navigation
- **Health Sensors**: 
  - react-native-health (iOS)
  - react-native-google-fit (Android)
- **QR Scanning**: react-native-camera
- **Encryption**: react-native-quick-crypto
- **HTTP**: Axios
- **Date**: date-fns

### Web
- **Framework**: React 18+
- **Language**: TypeScript
- **State Management**: TBD (Redux/Zustand)
- **Routing**: React Router
- **Charts**: Recharts
- **HTTP**: Axios
- **Date**: date-fns
- **UI**: Tailwind CSS / Chakra UI

### Shared
- **Language**: TypeScript
- **State Management**: Redux/Zustand
- **API Client**: Axios
- **Encryption**: AES-256-GCM, PBKDF2
- **Validation**: Zod
- **Date**: date-fns
- **Utilities**: Shared monorepo package

---

## Conclusion

**React Native + React** is the optimal choice for Normogen's mobile-first, web-complementary architecture:

- **70-80% code sharing** between mobile and web
- **Excellent health sensor integration** (HealthKit + Health Connect)
- **Single language** (JavaScript/TypeScript) reduces development cost
- **Great chart visualization** for web companion
- **Proven at scale** in health apps
- **Faster time to market** than native or Flutter

**Decision**: Use **React Native** for mobile (iOS + Android) and **React** for web companion app.

---

## References

- [React Native](https://reactnative.dev/)
- [React Native Health](https://github.com/anthonyecamps/react-native-health)
- [React Native Google Fit](https://github.com/StasDoskalenko/react-native-google-fit)
- [React Native Quick Crypto](https://github.com/margelo/react-native-quick-crypto)
- [React Native Camera](https://github.com/react-native-camera/react-native-camera)
- [Recharts](https://recharts.org/)
- [HealthKit Documentation](https://developer.apple.com/documentation/healthkit)
- [Google Health Connect](https://developer.android.com/health-and-fitness/google/health-connect)