TheNoiseClock/PRD.md

TheNoiseClock - Product Requirements Document

Overview

TheNoiseClock is a SwiftUI-based iOS application that combines a customizable digital clock display with white noise playback and alarm functionality. The app is designed with a dark theme and focuses on providing a clean, distraction-free interface for time display and ambient sound management.

Core Features

1. Digital Clock Display

• Real-time clock with automatic updates every second
• Customizable time format: 12-hour or 24-hour display
• Optional seconds display with toggle control
• AM/PM badge for 12-hour format (optional)
• Segmented time display with colon separators that adapt to orientation
• Dynamic scaling that fits available screen space
• Portrait and landscape orientation support

2. Clock Customization

• Color customization: User-selectable digit colors with color picker
• Background color: Customizable background with color picker
• Glow effects: Adjustable glow intensity (0-100%)
• Size control: Manual scaling (0-100%) or auto-fit mode
• Opacity controls: Separate opacity for clock digits and overlays
• Random color mode: Automatically changes digit color every minute
• Preset themes: Quick "Night" (black/white) and "Day" (white/black) themes

3. Display Modes

• Normal mode: Standard interface with navigation and settings
• Display mode: Full-screen clock activated by long-press (0.6 seconds)
• Automatic UI hiding: Tab bar and navigation elements hide in display mode
• Smooth transitions: Animated transitions between modes

4. Information Overlays

• Battery level display: Real-time battery percentage with icon
• Date display: Current date in "d MMMM EEE" format (e.g., "7 September Mon")
• Overlay opacity control: Independent opacity for battery/date overlays
• Automatic updates: Battery and date update in real-time

5. White Noise Player

• Multiple sound options:
  • White Noise (white-noise.mp3)
  • Heavy Rain White Noise (heavy-rain-white-noise.mp3)
  • Fan White Noise (fan-white-noise-heater-303207.mp3)
• Continuous playback: Sounds loop indefinitely
• Simple controls: Play/Stop button with visual feedback
• Sound selection: Dropdown picker for sound selection

6. Advanced Alarm System

• Multiple alarms: Create and manage unlimited alarms
• Rich alarm editor: Full-featured alarm creation and editing interface
• Time selection: Wheel-style date picker for precise alarm time
• Custom labels: User-defined alarm names and descriptions
• Repeat schedules: Set alarms to repeat on specific weekdays or daily
• Sound selection: Choose from extensive system sounds with live preview
• Volume control: Adjustable alarm volume (0-100%)
• Vibration settings: Enable/disable vibration for each alarm
• Snooze functionality: Configurable snooze duration (5, 7, 8, 9, 10, 15, 20 minutes)
• Smart notifications: Automatic scheduling for one-time and repeating alarms
• Enable/disable toggles: Individual alarm control with instant feedback
• Notification integration: Uses iOS UserNotifications framework with proper scheduling
• Persistent storage: Alarms saved to UserDefaults with backward compatibility
• Alarm management: Add, edit, delete, and duplicate alarms
• Next trigger preview: Shows when the next alarm will fire

Technical Architecture

Code Organization Principles

TOP PRIORITY: The codebase must be built with the following architectural principles from the beginning:

• True Separation of Concerns:

  • Many small files with focused responsibilities
  • Each module/class should have a single, well-defined purpose
  • Avoid monolithic files with mixed responsibilities

• Constants and Enums:

  • Create constants, enums, and configuration objects to avoid duplicate code or values
  • Centralize magic numbers, strings, and configuration values
  • Use enums for type safety and clarity

• Readability and Maintainability:

  • Code should be self-documenting with clear naming conventions
  • Easy to understand, extend, and refactor
  • Consistent patterns throughout the codebase

• Extensibility:

  • Design for future growth and feature additions
  • Modular architecture that allows easy integration of new components
  • Clear interfaces between modules

• Refactorability:

  • Code structure should make future refactoring straightforward
  • Minimize coupling between components
  • Use dependency injection and abstraction where appropriate

These principles are fundamental to the project's long-term success and must be applied consistently throughout development.

App Structure

• Main App: TheNoiseClockApp.swift - Entry point with WindowGroup
• Tab-based navigation: Three main tabs (Clock, Alarms, Noise)
• SwiftUI framework: Modern declarative UI framework with iOS 18+ and iOS 26 features
• Dark theme: Preferred color scheme set to dark

Data Models

• ClockStyle: @Observable class for clock customization settings
  • Time format preferences (24-hour, seconds, AM/PM)
  • Visual settings (colors, glow, scale, opacity)
  • Overlay settings (battery, date, opacity)
  • Background settings
  • Color caching for performance optimization
• Alarm: Codable struct for comprehensive alarm data
  • UUID identifier
  • Time and enabled state
  • Custom label and description
  • Repeat schedule (weekdays)
  • Sound name with volume control
  • Vibration settings
  • Snooze duration configuration
• Sound: Simple struct for noise file management
  • Display name and file name
• LegacyAlarm: Backward compatibility struct for old alarm data

Data Persistence

• AppStorage: ClockStyle settings persisted as JSON
• UserDefaults: Alarm data persisted as JSON
• Bundle resources: Audio files stored in app bundle

Audio System

• AVFoundation: AVAudioPlayer for noise playback
• @Observable NoisePlayer: Modern state management with preloading
• Looping playback: Infinite loop for ambient sounds
• Audio session management: Proper audio session configuration
• Error handling: Graceful handling of missing audio files
• AlarmTonePlayer: Dedicated player for alarm sound previews

Notification System

• UserNotifications: iOS notification framework
• Permission handling: Automatic permission requests
• Smart scheduling: One-time and repeating alarm support
• Calendar triggers: Precise alarm scheduling with weekday support
• Sound customization: System sound selection with volume control
• Multiple notifications: Support for repeating alarms with unique identifiers

User Interface Design

Navigation

• TabView: Three-tab interface (Clock, Alarms, Noise)
• NavigationStack: Modern navigation with back button support
• Navigation destinations: Deep linking for alarm editing
• Toolbar integration: Settings and add buttons in navigation bars
• Sheet presentations: Modal settings and alarm creation

Visual Design

• Rounded corners: Modern iOS design language
• Modern animations: iOS 18+ smooth and bouncy animations
• Color consistency: Blue accent color throughout
• Accessibility: Proper labels and hidden decorative elements
• Form-based layouts: Organized sections for settings and alarm editing
• Interactive controls: Toggles, sliders, color pickers, and date pickers

Settings Interface

• Form-based layout: Organized sections for different setting categories
• Interactive controls: Toggles, sliders, color pickers
• Real-time updates: Changes apply immediately
• Sheet presentation: Modal settings with detents

File Structure and Organization

Recommended File Organization

Following the separation of concerns principle, the codebase should be organized into focused, single-responsibility files:

TheNoiseClock/
├── App/
│   ├── TheNoiseClockApp.swift      # App entry point and configuration
│   └── ContentView.swift           # Main tab navigation coordinator
├── Core/
│   ├── Constants/
│   │   ├── AppConstants.swift      # App-wide constants and configuration
│   │   ├── UIConstants.swift       # UI-specific constants (colors, sizes, etc.)
│   │   └── AudioConstants.swift    # Audio-related constants
│   ├── Extensions/
│   │   ├── Color+Extensions.swift  # Color utilities and extensions
│   │   ├── Date+Extensions.swift   # Date formatting and utilities
│   │   └── View+Extensions.swift   # Common view modifiers
│   └── Utilities/
│       ├── ColorUtils.swift        # Color manipulation utilities
│       └── NotificationUtils.swift # Notification helper functions
├── Models/
│   ├── ClockStyle.swift            # Clock customization data model
│   ├── Alarm.swift                 # Alarm data model
│   ├── Sound.swift                 # Sound data model
│   └── LegacyAlarm.swift           # Backward compatibility model
├── ViewModels/
│   ├── ClockViewModel.swift        # Clock display logic and state
│   ├── AlarmViewModel.swift        # Alarm management logic
│   └── NoiseViewModel.swift        # Audio playback state management
├── Views/
│   ├── Clock/
│   │   ├── ClockView.swift         # Main clock display
│   │   ├── ClockSettingsView.swift # Clock settings interface
│   │   └── Components/
│   │       ├── TimeDisplayView.swift    # Time display component
│   │       ├── BatteryOverlayView.swift # Battery display component
│   │       └── DateOverlayView.swift    # Date display component
│   ├── Alarms/
│   │   ├── AlarmView.swift         # Alarm list and management
│   │   ├── AddAlarmView.swift      # Alarm creation interface
│   │   └── Components/
│   │       ├── AlarmRowView.swift      # Individual alarm row
│   │       ├── TimePickerView.swift    # Time selection component
│   │       └── SoundPickerView.swift   # Sound selection component
│   └── Noise/
│       ├── NoiseView.swift         # White noise player interface
│       └── Components/
│           └── SoundControlView.swift  # Audio controls component
├── Services/
│   ├── NoisePlayer.swift           # Audio playback service
│   ├── AlarmService.swift          # Alarm management service
│   └── NotificationService.swift   # Notification handling service
└── Resources/
    ├── Audio/
    │   ├── white-noise.mp3
    │   ├── heavy-rain-white-noise.mp3
    │   └── fan-white-noise-heater-303207.mp3
    └── Assets.xcassets/
        └── [Asset catalogs]

File Naming Conventions

• Views: Use descriptive names ending in View (e.g., ClockView, AlarmRowView)
• ViewModels: End with ViewModel (e.g., ClockViewModel, AlarmViewModel)
• Services: End with Service (e.g., AlarmService, NotificationService)
• Models: Use noun names (e.g., Alarm, Sound, ClockStyle)
• Extensions: Use Type+Extensions format (e.g., Color+Extensions)
• Constants: Use descriptive names ending in Constants (e.g., AppConstants)

Code Organization Best Practices

• Single Responsibility: Each file should have one clear purpose
• Dependency Injection: Use protocols and dependency injection for testability
• Protocol-Oriented Design: Define protocols for services and data sources
• Error Handling: Centralized error types and handling patterns
• Testing: Separate test targets with comprehensive coverage

Key User Interactions

Clock Tab

1. View time: Real-time clock display
2. Access settings: Tap gear icon in navigation bar
3. Enter display mode: Long-press anywhere on clock (0.6 seconds)
4. Exit display mode: Long-press again to return to normal mode

Settings

1. Time format: Toggle 24-hour, seconds, AM/PM display
2. Appearance: Adjust colors, glow, size, opacity
3. Overlays: Control battery and date display
4. Background: Set background color and use presets

Alarms Tab

1. View alarms: List of all created alarms with labels and repeat schedules
2. Add alarm: Tap + button to create new alarm with full editor
3. Edit alarm: Tap any alarm to open comprehensive editor
4. Toggle alarm: Use switch to enable/disable
5. Delete alarm: Swipe to delete or use delete button in editor
6. Alarm editor features:
   • Time picker with next trigger preview
   • Custom label editing
   • Repeat schedule selection
   • Sound picker with live preview
   • Volume and vibration controls
   • Snooze duration settings

Noise Tab

1. Select sound: Choose from dropdown menu
2. Play/Stop: Single button to control playback
3. Continuous playback: Sounds loop until stopped

Technical Requirements

iOS Compatibility

• Minimum iOS version: iOS 18.0+ (Latest SwiftUI features and performance optimizations)
• Target devices: iPhone and iPad with full adaptive layout support
• Orientation support: Portrait and landscape with dynamic type support
• Accessibility: Full VoiceOver and Dynamic Type support

Modern iOS Technology Stack

• SwiftUI: Latest declarative UI framework with iOS 18+ and iOS 26 features
• Observation Framework: Modern @Observable pattern for state management
• SwiftData: Advanced data persistence with iOS 18+ SwiftData features
• Async/Await: Modern concurrency patterns throughout
• Structured Concurrency: Task groups and actors for complex operations
• Swift 6: Latest language features and safety improvements
• iOS 26 Features: Latest platform capabilities where available

Dependencies

• SwiftUI: Native iOS UI framework with latest features
• AVFoundation: Audio playback with modern async patterns
• UserNotifications: Alarm notifications with rich content support
• Combine: Timer publishers and reactive programming
• Observation: Modern state management with @Observable
• Foundation: Core system frameworks and utilities

Performance Considerations

• Smart timer management: Conditional timers based on settings
• Debounced persistence: Batched UserDefaults writes
• Memory management: Proper cleanup of audio players
• Battery optimization: Efficient update mechanisms
• Color caching: Avoid repeated hex-to-Color conversions
• Dictionary lookups: O(1) alarm access instead of linear search
• Smooth animations: Hardware-accelerated transitions
• Preloaded audio: Instant sound playback

Future Enhancement Opportunities

• Additional sound types: More white noise variants
• Sleep timer: Auto-stop noise after specified time
• Widget support: Home screen clock widget
• Apple Watch companion: Watch app for quick time check
• In-app purchases: Premium sound packs
• Custom sounds: User-imported audio files
• Multiple time zones: World clock functionality
• Alarm categories: Group alarms by type (work, sleep, etc.)
• Smart alarms: Gradual volume increase
• Weather integration: Weather-based alarm sounds
• Health integration: Sleep tracking integration

Development Notes

Project Information

• Created: September 7, 2025
• Framework: SwiftUI with iOS 18.0+ target (latest stable features)
• Architecture: Modern SwiftUI with @Observable pattern and MVVM
• Testing: Comprehensive unit and UI test targets with Swift Testing
• Version control: Git repository with feature branch workflow
• Performance: Optimized for battery life and smooth operation
• Modern iOS: Uses latest iOS 18+ and iOS 26 features with Swift 6 language improvements

Modern iOS Development Practices

• Swift 6: Latest language features including strict concurrency checking
• Async/Await: Modern concurrency patterns throughout the codebase
• Observation Framework: @Observable for reactive state management
• SwiftUI Navigation: Latest NavigationStack and navigation APIs with iOS 18+ features
• Accessibility: Full VoiceOver and Dynamic Type support with iOS 26 enhancements
• Adaptive Layout: Support for all device sizes and orientations
• Performance: Optimized for 120Hz ProMotion displays and iOS 26 performance improvements
• Memory Management: ARC with proper weak references and cleanup
• Error Handling: Result types and proper error propagation
• Testing: Swift Testing framework for modern test writing
• iOS 26 Integration: Latest platform features and capabilities where applicable

Code Quality Standards

• SwiftLint: Automated code style enforcement
• Documentation: Comprehensive inline documentation with DocC
• Type Safety: Leverage Swift's type system for compile-time safety
• Protocol-Oriented: Use protocols for abstraction and testability
• Dependency Injection: Constructor injection for better testability
• SOLID Principles: Single responsibility, open/closed, dependency inversion