# 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):
```bash
./scripts/smoke/smoke_all.sh
```

**SharedCore unit tests only:**
```bash
cd SharedCore && swift test --disable-sandbox
```

**Individual platform builds** (no code signing):
```bash
./scripts/smoke/build_ios.sh
./scripts/smoke/build_watch.sh
./scripts/smoke/build_tvos.sh
```

**Build iOS via xcodebuild directly:**
```bash
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.