LeCountdown/CLAUDE.md

CLAUDE.md

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

Project Overview

LeCountdown is a Swift-based iOS timer application built with SwiftUI that supports countdowns, stopwatches, and alarms. The app features live activities, widgets, CloudKit synchronization, and background execution capabilities.

Build and Development Commands

Building and Running

• Build the app: Use Xcode to build the main LeCountdown target
• Run tests: Execute tests through Xcode Test Navigator or use ⌘+U
• Build widget extension: Build the LaunchWidgetExtension target
• Build intents extension: Build the LaunchIntents target

Xcode Schemes

• LeCountdown: Main app target with Core Data logging disabled
• LaunchWidgetExtension: Widget and Live Activity extension
• LaunchIntents: Siri Shortcuts and App Intents extension

Core Architecture

Data Layer

• Core Data: Primary data persistence using NSPersistentCloudKitContainer
• CloudKit Integration: Automatic sync via iCloud.LeCountdown container
• Shared App Group: group.com.staxriver.countdown for widget/extension data sharing
• Models: Generated Core Data classes in Model/Generation/
  • AbstractTimer (base class), Countdown, Stopwatch, Alarm
  • Activity, Record (for statistics)
  • CustomSound, IntervalGroup

Core Components

• Conductor: Central coordinator (Conductor.swift) managing live timers, sound playback, and background tasks
• LiveTimer: Runtime timer state management
• TimerRouter: Handles timer actions and URL schemes
• SoundPlayer: Audio playback coordination
• PersistenceController: Core Data stack setup with CloudKit

View Architecture

• SwiftUI-based: Modern declarative UI with environment objects
• ContentView: Generic main interface supporting different timer types
• Specialized Views: CountdownDialView, StopwatchDialView, AlarmDialView
• Form Views: CountdownFormView, StopwatchFormView, AlarmFormView

Extensions and Widgets

• Widget: Home screen widgets showing active timers
• Live Activities: Dynamic Island and Lock Screen live updates
• App Intents: Siri integration for timer management
• Background Processing: Uses BGAppRefreshTask for background updates

Key Utilities

• Logger: File-based logging system
• Preferences: UserDefaults wrapper with property wrappers
• Sound Management: Custom sound playback with delay support
• Statistics: Activity tracking and record management

Important Implementation Notes

Core Data Setup

• Uses shared App Group container for data sharing between app and extensions
• CloudKit container ID: iCloud.LeCountdown
• Merge policy: NSMergeByPropertyStoreTrumpMergePolicy
• Automatic migration disabled (manual migrations in data model versions)

Background Execution

• Registers BGAppRefreshTask with identifier com.staxriver.lecountdown.refresh
• Stops audio players when app becomes inactive
• Restores sound players when app becomes active

Widget and Extension Architecture

• Shared data access via App Group container
• Intent definitions for Siri integration
• Live Activities use LaunchWidgetAttributes for Dynamic Island

Sound System

• Multiple sound categories: Nature, Relax, Shorts, Stephan_Bodzin
• Delay-based sound player for timer completion
• State-based audio management with memory warning handling

Subscription Model

• AppGuard manages subscription state
• Store handles in-app purchases
• Subscription UI components integrated throughout

This codebase follows iOS app development best practices with clear separation between data, business logic, and presentation layers. The modular architecture supports extensions, widgets, and background processing while maintaining code clarity and testability.