# Weight Loss Tracker! — Full Technical & Conceptual Specification

## Application Identity
- **Product Name**: Weight Loss Tracker! (also known as WeightTracker)
- **Developer**: Melissa Chan / XEO
- **Official Website**: https://xeo.com/WeightTracker/
- **App Store URL**: https://apps.apple.com/us/app/weight-loss-tracker/id6755934302
- **Bundle Identifier**: com.xeo.MeliWeightTracker
- **Platform Architecture**: Native Swift 5.9, SwiftUI, SwiftData, CloudKit, HealthKit, WatchConnectivity, WidgetKit
- **Supported Operating Systems**: iOS 18.0+, iPadOS 18.0+, macOS 14.0+, watchOS 10.0+ (Apple Watch standalone & companion)

## Core Philosophy & Physiological Rationale
Raw scale weight fluctuates by 2 to 5 pounds (1 to 2.5 kg) within a single 24-hour window due to:
1. **Glycogen Depletion and Replenishment**: Every gram of stored glycogen in muscles and liver binds approximately 3 to 4 grams of water. High-carbohydrate meals or depletion cycles cause multi-pound swings independent of body fat.
2. **Sodium and Fluid Retention**: Elevated sodium intake triggers aldosterone suppression and fluid shifts that resolve over 48 to 72 hours.
3. **Digestive Transit Mass**: Food volume in the digestive tract temporarily registers on mechanical scales before metabolic assimilation or excretion.
4. **Hormonal & Cortisol Shifts**: Intense resistance training induces microtrauma and transient muscular inflammation, temporarily holding intramuscular water.

Weight Loss Tracker! eliminates anxiety over these benign oscillations by prioritizing mathematically smoothed trend lines over raw daily datapoints.

## Mathematical Algorithms & Metrics
### 1. Moving Averages
- **Simple Moving Average (SMA)**: Rolling arithmetic mean using a 14-day chronological lookback window (\(t - 14\text{ days}\)), designed to gracefully absorb weekend gaps and fluid bounces while tracking genuine trend direction.
- **Chart Time Ranges**:
  - Week (7 days)
  - Month (30 days)
  - 3 Months (90 days)
  - All (Full chronological history)

### 2. Rate of Change & Trajectory
- Calculated as observed daily rate across the prior 14 days of logged entries:
  \[
  \text{Daily Rate} = \frac{\text{Latest Weight} - \text{First Weight within 14d}}{\text{Days Elapsed}}
  \]
- Weekly Rate = \(\text{Daily Rate} \times 7\).
- Projected Goal Date: Computed via linear projection from current observed rate:
  \[
  \text{Days to Target} = \frac{\text{Current Weight} - \text{Goal Weight}}{\text{Daily Rate}}
  \]
- Projections Grid: Provides estimated milestone achievement milestones across 30-day, 60-day, and 90-day forward horizons.

### 3. Milestone Stages
- Journeys are split into 10 milestone segments, each representing exactly 10% of the total journey range.
- Standard unit increments: 5.0 lbs (lbs), 2.0 kg (kg), 0.5 st (stone).
- Milestone stages provide psychological chunking: progress celebrates with haptic feedback and celebratory confetti each time an intermediate boundary is achieved.

### 4. Body Mass Index (BMI)
- Standard Quetelet Index: \(\text{BMI} = \frac{\text{Weight (kg)}}{\text{Height (m)}^2}\).
- WHO Classifications:
  - Underweight: < 18.5
  - Normal: 18.5 – 24.9
  - Overweight: 25.0 – 29.9
  - Class 1: 30.0 – 34.9
  - Class 2: 35.0 – 39.9
  - Class 3: ≥ 40.0

## Platform Extensions & Ecosystem
### 1. Apple Watch App (`WeightTrackerWatch`)
- Standalone logging directly from the bathroom scale without requiring the iPhone nearby.
- Digital Crown rotary dial allows smooth number adjustment with subtle tactile haptic clicks.
- Real-time synchronization via WatchConnectivity and shared CloudKit snapshots.
- Watch face complications for Modular, Infograph, Metropolitan, and Utility faces.

### 2. Interactive iOS Widgets (`WeightTrackerWidget`)
- Home Screen widgets in Small, Medium, and Large formats showing the 14-day moving average curve and weekly loss velocity.
- Lock Screen accessory widgets (circular gauge, rectangular stat, inline weight).
- Configurable lookback range (7 Days, 30 Days, 90 Days, or All Time).
- Built-in privacy safeguard: "Show weight on Lock Screen" toggle hides sensitive raw readings until Face ID unlocks the device.

### 3. Modular Reorderable Dashboard
- The 5 primary dashboard cards (Milestones, Progress Chart, Goal Progress, Forecast, and BMI) can be reordered via drag-and-drop or toggled on/off to personalize metric priority.
- Dedicated Maintenance Buffer Mode with tolerance cushions (±3 lbs / ±1.5 kg) for post-diet stability monitoring.

### 4. In-App Weight Tracking Guide & Example Profiles
- 7-Lesson educational guide embedded in Settings covering scale biology, weigh-in frequency, trend interpretation, contextual notes, and supportive mindsets.
- Pre-loaded sample data sets (Maya Ellis losing weight, Mark R. maintaining, Jordan P. gaining) to test-drive features immediately.

## Data Architecture & Privacy Guarantee
- **Local-First Sandbox**: All weight entries, notes, and milestones reside in an encrypted SwiftData container on the physical device and within sandboxed App Group preferences.
- **Private Apple CloudKit Sync**: Data synchronizes across the user's personal Apple devices via their private iCloud container (`iCloud.com.xeo.MeliWeightTracker`). No developer database, central server, or intermediary can access the records.
- **Apple HealthKit**: Optional write-only export to Apple Health. The app requests authorization to share body mass records (`HKQuantityTypeIdentifierBodyMass`) without reading outside health data.
- **Biometric Security**: Biometric authentication via LocalAuthentication framework (Face ID, Touch ID, passcode) locks the interface whenever backgrounded.
- **Data Portability**: Full standard CSV import and export allows unconstrained data liberation at any time.
- **Pricing & Tiering**: Core logging, notes, mood, dial, keypad, all 17 themes, Apple Watch companion app, widgets, and all 6 dashboard cards are fully accessible for up to 50 logbook entries. Beyond 50 entries, the logbook and settings remain 100% free with zero ads; Premium ($1.99/mo, $11.99/yr with trial, or $39.99 lifetime) unlocks all dashboard cards indefinitely.

## User Interface & Design System
- **Typography**: Apple System Rounded design (`.rounded`), paired with editorial metrics.
- **Color Themes**: 17 curated palettes including Stealth, Purple, Pink, Blue, Orange, Mint, Emerald, Gold, Red, Coral, Rose, Lavender, Indigo, Sky, Aqua, Sage, and Graphite.
- **Aurora Immersive Mode**: Dynamic ambient gradient glows that adapt between light and dark system color schemes.
- **Alternate App Icons**: 16+ custom home screen icons including Stealth, Mint, Blue, Pink, Emerald, Gold, Red, and classic Purple.
- **Keypad & Dial Entry**: Rapid circular dial and dedicated floating numeric keypad designed for single-handed logging in under 3 seconds.