bogdan Implement comprehensive HealthProbe snapshot + delta + anomaly system

e052b34 a month ago History

# HealthProbe – Claude Code Instructions

## Project Context

**HealthProbe** is an iOS app that audits Apple HealthKit data integrity.  
It detects anomalies: data loss, historical insertions, duplicates, divergence trends.  
Full specification: `HealthProbe/Doc/HealthProbe – Complete Specification & Motivations.md`

**Current state:** Xcode scaffold only. `ContentView.swift` and `Item.swift` are default templates — replace them entirely.

---

## Claude Code Scope: UI Layer

Claude Code is responsible for:
- All **SwiftUI Views** (`Views/` directory)
- All **ViewModels** (`ViewModels/` directory)
- **Navigation structure** and tab/split layout
- **Design system** (colors, typography, spacing)
- **Preview providers** for all views
- **Accessibility** (VoiceOver, Dynamic Type)

Claude Code does NOT own:
- `Services/` — HealthKit queries, anomaly detection, sync monitoring (see AGENTS.md)
- `Models/` — SwiftData models (see AGENTS.md)
- Entitlements, Info.plist, project configuration

When services are not yet implemented, **consume their protocols and use mock implementations** for UI development.

---

## Target Screen Structure

```
App (TabView)
├── Tab 1: Dashboard          → DashboardView
├── Tab 2: Anomalies          → AnomalyListView → AnomalyDetailView
├── Tab 3: Audit Trail        → AuditTrailView
├── Tab 4: Sync Status        → SyncStatusView
└── Tab 5: Settings           → SettingsView
```

### DashboardView
- Large status indicator: ✅ Healthy / ⚠️ Check / 🚨 Critical
- Last check timestamp
- Summary cards: samples tracked, anomalies found (all-time)
- Up to 3 recent active alerts (tappable → AnomalyDetailView)
- "Check Now" button (calls monitoring service)

### AnomalyListView
- List of `DetectedAnomaly` sorted by date (most recent first)
- Filter: All / Critical / Warning / Info
- Filter: by type (deletion, insertion, duplicate, divergence)
- Each row: severity badge, type, sample type, date
- Swipe to mark resolved

### AnomalyDetailView
- Full anomaly details
- Evidence dictionary displayed as key-value rows
- Severity badge
- Share button → exports as Markdown (for bug reports)
- "Mark Resolved" action

### AuditTrailView
- Chronological list of `AuditTrailEntry`
- Each row: timestamp, event type chip, message
- Search/filter by event type
- Export button → JSON

### SyncStatusView
- Current iCloud sync state (chip: enabled / local-only)
- Last sync timestamp
- List of `SyncStateChange` events (most recent first)
- Visual indicator when sync is stalled (no event in > 48h)

### SettingsView
- Check frequency: 2h / 6h / 12h / 24h (Picker)
- Sample types to monitor (MultiSelect toggle list)
- Alert thresholds (severity level for push notifications)
- CloudKit sync toggle (off by default, with privacy disclaimer)
- Export all data (JSON)
- Delete all audit data (destructive, confirm alert)

---

## Design Guidelines

**Tone:** Professional, calm, medical-adjacent. Not alarming unless critical.

**Color System:**
```swift
// Status colors
.healthyGreen   // SF: green  — all clear
.warningAmber   // SF: yellow — attention needed  
.criticalRed    // SF: red    — action required
.neutralGray    // SF: gray   — informational / resolved
```

**Typography:** SF Pro (system font). No custom fonts.

**Spacing:** 8pt grid. Use `VStack(spacing: 12)` as baseline.

**Icons:** SF Symbols only. No third-party icon sets.

**Key SF Symbols:**
- `checkmark.shield.fill` — healthy status
- `exclamationmark.triangle.fill` — warning
- `xmark.shield.fill` — critical
- `clock.arrow.circlepath` — audit trail
- `antenna.radiowaves.left.and.right` — sync
- `waveform.path.ecg` — health data
- `doc.text.magnifyingglass` — anomaly detail

**Dark mode:** Required. Test in both modes.

**Privacy-first UI:**
- Health metric values are **never shown in plain text** in list rows
- Values visible only in `AnomalyDetailView` after tap
- Evidence dictionary values shown as monospace text, not highlighted

---

## SwiftData Integration

Models are defined in `Models/`. Reference them read-only from views:

```swift
// In views, use @Query — never write directly from a View
@Query(sort: \DetectedAnomaly.detectedAt, order: .reverse)
private var anomalies: [DetectedAnomaly]

// Mutations go through ViewModels or services only
```

Until `Models/` are implemented, use mock data via `PreviewProvider`.

---

## ViewModel Pattern

```swift
// Pattern for all ViewModels
@MainActor
@Observable
final class DashboardViewModel {
    private let monitor: HealthMonitorProtocol  // protocol, not concrete type
    
    var status: HealthStatus = .unknown
    var recentAnomalies: [DetectedAnomaly] = []
    var lastChecked: Date?
    
    init(monitor: HealthMonitorProtocol = HealthMonitorService.shared) {
        self.monitor = monitor
    }
    
    func refresh() async {
        await monitor.runCheck()
    }
}
```

Always inject dependencies via protocols — makes previews and tests possible without real HealthKit.

---

## Mock Data Protocol

Until services are ready, define preview mocks in `Utilities/Mocks.swift`:

```swift
struct MockHealthMonitor: HealthMonitorProtocol {
    func runCheck() async { }
    var status: HealthStatus { .warning }
}

extension DetectedAnomaly {
    static var preview: DetectedAnomaly {
        DetectedAnomaly(
            detectedAt: .now,
            type: "silent_deletion",
            severity: "warning",
            sampleType: "Steps",
            summary: "72 samples missing without deletion event",
            evidence: ["loss_count": "72", "loss_percent": "23.4"]
        )
    }
}
```

---

## File Organization

```
HealthProbe/
├── Views/
│   ├── Dashboard/
│   │   ├── DashboardView.swift
│   │   └── StatusCardView.swift
│   ├── Anomalies/
│   │   ├── AnomalyListView.swift
│   │   └── AnomalyDetailView.swift
│   ├── AuditTrail/
│   │   └── AuditTrailView.swift
│   ├── Sync/
│   │   └── SyncStatusView.swift
│   └── Settings/
│       └── SettingsView.swift
├── ViewModels/
│   ├── DashboardViewModel.swift
│   ├── AnomalyListViewModel.swift
│   └── SyncViewModel.swift
├── Models/           ← NOT owned by Claude Code
├── Services/         ← NOT owned by Claude Code
└── Utilities/
    ├── Mocks.swift
    ├── DateFormatters.swift
    └── DesignSystem.swift
```

---

## Privacy Directives

**Mandatory — no exceptions:**
- No credentials, tokens, or API keys in any file
- No personal data, device identifiers, or account identifiers
- No real health values in code, comments, previews, or tests
- Synthetic preview data only (see Mocks.swift above)

---

## Before Marking a Task Complete

- [ ] View renders in both Light and Dark mode (use Preview)
- [ ] VoiceOver labels set on interactive elements
- [ ] Dynamic Type tested (at least xSmall and AX3)
- [ ] Works with mock data (no real HealthKit dependency in View layer)
- [ ] No health values displayed without explicit user tap
- [ ] Compiles without warnings