WerkoutIOS/CLAUDE.md

CLAUDE.md

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

Build & Test Commands

Full smoke suite (token scan + SharedCore tests + all platform builds):

./scripts/smoke/smoke_all.sh

SharedCore unit tests only:

cd SharedCore && swift test --disable-sandbox

Individual platform builds (no code signing):

./scripts/smoke/build_ios.sh
./scripts/smoke/build_watch.sh
./scripts/smoke/build_tvos.sh

Build iOS via xcodebuild directly:

xcodebuild -project iphone/Werkout_ios.xcodeproj \
  -scheme 'Werkout_ios' -configuration Debug \
  -destination 'generic/platform=iOS' \
  CODE_SIGNING_ALLOWED=NO build

Schemes: Werkout_ios (iOS), Werkout_watch Watch App (watchOS), WekoutThotViewer (tvOS)

Workspace: Werkout.xcworkspace contains the iOS/watchOS project and tvOS project.

Architecture

Multi-Platform Structure

• iphone/ — Main iOS app and watchOS companion app (same Xcode project: Werkout_ios.xcodeproj)
• SharedCore/ — Swift Package (v5.9) with cross-platform code: data models, validation, token security, runtime reporting, utilities. Has per-platform test targets (SharedCoreiOSTests, SharedCoreWatchOSTests, SharedCoreTVOSTests).
• WekoutThotViewer/ — Standalone tvOS app (separate Xcode project)

Platform minimums: iOS 16+, watchOS 9+, tvOS 16+, macOS 13+.

iOS App (iphone/Werkout_ios/)

SwiftUI app with MVVM pattern. Three-tab navigation: All Workouts, Create Workout, Account.

Core singletons:

• UserStore — Auth state, token lifecycle (Keychain storage with legacy migration), login/logout, planned workouts
• DataStore — Cached workouts/exercises/muscles/equipment, parallel fetching via DispatchGroup
• BridgeModule — iPhone↔Watch communication via WCSession, workout timers, external display (AirPlay) support

Networking layer (Network/):

• Protocol-based: Fetchable (GET) and Postable (POST) protocols in Network.swift
• Concrete implementations in Fetchables.swift (e.g. AllWorkoutFetchable, LoginFetchable, CreateWorkoutFetchable)
• Auto-attaches auth token; 30-second timeout; error handling via FetchableError enum

Data persistence:

• CoreData (Werkout_ios.xcdatamodeld, managed by Persistence.swift)
• Keychain for token storage (Keychain.swift)
• UserDefaults for preferences and token metadata

Key integrations: HealthKit (calories, heart rate, workout sessions), AVFoundation (audio/video playback), WatchConnectivity

watchOS App (iphone/Werkout_watch Watch App/)

Companion app with HealthKit workout session management (WatchWorkout), timer display, exercise controls. Communicates with iPhone via BridgeModule using action-based message passing (WatchActions, PhoneToWatchActions).

View Organization

Views live in iphone/Werkout_ios/Views/ grouped by feature (AllWorkouts, CreateWorkout, Login, WorkoutDetail, etc.). Shared subviews are in iphone/Werkout_ios/subview/.

Data Flow Patterns

• Workout creation: WorkoutViewModel validates → CreateWorkoutFetchable POSTs → AppNotifications.createdNewWorkout triggers refresh
• Auth: LoginFetchable → UserStore stores token in Keychain → all requests auto-attach token → 401/403 triggers logout → proactive refresh 30min before expiry
• Watch sync: BridgeModule queues messages via BoundedFIFOQueue (max 100) over WCSession

CI

GitHub Actions (.github/workflows/apple-platform-ci.yml) runs on macOS 15 for all pushes/PRs. Executes smoke_all.sh which runs token security scan, SharedCore tests, and builds all three platforms. Build scripts fail on any warnings or errors.