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