CLAUDE.md

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

3.7 KiB Raw Blame History