workouts/REQUIREMENTS.md

# Workouts App Requirements

## Overview
A workout tracking iOS application with Apple Watch companion that helps users manage workout splits, track exercise logs, and sync data across devices using CloudKit.

## Platform Requirements
- iOS app (iPhone)
- watchOS app (Apple Watch companion)
- CloudKit sync between devices
- SwiftData for persistence with CloudKit automatic sync

## Core Data Models

### Split
- `name: String` - Name of the workout split
- `color: String` - Color theme for the split
- `systemImage: String` - SF Symbol icon
- `order: Int` - Display order
- Relationship: One-to-many with Exercise

### Exercise  
- `name: String` - Exercise name
- `order: Int` - Order within split
- `sets: Int` - Number of sets
- `reps: Int` - Number of repetitions
- `weight: Int` - Weight amount
- `loadType: Int` - Type of load (weight units)
- Relationship: Many-to-one with Split

### Workout
- `start: Date` - Workout start time
- `end: Date?` - Workout end time (optional)
- `status: WorkoutStatus` - Enum (notStarted, inProgress, completed, skipped)
- Relationship: Many-to-one with Split (optional)
- Relationship: One-to-many with WorkoutLog

### WorkoutLog
- `exerciseName: String` - Name of the exercise
- `date: Date` - When performed
- `order: Int` - Order in workout
- `sets: Int` - Number of sets completed
- `reps: Int` - Number of reps completed  
- `weight: Int` - Weight used
- `status: WorkoutStatus?` - Completion status
- `completed: Bool` - Whether exercise was completed
- Relationship: Many-to-one with Workout

## iOS App Features

### Main Navigation (TabView)
1. **Workouts Tab**
   - List all workouts sorted by start date (newest first)
   - Create new workout from split
   - Edit/delete existing workouts
   - Navigate to workout logs

2. **Logs Tab**
   - Historical exercise completion records
   - Grouped by workout

3. **Reports Tab**
   - Workout statistics and progress tracking

4. **Achievements Tab**
   - User achievements and milestones

### Split Management
- Create/edit/delete workout splits
- Assign colors and system images
- Reorder splits
- Add/remove/reorder exercises within splits

### Exercise Management
- Add exercises to splits
- Set default sets, reps, weight
- Reorderable list within each split
- Support for different load types

### Workout Flow
- Start workout from selected split
- Auto-populate exercises from split template
- Track exercise completion status
- Update sets/reps/weight during workout
- Mark exercises as completed/skipped
- Auto-prevent device sleep during workouts

## Watch App Features

### Main View
- List active workouts
- Show "No Workouts" state when empty
- Sync button to pull from CloudKit
- Display sync status and last sync time

### Workout Display
- Show workout name and status
- List exercises with completion indicators
- Quick completion toggles

### CloudKit Sync
- Manual sync trigger
- Hybrid approach: SwiftData for local storage + direct CloudKit API for sync
- Sync from `com.apple.coredata.cloudkit.zone`
- Fetch and save Splits, Exercises, Workouts, and WorkoutLogs

## Data Management

### Exercise Library
- YAML-based exercise definitions in `Resources/` directory
- `ExerciseListLoader` to parse YAML files
- Preset libraries:
  - Bodyweight exercises (`bodyweight-exercises.yaml`)
  - Planet Fitness starter (`pf-starter-exercises.yaml`)

### CloudKit Configuration
- Container ID: `iCloud.com.dev.rzen.indie.WorkoutsV2`
- Automatic sync via `ModelConfiguration(cloudKitDatabase: .automatic)`
- Development environment for debug builds
- Production environment for release/TestFlight builds

## UI/UX Requirements

### Design Patterns
- SwiftUI throughout
- NavigationStack for hierarchical navigation
- Form-based editing interfaces
- Sheet presentations for modal operations
- Swipe gestures for edit/delete/complete actions

### Visual Design
- Custom color system via Color extensions
- Consistent use of SF Symbols
- Reorderable lists using SwiftUIReorderableForEach
- Calendar-style list items for workouts
- Checkbox components for completion tracking

### Key UI Components
- `CalendarListItem` - Formatted date/time display
- `Checkbox` - Visual completion indicators
- `SplitListItemView` - Split display with icon and color
- `ExerciseListItemView` - Exercise display with sets/reps/weight
- `WorkoutLogListItemView` - Log entry display

## Technical Architecture

### Project Structure
```
Workouts/
├── Models/          # SwiftData models
├── Schema/          # Database schema and migrations
├── Views/           # UI components by feature
│   ├── Splits/
│   ├── Exercises/
│   ├── Workouts/
│   └── WorkoutLog/
├── Utils/           # Shared utilities
└── Resources/       # YAML exercise definitions

Workouts Watch App/
├── Schema/          # Watch-specific container
├── Views/           # Watch UI components
└── CloudKitSyncManager.swift  # Direct CloudKit sync
```

### Key Technical Decisions
- SwiftData with CloudKit automatic sync
- Versioned schema with migration support
- Single file per model convention
- No circular relationships in data model
- Platform-specific implementations for iOS/watchOS
- Shared model definitions between platforms

## Dependencies
- **Yams**: YAML parsing for exercise definitions
- **SwiftUIReorderableForEach**: Drag-to-reorder lists

## Entitlements Required
- CloudKit
- Push Notifications (aps-environment)
- App Sandbox
- File access (read-only for user-selected files)

## Build Configuration
- Swift Package Manager for dependencies
- Separate targets for iOS and watchOS
- Shared CloudKit container between apps
- Automatic provisioning and code signing