Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>

PRD.md

@@ -43,11 +43,17 @@ TheNoiseClock is a SwiftUI-based iOS application that combines a customizable di
 - **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
@@ -72,6 +78,13 @@ TheNoiseClock is a SwiftUI-based iOS application that combines a customizable di
   - 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
@@ -196,32 +209,47 @@ TheNoiseClock/
 │   └── NoiseViewModel.swift        # Audio playback state management
 ├── Views/
 │   ├── Clock/
-│   │   ├── ClockView.swift         # Main clock display
+│   │   ├── ClockView.swift         # Main clock display view
-│   │   ├── ClockSettingsView.swift # Clock settings interface
+│   │   ├── ClockSettingsView.swift # Clock customization interface
 │   │   └── Components/
-│   │       ├── TimeDisplayView.swift    # Time display component
+│   │       ├── TimeDisplayView.swift    # Segmented time display component
-│   │       ├── BatteryOverlayView.swift # Battery display component
+│   │       ├── BatteryOverlayView.swift # Battery level overlay
-│   │       └── DateOverlayView.swift    # Date display component
+│   │       ├── DateOverlayView.swift    # Date display overlay
+│   │       └── TopOverlayView.swift     # Combined overlay container
 │   ├── Alarms/
-│   │   ├── AlarmView.swift         # Alarm list and management
+│   │   ├── AlarmView.swift         # Main alarm management view
 │   │   ├── AddAlarmView.swift      # Alarm creation interface
 │   │   └── Components/
-│   │       ├── AlarmRowView.swift      # Individual alarm row
+│   │       ├── AlarmRowView.swift      # Individual alarm row component
-│   │       ├── TimePickerView.swift    # Time selection component
+│   │       ├── TimePickerSection.swift # Time selection component
-│   │       └── SoundPickerView.swift   # Sound 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         # White noise player interface
+│       ├── NoiseView.swift         # Main white noise player interface
 │       └── Components/
-│           └── SoundControlView.swift  # Audio controls component
+│           ├── 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/
-    ├── Audio/
+    ├── sounds.json                    # Sound configuration and definitions
-    │   ├── white-noise.mp3
+    ├── Ambient.bundle/                # Ambient sound category
-    │   ├── heavy-rain-white-noise.mp3
+    │   └── white-noise.mp3
-    │   └── fan-white-noise-heater-303207.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]
 ```
@@ -241,6 +269,36 @@ TheNoiseClock/
 - **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