FitTrack — Requirements

Personas

  • Casual logger — opens after a run, taps “+ Run”, picks duration, saves. Wants the experience to take under 10 seconds.
  • Active tracker — starts the workout on the Watch, lets it run with heart rate and pace, ends it; iPhone is only used later for review.
  • Trend watcher — checks the dashboard weekly to see 30-day trends; wants beautiful, readable charts.

User stories

Onboarding & permissions

  1. As a first-time user I see a clear screen explaining what HealthKit data FitTrack reads and writes, before the system permission sheet.
  2. I am asked only for the minimum data: read heart rate / steps / active energy / distance, write workouts. Nothing else.
  3. If I deny everything, the app falls back to manual workout entry. Denial is not a dead-end.

Logging a workout (iPhone)

  1. From the home screen I tap “+” to log a workout: pick activity type (run/cycle/swim/walk/strength), duration, optional notes, optional photo.
  2. Workout saves to SwiftData and writes a corresponding HKWorkout to HealthKit (visible in Apple Health).
  3. If CloudKit sync is delayed, my saved workout is still visible immediately; sync indicator shows pending.

Starting a workout (watchOS)

  1. From the Watch app I tap an activity type to start a session. Heart rate and distance show live.
  2. The session runs in the foreground; double-tap on Apple Watch S9+ pauses/resumes.
  3. Ending the session saves the HKWorkout (with samples) to HealthKit and the FitTrack SwiftData store.
  4. While a session is active, a Live Activity on the iPhone shows duration + heart rate + a “Stop on Watch” hint.

Dashboard

  1. The dashboard shows 30-day trend charts for: heart rate (resting + active), steps, active energy, total workouts per week.
  2. Charts are tappable; tapping a data point opens that day’s detail with the contributing workouts.
  3. Charts gracefully handle missing days (shown as gaps, not as zero).

Sharing & export

  1. I can export my last 90 days of workouts as a .csv via the share sheet.
  2. I can delete all FitTrack data — workouts and any cached samples — with one explicit two-tap confirmation. This must NOT delete HealthKit data written before (Apple’s rules).

Complications

  1. The Modular Compact face shows my last workout’s date + activity icon.
  2. The Smart Stack widget shows today’s active-energy progress vs goal.

Acceptance criteria

  • Cold launch to home: < 1.5 s on iPhone 13.
  • HealthKit query for 30 days of heart rate samples: < 800 ms end-to-end.
  • Watch session start → first heart rate sample on screen: < 5 s.
  • Live Activity update interval: 5 s during active workout, never less than the system permits.
  • CloudKit sync of a new workout between two devices: < 30 s typical.
  • Zero crashes in 100 simulated workouts (CI test).

Non-goals

  • No social feed, no follower system, no “shares per workout” — not Strava.
  • No GPS route tracking — that’s a third capstone’s worth of work and adds little here.
  • No personalized coaching, no ML-derived recommendations.
  • No third-party integration (Garmin, Whoop, etc.) — first-party Apple data only.
  • No web dashboard.

Constraints

  • iOS 17+ (SwiftData + CloudKit, Live Activities, Swift Charts 2.0).
  • watchOS 10+ (modern workout session API, Smart Stack widget kind).
  • Apple Developer Program — HealthKit capability requires it.

HealthKit privacy contract

The app’s purpose strings must be exact and honest. Drafts:

  • NSHealthShareUsageDescription: “FitTrack reads your heart rate, steps, distance, and active energy to show trends and power your workout history.”
  • NSHealthUpdateUsageDescription: “FitTrack writes the workouts you log so they appear in Apple Health and contribute to your move ring.”

Apple Review rejects vague strings. Be specific.

Next: Architecture