# HealthProbe Documentation Index

## Quick Navigation

### 📋 Core Documentation

1. **[Complete Specification & Motivations](HealthProbe%20–%20Complete%20Specification%20&%20Motivations.md)**
   - Complete system design
   - Concrete observed cases (Sept 2025 data loss + ongoing issues)
   - Motivations for each feature
   - Technical architecture & threading model
   - Privacy & security guarantees

2. **[MVP Specification](HealthProbe%20iOS%20–%20Specification%20(MVP).md)** *(original)*
   - Feature scope for iOS 1.0
   - Core HealthKit monitoring approach

---

## Project Status

| Component | Status | Notes |
|-----------|--------|-------|
| **iOS App Foundation** | ✅ Started | SwiftUI + SwiftData scaffolding in place |
| **Core Architecture** | 📋 Designed | See "Complete Specification" |
| **HealthKit Integration** | ⏳ Pending | Implement anchored queries, observer queries |
| **Anomaly Detection** | 📋 Designed | Logic documented, pending implementation |
| **Sync Monitoring** | 📋 Designed | Background thread model defined |
| **UI Dashboard** | ⏳ Pending | Wireframes in Complete Specification |
| **Data Export** | 📋 Designed | Format specs ready |
| **macOS Companion** | 🔄 Future | Post-MVP enhancement |

---

## Motivation: Why HealthProbe Exists

**The Problem:** Apple Health data loss events (confirmed September 2025, ongoing sporadic reports) lack any detection mechanism. Users don't know their data has been lost, corrupted, or silently modified.

**Concrete Examples:**
- **Historical insertions:** Workouts from 6+ months ago suddenly appearing
- **Silent deletions:** Multi-week gaps with no deletion notification
- **Duplicates:** Same workout syncing multiple times across devices
- **Divergence:** Metrics (steps, energy, HR) drifting without user action

See **Complete Specification § 2** for detailed observed cases and forensic implications.

---

## Next Steps

1. **Implement HealthKit Integration** (`Sources/HealthKitMonitor.swift`)
   - `HKAnchoredObjectQuery` for efficient incremental queries
   - `HKObserverQuery` for real-time change notifications
   - Track: Workouts, Heart Rate, Steps, Sleep, Activity Summary

2. **Build Anomaly Detection** (`Sources/AnomalyDetector.swift`)
   - Historical insertion detection
   - Silent deletion detection
   - Duplicate fingerprinting
   - Divergence trend analysis

3. **Implement Sync Monitoring** (`Sources/SyncMonitor.swift`)
   - Background thread that tracks iCloud state changes
   - Document sync events in audit trail
   - Trigger re-baselining on sync state transitions

4. **Create UI Dashboard** (`Views/HealthStatusView.swift`)
   - Show current health status
   - Display active alerts
   - Timeline of anomalies
   - Audit trail viewer

---

## Key Design Decisions

| Decision | Rationale |
|----------|-----------|
| **Read-only + HealthKit** | Never modify health data; pure observation only |
| **Local-first storage** | Full functionality without internet; privacy-first |
| **SwiftData** | Efficient local persistence, encrypted by iOS |
| **Anchored queries** | Minimize HealthKit load, reduce battery impact |
| **Separate sync thread** | Non-blocking, responsive UI during background work |
| **Aggregated digests only** | CloudKit sync respects privacy, no raw samples exported |

---

## Document Versions

- **v1.0** — 2026-05-01 — Initial comprehensive specification
  - Concrete cases from DearApple
  - Full technical architecture
  - MVP feature scope + future roadmap

---

*HealthProbe: Guarding the integrity of your health data.*
