Initial commit: Project setup and documentation

- Initialize Normogen health tracking platform - Add comprehensive project documentation - Add zero-knowledge encryption implementation guide - Set up .gitignore for Rust/Node.js/mobile development - Create README with project overview and roadmap Project is currently in planning phase with no implementation code yet.
2026-02-14 11:11:06 -03:00 · 2026-02-14 11:11:06 -03:00 · e72602d784
commit e72602d784
10 changed files with 3407 additions and 0 deletions
--- a/thoughts/research/2026-01-05-mobile-health-frameworks-data.md
+++ b/thoughts/research/2026-01-05-mobile-health-frameworks-data.md
@ -0,0 +1,635 @@
+---
+date: 2026-01-05T20:27:17-03:00
+git_commit: N/A (not a git repository)
+branch: N/A
+repository: normogen
+topic: "Mobile Health Frameworks - Available Data Types"
+tags: [research, healthkit, health-connect, mobile-integration, data-types]
+status: complete
+---
+
+# Research: Mobile Health Frameworks Data Availability
+
+## Research Question
+What health data can be accessed from mobile phone health frameworks (Apple HealthKit and Google Health Connect) with proper application permissions?
+
+## Summary
+
+**Key Finding:** Both iOS and Android provide comprehensive access to health data through their respective frameworks (HealthKit and Health Connect). With proper permissions, applications can access **50+ different health data types** including body measurements, vitals, activity, sleep, nutrition, and reproductive health.
+
+**Platform Coverage:**
+- **Apple HealthKit (iOS):** 9 major categories, 50+ data types
+- **Google Health Connect (Android):** 8 major categories, 45+ data types
+- **Common to Both:** ~15 core data types with overlap
+
+**User Control:** Both platforms require explicit user permission for each data category, with granular controls and easy revocation.
+
+---
+
+## Apple HealthKit (iOS)
+
+### Data Categories Available
+
+#### 1. Body Measurements
+With basic permissions:
+- **Weight** - kg, lbs
+- **Height** - cm, in, ft
+- **Body Mass Index (BMI)** - calculated
+- **Body Fat Percentage** - %age
+- **Lean Body Mass** - kg, lbs
+
+#### 2. Vitals (Requires Special Permissions)
+- **Heart Rate** - beats per minute (BPM)
+- **Resting Heart Rate** - BPM
+- **Blood Pressure** - systolic/diastolic (mmHg)
+- **Body Temperature** - °C, °F
+- **Respiratory Rate** - breaths per minute
+- **Oxygen Saturation (SpO2)** - percentage
+- **Blood Glucose** - mg/dL, mmol/L
+
+#### 3. Fitness & Activity
+- **Step Count** - daily/total steps
+- **Distance Walking/Running** - km, mi
+- **Flights Climbed** - count
+- **Active Energy Burned** - kcal
+- **Basal Energy Burned** - kcal/day
+- **Exercise Duration** - minutes/hours
+- **Workouts** - type, duration, calories, route
+
+#### 4. Sleep Analysis
+- **Sleep Duration** - total time asleep
+- **Time in Bed** - total time in bed
+- **Sleep Stages** - in bed, asleep, awake
+- **Sleep Quality** - REM, light, deep sleep
+
+#### 5. Mobility
+- **Walking Speed** - m/s
+- **Walking Asymmetry** - percentage
+- **Walking Steadiness** - score
+- **Step Length** - cm, in
+
+#### 6. Nutrition
+- **Dietary Energy** - calories
+- **Macronutrients** - carbs, protein, fat (total, saturated, unsaturated)
+- **Fiber** - grams
+- **Sugar** - grams
+- **Sodium** - milligrams
+- **Water Intake** - liters, cups, ounces
+- **Vitamins & Minerals** - various (A, C, D, iron, calcium, etc.)
+
+#### 7. Reproductive Health
+- **Menstrual Flow** - light, medium, heavy
+- **Basal Body Temperature** - °C, °F
+- **Cervical Mucus Quality** - type and amount
+- **Ovulation Test Result** - positive/negative
+- **Sexual Activity** - protected/unprotected
+- **Spotting** - yes/no
+
+#### 8. Medical Records & Labs (Clinical Data)
+- **Allergy Records** - allergen, severity, reaction
+- **Condition Records** - diagnosis, status
+- **Immunization Records** - vaccine, date
+- **Lab Result Records** - test name, result, unit, reference range
+- **Medication Records** - name, dosage, frequency
+- **Procedure Records** - procedure, date, outcome
+- **Vital Signs Records** - clinical measurements
+
+#### 9. Apple Watch Specific Data
+- **ECG Results** - ECG readings and classifications
+- **AFib Detection** - atrial fibrillation notifications
+- **Fall Detection** - fall events
+- **Noise Levels** - environmental sound exposure
+- **Headphone Audio Levels** - audio exposure
+
+### Permission Requirements
+
+**Info.plist Required Entries:**
+```xml
+<key>NSHealthShareUsageDescription</key>
+<string>We need access to your health data to track and analyze your wellness metrics.</string>
+
+<key>NSHealthUpdateUsageDescription</key>
+<string>We need permission to save health data to your Health app.</string>
+```
+
+**Entitlements Required:**
+- HealthKit capability in Xcode project settings
+- Special entitlements for clinical data access
+
+**User Permissions:**
+- User must explicitly grant permission for each data category
+- Prompts shown at first access to each category
+- User can revoke permissions in Settings > Health > Data Access & Devices
+- Clinical data requires additional user consent
+
+**Metadata Available:**
+- **Timestamp:** Start and end time (millisecond precision)
+- **Device:** Source device (iPhone, Apple Watch, third-party app)
+- **Units:** Always included with proper conversions
+- **Provenance:** Which app/device provided the data
+- **Accuracy:** For sensor-based measurements
+- **User Notes:** Optional user-created annotations
+
+---
+
+## Google Health Connect (Android)
+
+### Data Types Available
+
+#### 1. Activity & Exercise
+- **Steps** - count
+- **Distance** - meters, kilometers, miles
+- **Floors** - count
+- **Elevation** - meters, feet
+- **Exercise Sessions** - type (running, walking, cycling, etc.), duration, calories
+- **Swimming** - strokes, laps, distance
+- **Wheelchair Pushes** - count
+- **Golf Swings** - count (for supported apps)
+
+#### 2. Body Measurements
+- **Weight** - kg, lbs
+- **Height** - meters, centimeters, feet, inches
+- **Body Fat** - percentage
+- **Basal Metabolic Rate** - kcal/day
+- **Body Water Mass** - kg
+- **Bone Mass** - kg
+- **Lean Body Mass** - kg
+
+#### 3. Vitals
+- **Heart Rate** - BPM
+- **Resting Heart Rate** - BPM
+- **Heart Rate Variability** - milliseconds
+- **Blood Pressure** - systolic/diastolic in mmHg
+- **Oxygen Saturation (SpO2)** - percentage
+- **Body Temperature** - °C, °F
+- **Respiratory Rate** - breaths/minute
+
+#### 4. Sleep
+- **Sleep Sessions** - start time, end time, total duration
+- **Sleep Stages** - awake, REM, light, deep sleep with durations
+- **Sleep Latency** - time to fall asleep
+
+#### 5. Nutrition
+- **Hydration** - volume in mL, oz, cups
+- **Nutrition** - calories, macronutrients, micronutrients
+- **Meal Information** - meal type (breakfast, lunch, dinner, snack)
+
+#### 6. Cycle Tracking
+- **Menstruation Flow** - flow amount and type
+- **Menstruation Period** - start and end dates
+- **Ovulation** - positive, negative, test result
+- **Cervical Mucus** - type and quantity
+- **Sexual Activity** - protection status
+- **Spotting** - yes/no
+
+#### 7. Clinical Data
+- **Blood Glucose** - mg/dL, mmol/L
+- **Lab Test Results** - similar to Apple HealthKit
+
+#### 8. Physical Activity Details
+- **Exercise Type** - running, walking, cycling, swimming, etc.
+- **Exercise Duration** - time in minutes/hours
+- **Exercise Calories** - kcal burned
+- **Exercise Route** - GPS data path (if available)
+
+### Permission Requirements
+
+**AndroidManifest.xml:**
+```xml
+<uses-permission android:name="android.permission.health.READ_HEALTH_DATA" />
+<uses-permission android:name="android.permission.health.WRITE_HEALTH_DATA" />
+```
+
+**Runtime Permissions:**
+- Granular permission requests per data type
+- User approves each category individually
+- Health Connect app must be installed on device
+- User can manage permissions in Health Connect app
+
+**Requirements:**
+- Android API level 34+ (Android 14) recommended
+- Health Connect Jetpack library
+- Google Play Services (on Play Store devices)
+- User consent for each data type read
+
+**Metadata Available:**
+- **Timestamps:** Start and end time (millisecond precision)
+- **Device/Source:** Which app or device provided data
+- **Accuracy:** Measurement precision
+- **Units:** Always included
+- **Entry Method:** Manual vs automatic/sensor
+
+---
+
+## Cross-Platform Comparison
+
+### Common Data Types (Both Platforms)
+These data types are available on both iOS and Android with consistent structure:
+
+| Data Type | Apple HealthKit | Google Health Connect | Notes |
+|-----------|----------------|----------------------|-------|
+| **Weight** | ✓ | ✓ | Both support kg/lbs |
+| **Height** | ✓ | ✓ | Both support metric/imperial |
+| **Steps** | ✓ | ✓ | Daily count and historical |
+| **Distance** | ✓ | ✓ | Walking/running distance |
+| **Heart Rate** | ✓ | ✓ | BPM, resting HR, HRV |
+| **Blood Pressure** | ✓ | ✓ | Systolic/diastolic |
+| **Sleep** | ✓ | ✓ | Duration, stages |
+| **Active Energy** | ✓ | ✓ | Calories burned |
+| **Body Temperature** | ✓ | ✓ | °C/°F |
+| **Blood Glucose** | ✓ | ✓ | mg/dL, mmol/L |
+| **Respiratory Rate** | ✓ | ✓ | Breaths per minute |
+| **SpO2** | ✓ | ✓ | Oxygen saturation |
+| **Nutrition** | ✓ | ✓ | Calories, macros, hydration |
+| **Exercise** | ✓ | ✓ | Type, duration, calories |
+| **Body Fat %** | ✓ | ✓ | Percentage |
+
+### Platform-Specific Features
+
+**Apple-Only:**
+- ECG measurements (Apple Watch)
+- Atrial fibrillation detection
+- Walking steadiness/asymmetry metrics
+- Environmental sound levels
+- More detailed mobility analysis
+- Integration with Apple ecosystem (Watch, iPad, Mac)
+
+**Android-Only:**
+- More granular exercise types
+- Broader device ecosystem (Samsung, Fitbit, Garmin, etc.)
+- More flexible third-party app integrations
+- Earlier API access for some features
+
+### Unit Conversions
+Both platforms handle units automatically:
+
+| Measurement | iOS Units | Android Units | Notes |
+|------------|-----------|---------------|-------|
+| Weight | kg, lbs | kg, lbs | 1 kg = 2.20462 lbs |
+| Height | cm, in | cm, in, ft+in | 1 in = 2.54 cm |
+| Temperature | °C, °F | °C, °F | °F = (°C × 9/5) + 32 |
+| Glucose | mg/dL, mmol/L | mg/dL, mmol/L | mg/dL = mmol/L × 18.02 |
+| Distance | km, mi | km, mi | 1 mi = 1.60934 km |
+
+### Time Precision
+- **Apple:** Millisecond precision (Unix timestamp)
+- **Android:** Millisecond precision (Unix timestamp)
+- **Both:** Support historical queries with date ranges
+- **Best Practice:** Store all timestamps in UTC on server
+
+---
+
+## Integration Complexity Assessment
+
+### Apple HealthKit
+
+**Complexity:** ⭐⭐⭐ (Medium - 3/5)
+
+**Advantages:**
+- Mature, stable framework (since iOS 8)
+- Excellent documentation (with Apple Developer account)
+- Strong type safety with Swift
+- Consistent API across iOS versions
+- Good debugging tools in Xcode
+- Deep integration with Apple Watch
+
+**Challenges:**
+- Requires Mac for development
+- Requires Xcode
+- Simulator has limited HealthKit support
+- Testing on physical device required
+- Some features require Apple Developer Program ($99/year)
+
+**Development Requirements:**
+- macOS with Xcode
+- iOS deployment target: iOS 13+ (for full features)
+- Swift or Objective-C
+- HealthKit framework entitlement
+
+### Google Health Connect
+
+**Complexity:** ⭐⭐⭐⭐ (Medium-High - 4/5)
+
+**Advantages:**
+- Modern, actively developed framework
+- Centralizes data from all health apps
+- Cross-app data sharing
+- User privacy controls
+- Works on wide range of devices
+
+**Challenges:**
+- Newer framework (introduced 2023, replacing Google Fit)
+- Documentation still evolving
+- Android version compatibility (API 34+ recommended)
+- Device fragmentation (different OEM implementations)
+- Health Connect app must be installed separately
+- More complex testing matrix (device/OS combinations)
+
+**Development Requirements:**
+- Android Studio
+- Minimum SDK: API 26 (Android 8) with compatibility layer
+- Recommended SDK: API 34 (Android 14) for full features
+- Kotlin or Java
+- Health Connect Jetpack library
+- Google Play Services (optional but recommended)
+
+---
+
+## Recommended MVP Integration Strategy
+
+### Phase 1: Manual Entry (Current MVP Scope)
+**Timeline:** Week 1-4
+**Features:**
+- Manual entry of weight, height
+- Manual entry of basic vitals (heart rate, blood pressure, temperature)
+- Web-based interface only
+- No mobile integration yet
+
+### Phase 2: Mobile Foundation
+**Timeline:** Week 5-8
+**Features:**
+- Build basic iOS and Android apps
+- Implement authentication
+- Manual data entry on mobile
+- Sync with server
+
+### Phase 3: Health Framework Integration
+**Timeline:** Week 9-12
+**Features:**
+- Implement HealthKit on iOS
+- Implement Health Connect on Android
+- Support top 5 most important data types:
+  1. Weight
+  2. Heart Rate
+  3. Blood Pressure
+  4. Sleep (duration)
+  5. Steps (count)
+- Background sync every 15-30 minutes
+- Historical data import (last 30 days)
+
+### Phase 4: Expanded Data Types
+**Timeline:** Week 13-16
+**Features:**
+- Add all common data types
+- Support for exercise tracking
+- Nutrition tracking
+- Advanced sleep analysis
+- Menstrual cycle tracking
+
+---
+
+## Data Model Recommendations
+
+### Enhanced health_metrics Table
+
+```sql
+ALTER TABLE health_metrics ADD COLUMN metric_source VARCHAR(50) 
+  CHECK (metric_source IN ('manual', 'healthkit', 'healthconnect', 'third_party_device', 'unknown'));
+
+ALTER TABLE health_metrics ADD COLUMN source_device_id VARCHAR(255);
+  -- Stores identifier for source device/app (e.g., "com.apple.health.Health", "com.fitbit.FitbitMobile")
+
+ALTER TABLE health_metrics ADD COLUMN accuracy DECIMAL(5,2);
+  -- Sensor accuracy for automatic measurements (0.0-1.0, where 1.0 = perfect)
+
+ALTER TABLE health_metrics ADD COLUMN metadata JSONB;
+  -- Flexible storage for platform-specific data:
+  -- iOS: {"HKDevice": "iPhone14,2", "HKSource": "com.apple.Health"}
+  -- Android: {"device": "Samsung Galaxy S21", "package": "com.sec.android.app.health"}
+```
+
+### New Table: health_metric_sources
+```sql
+CREATE TABLE health_metric_sources (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    platform VARCHAR(20) NOT NULL, -- 'ios' or 'android'
+    device_name VARCHAR(255),
+    source_bundle_id VARCHAR(255), -- App/package ID
+    first_sync TIMESTAMP DEFAULT NOW(),
+    last_sync TIMESTAMP DEFAULT NOW(),
+    is_active BOOLEAN DEFAULT TRUE,
+    
+    UNIQUE(user_id, platform, source_bundle_id)
+);
+
+CREATE INDEX idx_metric_sources_user ON health_metric_sources(user_id);
+```
+
+### New Table: sync_history
+```sql
+CREATE TABLE sync_history (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    platform VARCHAR(20) NOT NULL,
+    sync_type VARCHAR(50) NOT NULL, -- 'initial', 'incremental', 'manual'
+    records_imported INTEGER DEFAULT 0,
+    records_failed INTEGER DEFAULT 0,
+    sync_duration_seconds INTEGER,
+    error_message TEXT,
+    synced_from TIMESTAMP,
+    synced_to TIMESTAMP,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_sync_history_user ON sync_history(user_id, created_at DESC);
+```
+
+---
+
+## Sync Strategy
+
+### Initial Sync (First Connection)
+When user first connects health framework:
+1. Request last 30 days of data (common window)
+2. Import in batches to avoid overwhelming server
+3. Show progress to user
+4. Handle errors gracefully
+5. Store sync timestamp for incremental updates
+
+### Incremental Sync (Background)
+Every 15-30 minutes:
+1. Query for new data since last sync
+2. Send new records to server
+3. Handle conflicts (same metric, multiple sources)
+4. Update last sync timestamp
+
+### Conflict Resolution Strategy
+When same metric type exists from multiple sources:
+1. **Automatic Entry** (sensor/device) > **Manual Entry**
+2. **More Recent** > **Older** (for time-series data)
+3. **More Accurate** > **Less Accurate** (based on metadata)
+4. **User Preference** (if user sets preferred source)
+
+### Battery Optimization
+- Limit sync frequency when battery < 20%
+- Use WorkManager (Android) and Background Tasks (iOS)
+- Batch requests to minimize wake-ups
+- Sync only when on Wi-Fi (user preference)
+- Respect battery saver mode
+
+---
+
+## Security & Privacy Considerations
+
+### Data Transmission
+- **Always use HTTPS** (TLS 1.3)
+- **Encrypt sensitive data** at REST on server
+- **Never store credentials** on device (use tokens)
+- **Certificate pinning** for API calls
+
+### Data Storage
+- **Encrypt at rest** using database encryption
+- **Separate encryption keys** per user
+- **No plaintext passwords** (bcrypt/scrypt/Argon2)
+- **Secure key derivation** for data access
+
+### User Privacy
+- **Clear permission requests** explaining why data is needed
+- **Granular controls** - user chooses what to share
+- **Easy data deletion** - "nuke option" from intro.md
+- **No data sharing** with third parties without explicit consent
+- **Transparent data usage** - show user what's stored
+
+### Compliance
+- **GDPR** (Europe)
+- **HIPAA** (if handling protected health information in US)
+- **CCPA** (California)
+- **App Store Review Guidelines** (Apple)
+- **Google Play Policy** (Android)
+
+---
+
+## Open Questions & Further Research
+
+### Priority 1 (MVP Blocking)
+1. **Conflict Resolution Algorithm**
+   - What if user manually enters weight but scale also sent data?
+   - Need comprehensive conflict resolution policy
+
+2. **Background Sync Optimization**
+   - Optimal sync interval for battery vs data freshness
+   - How to handle offline scenarios
+
+3. **Data Retention Policy**
+   - How long to keep historical data?
+   - Should old data be archived or deleted?
+
+### Priority 2 (Post-MVP)
+4. **Third-Party Device Integration**
+   - Fitbit, Garmin, Oura Ring, Whoop, etc.
+   - Each requires separate API integration
+
+5. **Data Export Format**
+   - What format for user downloads?
+   - JSON, CSV, FHIR (HL7), or custom?
+
+6. **Advanced Analytics**
+   - Trends, correlations, predictions
+   - Privacy-preserving computations?
+
+7. **Cross-Platform Sync**
+   - What if user has both iOS and Android devices?
+   - How to merge data from both?
+
+### Priority 3 (Future)
+8. **Real-Time Monitoring**
+   - Live heart rate, blood glucose alerts?
+   - Push notification strategy
+
+9. **Data Visualization**
+   - Charts, graphs, heatmaps
+   - What library to use?
+
+10. **International Units**
+    - Automatic unit conversion based on user location?
+    - Support for medical vs customary units?
+
+---
+
+## Implementation Checklist
+
+### Pre-Development
+- [ ] Finalize data model with source tracking
+- [ ] Design conflict resolution algorithm
+- [ ] Create API endpoints for bulk data import
+- [ ] Set up database encryption
+
+### iOS Development
+- [ ] Add HealthKit capability in Xcode
+- [ ] Write permission request code
+- [ ] Implement HealthKit queries for top 5 data types
+- [ ] Implement background sync with BGTaskScheduler
+- [ ] Test on physical device (simulator has limited support)
+
+### Android Development
+- [ ] Add Health Connect dependencies
+- [ ] Add permissions to AndroidManifest
+- [ ] Write permission request code
+- [ ] Implement Health Connect queries for top 5 data types
+- [ ] Implement background sync with WorkManager
+- [ ] Test on multiple Android versions/devices
+
+### Backend Development
+- [ ] Create bulk import API endpoints
+- [ ] Implement conflict resolution logic
+- [ ] Add sync history tracking
+- [ ] Optimize database indexes for time-series queries
+- [ ] Implement data deletion endpoint ("nuke")
+
+### Testing
+- [ ] Unit tests for data parsing
+- [ ] Integration tests for sync logic
+- [ ] Manual testing on physical devices
+- [ ] Battery usage profiling
+- [ ] Security audit
+- [ ] Load testing with thousands of records
+
+---
+
+## Conclusion
+
+**Feasibility:** ✅ **Highly Feasible**
+
+Both mobile platforms provide robust, well-documented frameworks for health data access. The integration is straightforward for common data types (weight, height, heart rate, blood pressure, sleep, steps).
+
+**Recommendation for MVP:**
+- Start with **Phase 1** (manual entry) to validate core architecture
+- Move to **Phase 2** (mobile apps) for basic platform functionality
+- Implement **Phase 3** (health frameworks) with top 5 data types
+- Expand in **Phase 4** based on user feedback
+
+**Timeline Estimate:**
+- Phase 1: 4 weeks (manual entry web app)
+- Phase 2: 4 weeks (mobile app foundation)
+- Phase 3: 4 weeks (health framework integration)
+- Phase 4: 4 weeks (expanded data types)
+
+**Total to Full Mobile Integration:** ~16 weeks (4 months)
+
+---
+
+## References
+
+### Official Documentation
+- [Apple HealthKit Documentation](https://developer.apple.com/documentation/healthkit)
+- [Google Health Connect Documentation](https://developer.android.com/health-connect)
+- [Apple Human Interface Guidelines - Health](https://developer.apple.com/design/human-interface-guidelines/health)
+- [Google Play - Health Apps Policy](https://play.google.com/console/about/health/)
+
+### Data Type References
+- [HealthKit HKObjectType Constants](https://developer.apple.com/documentation/healthkit/hkobjecttype)
+- [Health Connect Data Types](https://developer.android.com/reference/kotlin/androidx/health/data/class)
+- [Common Data Elements - FHIR](https://hl7.org/fhir/observation.html)
+
+### Code Examples
+- Apple Sample Code: HKWorkoutSession, HKHealthStore
+- Android Sample Code: Health Connect Samples on GitHub
+
+---
+
+**Next Steps:**
+1. Review this research with stakeholders
+2. Prioritize which data types for MVP
+3. Choose mobile development framework (React Native vs native)
+4. Begin implementation with Phase 1 (manual entry)