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. Alarm System
- **Multiple alarms**: Create and manage multiple alarms
- **Time selection**: Wheel-style date picker for alarm time
- **Sound selection**: Choose from system sounds (default, bell, chimes, ding, glass, silence)
- **Enable/disable toggles**: Individual alarm control
- **Notification integration**: Uses iOS UserNotifications framework
- **Persistent storage**: Alarms saved to UserDefaults
- **Alarm management**: Add, delete, and modify alarms

## Technical Architecture

### 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
- **Dark theme**: Preferred color scheme set to dark

### Data Models
- **ClockStyle**: Codable struct 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
- **Alarm**: Codable struct for alarm data
  - UUID identifier
  - Time and enabled state
  - Sound name
- **Sound**: Simple struct for noise file management
  - Display name and file name

### 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
- **Looping playback**: Infinite loop for ambient sounds
- **Error handling**: Graceful handling of missing audio files

### Notification System
- **UserNotifications**: iOS notification framework
- **Permission handling**: Automatic permission requests
- **Calendar triggers**: Daily alarm scheduling
- **Sound customization**: System sound selection

## User Interface Design

### Navigation
- **TabView**: Three-tab interface (Clock, Alarms, Noise)
- **NavigationStack**: Modern navigation with back button support
- **Toolbar integration**: Settings and add buttons in navigation bars

### Visual Design
- **Rounded corners**: Modern iOS design language
- **Smooth animations**: 0.28-second easeInOut transitions
- **Color consistency**: Blue accent color throughout
- **Accessibility**: Proper labels and hidden decorative elements

### 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
```
TheNoiseClock/
├── TheNoiseClockApp.swift          # App entry point
├── ContentView.swift               # Main tab navigation
├── ClockView.swift                 # Clock display and settings
├── ClockSettingsView.swift         # Settings interface
├── ClockStyle.swift                # Data model and color utilities
├── AlarmView.swift                 # Alarm management
├── AddAlarmView.swift              # Alarm creation
├── NoiseView.swift                 # White noise player
├── NoisePlayer.swift               # Audio playback logic
├── Sound.swift                     # Sound data model
└── Resources/                      # Audio files
    ├── white-noise.mp3
    ├── heavy-rain-white-noise.mp3
    └── fan-white-noise-heater-303207.mp3
```

## 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
2. **Add alarm**: Tap + button to create new alarm
3. **Toggle alarm**: Use switch to enable/disable
4. **Delete alarm**: Swipe to delete

### 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 15.0+ (SwiftUI features)
- **Target devices**: iPhone and iPad
- **Orientation support**: Portrait and landscape

### Dependencies
- **SwiftUI**: Native iOS UI framework
- **AVFoundation**: Audio playback
- **UserNotifications**: Alarm notifications
- **Combine**: Timer publishers for real-time updates

### Performance Considerations
- **Efficient timers**: Separate timers for seconds and minutes
- **Memory management**: Proper cleanup of audio players
- **Battery optimization**: Efficient update mechanisms
- **Smooth animations**: Hardware-accelerated transitions

## Future Enhancement Opportunities
- **Additional sound types**: More white noise variants
- **Volume control**: Adjustable playback volume
- **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
- **Snooze functionality**: Enhanced alarm features
- **Multiple time zones**: World clock functionality

## Development Notes
- **Created**: September 7, 2025
- **Framework**: SwiftUI with iOS 15+ target
- **Architecture**: MVVM pattern with SwiftUI
- **Testing**: Includes unit and UI test targets
- **Version control**: Git repository with staged changes