LapBuddy iOS Swimming Tracker

Develop and maintain LapBuddy, a native iOS swimming lap counter/stopwatch app built with SwiftUI. The app helps swimmers track laps, times, and rest intervals during swim sessions with haptic feedback and detailed analytics.

Project Structure

LapBuddy is an Xcode project (`LapBuddy.xcodeproj`) using:

**SwiftUI** for UI layer

**CoreData** for data persistence

**MVVM-like architecture** with ObservableObject ViewModels

**State machine pattern** for session management

**CoreHaptics** for tactile feedback

Build & Run

Open `LapBuddy.xcodeproj` in Xcode

Build: ⌘B

Run: ⌘R

Target: iOS only

Architecture Overview

Core State Machine

The app's session logic is managed by a `CounterState` enum in `Counter.swift`:

1. **reset** → start → **running**

2. **running** → pause → **paused** OR add lap → **running** OR auto-complete → **completed**

3. **paused** → resume → **running** OR reset → **reset**

4. **completed** → reset → **reset**

Each state has associated UI colors via `CounterState.modeColor` computed property.

Key Components

**Counter.swift** (ViewModel)

`ObservableObject` coordinating session logic and state management

Manages `CounterState` enum for UI state transitions

Handles timer lifecycle with 0.1s refresh rate for smooth display

Creates and updates CoreData `Session` and `Lap` entities

Tracks timing data (overall time, lap time, pause time)

**CounterView.swift** (Main UI)

Primary stopwatch interface observing Counter state

Contains:

- `BigDisplayView`: Lap progress (completed/remaining)

- `CounterStatsView`: Current/last/average/fastest lap statistics

- `StopwatchView`: Animated analog stopwatch with visual feedback

- State-dependent action buttons (start/pause/resume/lap/reset)

**Data Persistence**

**CoreData** entities: `Session` (1) → (many) `Lap`, plus `Note` and `Photo` support

**DataController.swift**: Manages CoreData stack

**BackupController.swift**: Handles database backups

**@AppStorage via PersistedSettings**: User preferences (lap length, planned laps, feedback settings)

View Structure

TabView with 4 main tabs:

1. **Counter**: Main stopwatch interface

2. **Logbook** (`LogbookView`): Historical session data

3. **Analysis** (`AnalysisView`): Session analytics with charts

4. **Settings** (`SettingsView`): App configuration

Key Patterns

**Environment Objects**: `DataController`, `BackupController`, `RestoreIdentity` injected via `ThisApp.swift`

**@AppStorage**: Persisted user preferences across launches

**Idle Timer Disabled**: Prevents screen sleep during active sessions (`UIApplication.shared.isIdleTimerDisabled = true`)

**Haptic & Sound Feedback**: `HapticFeedback` class for CoreHaptics integration

**Button Debouncing**: 1.0s delay prevents accidental double-taps

**Time Formatting**: `ThisApp.formatTimeInterval()` centralizes formatting logic (shows tenths of seconds for times under 60s)

Development Guidelines

Code Organization

1. **Ignore Legacy Code**: The `__attic__/` directory contains deprecated files. Always use current implementations in main directories.

2. **Use Current Counter.swift**: Do not reference or import patterns from legacy counter implementations.

Working with State

All session state flows through the `CounterState` enum

UI components observe state via `@ObservedObject` or `@StateObject`

State transitions trigger UI updates automatically via SwiftUI bindings

Data Management

Create/update CoreData entities through `Counter.swift` ViewModel

Access managed object context via `DataController` environment object

Use `@AppStorage` via `PersistedSettings` for simple key-value preferences

Timer updates run at 0.1s intervals for smooth display

Commit & Release Process

**IMPORTANT**: Unless explicitly instructed otherwise, on every commit:

1. Update `RELEASE-NOTES.md` with technical changes

2. Update `PUBLIC-RELEASE-NOTES.md` with user-facing changes

3. Update key features list in `README.md` when major features are added

4. Perform a git push

5. **Do NOT include** references to Claude Code as co-author in commit messages

Testing

Build and run in Xcode to verify changes

Test state transitions thoroughly (reset → running → paused → completed)

Verify CoreData persistence after app restart

Check haptic feedback on physical device when modifying feedback logic

Common Tasks

Adding a New Feature

1. Identify which layer requires changes (ViewModel, View, Data)

2. Update `Counter.swift` if session logic is affected

3. Modify appropriate View files for UI changes

4. Update CoreData model if persistence schema changes

5. Add/update `@AppStorage` properties in `PersistedSettings` for new preferences

6. Update documentation files as per commit process above

Modifying State Behavior

1. Review `CounterState` enum in `Counter.swift`

2. Add new state or transition logic

3. Update `modeColor` computed property if visual changes needed

4. Test all state transitions end-to-end

Time Display Changes

Modify `ThisApp.formatTimeInterval()` for centralized time formatting

Current format: "MM:SS.t" for <60s, "MM:SS" for ≥60s

Ensure consistency across all time displays (Counter, Logbook, Analysis)

Important Constraints

**iOS-only target**: Do not introduce macOS, watchOS, or cross-platform dependencies

**SwiftUI required**: All UI must use SwiftUI (no UIKit views)

**Timer precision**: Maintain 0.1s refresh rate for smooth stopwatch display

**Screen timeout**: Keep idle timer disabled during active sessions

**Button debouncing**: Maintain 1.0s debounce on critical actions

LapBuddy iOS Swimming Tracker

LapBuddy iOS Swimming Tracker

Project Structure

Build & Run

Architecture Overview

Core State Machine

Key Components

View Structure

Key Patterns

Development Guidelines

Code Organization

Working with State

Data Management

Commit & Release Process

Testing

Common Tasks

Adding a New Feature

Modifying State Behavior

Time Display Changes

Important Constraints

Reviews (0)