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
• JSON-based configuration: Sound definitions loaded from external configuration
• Bundle organization: Sounds organized in category-based bundles
• Shared audio player: Singleton pattern prevents audio conflicts

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
• Dynamic alarm sounds: Configurable alarm sounds loaded from JSON configuration
• Sound preview: Play/stop functionality for testing alarm sounds before selection
• Sound organization: Alarm sounds organized in bundles with categories
• 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

• View Structure Requirements:

  • Single View Per File: Each SwiftUI view must be in its own file
  • No Nested Views: Views should not contain other view structs/classes in the same file
  • Component Extraction: Complex views must be broken down into smaller, reusable components
  • Clean Main Views: Main view files should only contain the primary view logic and helper methods
  • Component Organization: Supporting views should be placed in appropriate Components/ subdirectories

• 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 view
│   │   ├── ClockSettingsView.swift # Clock customization interface
│   │   └── Components/
│   │       ├── TimeDisplayView.swift    # Segmented time display component
│   │       ├── BatteryOverlayView.swift # Battery level overlay
│   │       ├── DateOverlayView.swift    # Date display overlay
│   │       └── TopOverlayView.swift     # Combined overlay container
│   ├── Alarms/
│   │   ├── AlarmView.swift         # Main alarm management view
│   │   ├── AddAlarmView.swift      # Alarm creation interface
│   │   └── Components/
│   │       ├── AlarmRowView.swift      # Individual alarm row component
│   │       ├── TimePickerSection.swift # Time selection component
│   │       ├── TimeUntilAlarmSection.swift # Time calculation display
│   │       ├── SoundSelectionView.swift   # Sound selection with preview
│   │       ├── LabelEditView.swift       # Label editing interface
│   │       └── SnoozeSelectionView.swift # Snooze duration selection
│   └── Noise/
│       ├── NoiseView.swift         # Main white noise player interface
│       └── Components/
│           ├── SoundPickerView.swift    # Sound selection component
│           └── SoundControlView.swift   # Playback controls component
├── Services/
│   ├── NoisePlayer.swift           # Audio playback service
│   ├── AlarmService.swift          # Alarm management service
│   └── NotificationService.swift   # Notification handling service
└── Resources/
    ├── sounds.json                    # Sound configuration and definitions
    ├── Ambient.bundle/                # Ambient sound category
    │   └── white-noise.mp3
    ├── Nature.bundle/                 # Nature sound category
    │   └── heavy-rain-white-noise.mp3
    ├── Mechanical.bundle/             # Mechanical sound category
    │   └── fan-white-noise-heater.mp3
    ├── AlarmSounds.bundle/            # Alarm sound category
    │   ├── digital-alarm.mp3
    │   ├── iphone-alarm.mp3
    │   ├── classic-alarm.mp3
    │   ├── beep-alarm.mp3
    │   ├── siren-alarm.mp3
    │   └── voice-wakeup.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

Documentation Maintenance Requirements

CRITICAL: The PRD must be kept up-to-date with all code changes. The following procedures are mandatory:

Automatic PRD Updates

• Every code change that affects architecture, features, or file structure MUST include a corresponding PRD update
• AI Assistant Responsibility: When making code changes, the AI assistant must automatically:
  1. Identify PRD sections that need updating based on the changes made
  2. Update relevant sections without being asked
  3. Add new features to the appropriate feature sections
  4. Update file structure when new files or components are created
  5. Document new requirements or architectural decisions
  6. Maintain consistency between code and documentation

PRD Update Triggers

The following changes automatically require PRD updates:

• New files or components → Update file structure section
• New features or functionality → Update core features section
• Architectural changes → Update code organization principles
• New services or models → Update technical architecture
• UI/UX changes → Update user interaction sections
• Configuration changes → Update technical requirements
• Bundle or resource changes → Update resources section

Documentation Standards

• Real-time updates: PRD updates should happen in the same conversation as code changes
• Comprehensive coverage: All aspects of changes must be documented
• Version consistency: Code and documentation must always be in sync
• No manual requests: Users should not need to ask for PRD updates

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