# CLAUDE.md

<!-- rgb(86, 20, 150); -->

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a workout tracking iOS app built with Swift/SwiftUI, featuring both iPhone and Apple Watch companions. The app helps users manage workout splits, track exercise logs, and sync data across devices using CloudKit.

## Development Commands

### Building and Running
- **Build the project**: Open `Workouts.xcodeproj` in Xcode and build (Cmd+B)
- **Run on iOS Simulator**: Select the Workouts scheme and run (Cmd+R)
- **Run on Apple Watch Simulator**: Select the "Workouts Watch App" scheme and run
- **Dependencies**: The project uses Swift Package Manager. Dependencies are resolved automatically via `Package.resolved`

### Key Dependencies
- **Yams**: For parsing YAML exercise definition files in `Resources/`
- **SwiftUIReorderableForEach**: For reorderable lists in UI components

## Architecture

### Data Layer
- **SwiftData**: Core persistence framework with CloudKit sync
- **Schema Management**: Versioned schemas in `Schema/` directory with migration support
- **Models**: Located in `Models/` directory, following single-file-per-model convention

### Core Models
- **Split**: Workout routine templates with exercises, colors, and system images
- **Exercise**: Individual exercises within splits (sets, reps, weight, load type)
- **Workout**: Active workout sessions linked to splits
- **WorkoutLog**: Historical exercise completion records

### App Structure
- **Dual targets**: Main iOS app (`Workouts/`) and Watch companion (`Workouts Watch App/`)
- **Shared components**: Both apps share similar structure but have platform-specific implementations
- **TabView navigation**: Main app uses tabs (Workouts, Logs, Reports, Achievements)

### Exercise Data Management
- **YAML-based exercise definitions**: Located in `Resources/*.exercises.yaml`
- **ExerciseListLoader**: Parses YAML files into structured exercise data
- **Preset exercise libraries**: Starter sets for bodyweight and Planet Fitness routines

### CloudKit Integration
- **Automatic sync**: Configured via `ModelConfiguration(cloudKitDatabase: .automatic)`
- **Change observation**: App observes CloudKit sync events for UI refresh
- **Cross-device sync**: Data syncs between iPhone and Apple Watch

### UI Patterns
- **SwiftUI-first**: Modern declarative UI throughout
- **Navigation**: Uses NavigationStack for hierarchical navigation
- **Form-based editing**: Consistent form patterns for data entry
- **Reorderable lists**: Custom sortable components for exercise ordering

### Key Directories
- `Models/`: SwiftData model definitions
- `Views/`: UI components organized by feature (Splits, Exercises, Workouts, etc.)
- `Schema/`: Database schema management and versioning
- `Utils/`: Shared utilities (logging, date formatting, colors)
- `Resources/`: YAML exercise definitions and static assets

### Schema Guidelines
- Each model gets its own file in `Models/`
- Schema versions managed in `Schema/` directory
- Migration plans handle schema evolution
- No circular relationships in data model
- Use appropriate delete rules for relationships

### UI Guidelines (from UI.md)
- Tab-based root navigation with independent navigation stacks
- Consistent form patterns for add/edit operations
- Sheet presentations for modal operations
- Swipe gestures for common actions (edit, complete, navigate)

### Development Notes
- **Auto-lock disabled**: App prevents device sleep during workouts
- **Preview support**: ModelContainer.preview for SwiftUI previews
- **Logging**: Structured logging via AppLogger throughout the app
- **Color system**: Custom color extensions for consistent theming