How pitt500/clockapp works
1. Repo shape and targets
- This is an iOS app built with SwiftUI, Swift Concurrency, and ActivityKit/Live Activities.
- It has three relevant targets: the main ClockApp app, the TimerLiveActivity extension for lock screen/Dynamic Island UI, and ClockAppTests for behavior/integration coverage.
2. App entry and screen composition
- ClockApp.swift is the app entry point and routes into RootView.
- The main timer experience lives in TimersScreen, with a UIKit bridge in TimersScreenUIKit where needed.
- The screen layer is mostly presentation-only: it renders timers, detail views, and controls, but does not own business logic.
3. Central orchestration layer
- TimersStore is the app’s state/workflow hub.
- It owns the user-facing state: active timers, recent timers, and the current draft/input state.
- All user actions funnel through this store, which coordinates timer execution, persistence, and Live Activity updates.
4. Timer execution engine
- TimerManager is the countdown engine.
- It models timer lifecycle states such as running, paused, and idle, and computes remaining time from an endDate rather than decrementing a counter.
- This makes the countdown resilient to delays, backgrounding, and rendering jitter.
- Completion is callback-driven, so the store can react when a timer finishes.
5. Domain model boundaries
- The domain layer defines the core timer abstractions: TimerItem, TimerProgressSnapshot, and provider protocols.
- TimerProgressProviding and TimerDetailProviding describe what the UI needs without binding it to concrete timer logic.
- TimerRowProgressProviderFromManager and TimerDetailProviderFromManager adapt the manager into those domain-facing views of state.
6. Persistence boundary
- FileTimersPersistence implements TimersPersistence and stores timer recents on disk as a file-backed model.
- The repo explicitly separates recents from active timers: recents are persisted, active timers are ephemeral runtime state.
- This keeps the persistence model simple and avoids trying to serialize live execution state.
7. Live Activity policy and adapter layers
- Live Activities are split into two pieces:
- TimerLiveActivityPrioritizer decides which timer should be surfaced when multiple timers exist.
- TimerActivityController performs the ActivityKit operations to start, update, and end the activity.
- NoopTimerActivityHandler provides a safe non-system or disabled behavior path.
- This separation keeps “which timer matters” distinct from “how to talk to ActivityKit.”
8. System integration via App Intents
- TimerAlertCommandCenter and TimerLiveActivityCommandCenter act as command surfaces for timer-related system actions.
- These are the bridge points for triggering alerts and Live Activity behavior from outside the main SwiftUI flow.
- The architecture treats them as integration adapters rather than core business logic.
9. Shared Live Activity rendering
- TimerAttributes and the views under Timers/Shared/Views are shared between the app and the Live Activity extension.
- These include lock screen and Dynamic Island-specific UI pieces such as compact time, progress rings, control buttons, and timer titles.
- Shared formatting helpers keep the app and extension visually and behaviorally aligned.
10. TimerLiveActivity extension boundary
- The TimerLiveActivity target is a separate widget-style extension package that renders system surfaces.
- TimerLiveActivityBundle and TimerLiveActivityConfiguration define the extension entry and configuration.
- This target is responsible only for system presentation; it does not own timer state or persistence.
11. Assets and runtime assumptions
- The app includes a custom alarm sound (alarm_pitt.caf) and standard asset catalogs for app icon, accent color, and widget background.
- The project targets modern iOS behavior: iOS 18+, Swift 6, and Live Activities on physical devices.
- These platform constraints materially shape the architecture because Live Activities and ActivityKit are first-class system integration points.
12. Testing strategy
- Tests focus on behavior: timer countdown logic, store workflows, Live Activity prioritization, and integration scenarios with real time delays.
- ClockAppTests exercises the architecture at subsystem boundaries, which reflects the repo’s emphasis on system design over UI snapshot testing.
13. Primary data flow
- User interaction begins in TimersScreen.
- The UI dispatches actions into TimersStore.
- The store coordinates TimerManager for time progression, FileTimersPersistence for recents, and TimerActivityController for Live Activity updates.
- When a timer completes, the manager notifies the store, which then finalizes state and updates system surfaces.
14. Architectural theme
- The codebase is organized around clear separation of concerns: presentation, orchestration, domain, persistence, and system integration.
- The main diagram should emphasize that the app is not “just a screen”; it is a timer coordination system with a dedicated execution engine and a separate system-UI extension.
Main entry points: TimersStore.swift Timers store · TimerManager.swift Timer manager · TimerActivityController.swift Activity controller · TimersScreen.swift Timers screen
Components 27
ClockApp
Main iOS app target and presentation layer
Timers
Core timer feature split into domain, orchestration, persistence, and shared integrations
- Timers screen · Primary timer experience and presentation surface.
ClockApp/Timers/Presentation/Views/TimersScreen.swift - UIKit bridge · UIKit-backed bridge used where SwiftUI needs platform interop.
ClockApp/Timers/Presentation/Views/TimersScreenUIKit.swift - Timers store · Central orchestration for active timers, recents, draft state, persistence, and system updates.
ClockApp/Timers/Presentation/State/TimersStore.swift - Timer manager · Tracks running, paused, and idle timers using end dates and completion callbacks.
ClockApp/Timers/Presentation/Logic/TimerManager.swift - Timer item · Core timer entity used across the feature.
ClockApp/Timers/Domain/Entities/TimerItem.swift - Progress snapshot · Immutable timer progress state for rendering and coordination.
ClockApp/Timers/Domain/Entities/TimerProgressSnapshot.swift - Progress provider · UI-facing contract for row progress data.
ClockApp/Timers/Domain/Interfaces/TimerProgressProviding.swift - Detail provider · UI-facing contract for timer detail data.
ClockApp/Timers/Domain/Interfaces/TimerDetailProviding.swift - Row provider · Adapts the manager into row progress state.
ClockApp/Timers/Domain/Entities/TimerRowProgressProviderFromManager.swift - Detail adapter · Adapts the manager into timer detail state.
ClockApp/Timers/Domain/Entities/TimerDetailProviderFromManager.swift - Timers persistence · Boundary for storing timer recents.
ClockApp/Timers/Data/Persistence/TimersPersistence.swift - File storage · Disk-backed implementation for recent timers.
ClockApp/Timers/Data/Persistence/FileTimersPersistence.swift - Prioritizer · Chooses which timer should be surfaced to Live Activities.
ClockApp/Timers/Data/Activities/TimerLiveActivityPrioritizer.swift - Activity controller · Starts, updates, and ends Live Activities.
ClockApp/Timers/Data/Activities/TimerActivityController.swift - No-op handler · Disabled or non-system path for activity handling.
ClockApp/Timers/Data/Activities/NoopTimerActivityHandler.swift - Alert commands · System command surface for timer alert actions.
ClockApp/Timers/Shared/AppIntents/TimerAlertCommandCenter.swift - Live Activity cmds · System command surface for Live Activity actions.
ClockApp/Timers/Shared/AppIntents/TimerLiveActivityCommandCenter.swift - Timer attributes · Shared ActivityKit attributes and state definitions.
ClockApp/Timers/Shared/LiveActivities/TimerAttributes.swift - Shared views · Shared rendering for lock screen, Dynamic Island, and app-aligned timer visuals.
ClockApp/Timers/Shared/Views/LockScreenTimerLiveActivityView.swift
Live Activity
Widget-style extension for lock screen and Dynamic Island surfaces
- Activity bundle · Widget extension entry point for Live Activity surfaces.
TimerLiveActivity/TimerLiveActivityBundle.swift - Activity config · Configures the Live Activity extension presentation.
TimerLiveActivity/TimerLiveActivityConfiguration.swift
Tests
Behavior and integration coverage
- Manager tests · Covers countdown lifecycle and timing behavior.
ClockAppTests/TimerManagerTests.swift - Manager integration · Exercises timer manager behavior across real timing scenarios.
ClockAppTests/TimerManagerIntegrationTests.swift - Store tests · Validates recents and active timer workflow boundaries.
ClockAppTests/TimersStoreRecentsAndActivesTests.swift - Activity tests · Covers Live Activity coordination and prioritization behavior.
ClockAppTests/TimerLiveActivityCoordinatorTests.swift
Connections 28
- App entry → Root view: boots · App entry composes the root view.
- Root view → Timers screen: hosts · Root view presents the main timers screen.
- Timers screen → Timers store: dispatches · User actions flow into the orchestration store.
- Timers screen → UIKit bridge: bridges · SwiftUI uses UIKit where needed.
- Timers store → Timer manager: controls · Store coordinates timer execution and lifecycle.
- Timers store → Timers persistence: persists recents · Store saves and restores recent timers through the persistence boundary.
- Timers store → Activity controller: updates · Store drives Live Activity updates.
- Timers store → Alert commands: exposes · Store-integrated command surface for alert actions.
- Timers store → Live Activity cmds: exposes · Store-integrated command surface for Live Activity actions.
- Timer manager → Timer item: executes · Manager operates on timer domain items.
- Timer manager → Progress snapshot: produces · Manager computes current progress state.
- Timer manager → Row provider: adapts to · Row-facing progress is provided from the manager.
- Timer manager → Detail adapter: adapts to · Detail-facing state is provided from the manager.
- Row provider → Progress provider: implements · Adapter fulfills the row progress contract.
- Detail adapter → Detail provider: implements · Adapter fulfills the detail contract.
- File storage → Timers persistence: implements · File-backed storage implements the persistence boundary.
- Activity controller → Prioritizer: uses · Controller relies on prioritization to choose the surfaced timer.
- Activity controller → Timer attributes: drives · ActivityKit operations are built around shared attributes.
- Activity controller → Shared views: renders · Controller feeds shared Live Activity UI surfaces.
- Activity controller → No-op handler: falls back to · Safe no-op path when activity handling is disabled or unavailable.
- Shared views → Timer attributes: binds to · Shared views consume the Live Activity model.
- Activity bundle → Activity config: configures · Extension bundle owns the configuration entry.
- Activity config → Shared views: renders · Extension configuration uses shared UI components.
- Manager tests → Timer manager: verifies · Tests cover countdown lifecycle behavior.
- Manager integration → Timer manager: verifies · Integration tests cover real-time manager behavior.
- Store tests → Timers store: verifies · Tests cover store workflow and state boundaries.
- Activity tests → Prioritizer: verifies · Tests cover which timer is surfaced.
- Activity tests → Activity controller: verifies · Tests cover ActivityKit coordination behavior.