# 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 Context Logging** | 📋 Designed | Log Health/iCloud state as forensic context; do not sync HealthProbe data via iCloud |
| **UI Dashboard** | ⏳ Pending | Wireframes in Complete Specification |
| **Local Archive Store** | 📋 Designed | Robust on-device archive is the source of truth |
| **Reports & Point Exports** | 📋 Designed | Export only selected reports/record tables, not a complete routine dump |
| **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 Local Archive Store** (`Sources/ArchiveStore.swift`)
   - Single robust local database for all archived samples
   - Preserve cross-type relationships, sources, devices, metadata, and fingerprints
   - Keep SwiftData as UI/cache/settings/history only

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 |
| **Archive DB as truth** | Store HealthKit samples and metadata in a robust local database, not split per data type |
| **SwiftData as UI cache** | Keep precomputed values, settings, logs, and history for visualization only |
| **Anchored queries** | Minimize HealthKit load, reduce battery impact |
| **No HealthProbe iCloud sync** | Device HealthKit databases evolve independently; CloudKit sync adds complexity without proven forensic benefit |
| **Selective forensic capture** | When Health/iCloud rewrites or downsamples historical data, counts alone are insufficient; HealthProbe archives complete samples for selected types in one local store |

---

## Document Versions

- **v1.0** — 2026-05-01 — Initial comprehensive specification
  - Concrete cases from DearApple
  - Full technical architecture
  - MVP feature scope + future roadmap
- **v1.1** — 2026-05-17 — Objective extension (post-findings)
  - New observed behavior: Apple-side consolidation/downsampling can rewrite historical samples (not just add/delete)
  - HealthProbe scope extended: from “counter of records” → “forensic backup agent” (local-only archives for selected types)
- **v1.2** — 2026-05-18 — Storage direction update
  - Robust single local archive store becomes the source of truth
  - SwiftData is limited to precomputed UI data, settings, logs, and history
  - CloudKit/iCloud sync removed from product goals; reports and point exports replace routine complete export ambitions

---

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