refactored PRD to be Platform Agnostic

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

docs/PRD.md

@@ -1,122 +1,205 @@
-# 🎤 Karaoke Web App — Product Requirements Document (PRD)
+# 🎤 Karaoke App — Product Requirements Document (PRD)
+
+---
+
+> **Note:** This PRD is structured for platform-agnostic use. Each feature is described with platform-independent requirements, followed by a 'Web Implementation Details' section for web-specific behaviors. For future platforms (iOS, Android, etc.), add corresponding implementation details under each feature. This ensures the PRD can be used as the single source of truth for any platform.
 
 ---
 
 ## 1️⃣ Purpose
 
-This document defines the functional, technical, and UX requirements for the Karaoke Web App, designed for **in-home party use**.  
+This document defines the functional, technical, and UX requirements for the Karaoke App, designed for **in-home party use**. The app leverages **Firebase Realtime Database** for real-time synchronization, with all business logic and validation handled **client-side**.
-The app leverages **Firebase Realtime Database** for real-time synchronization, with all business logic and validation handled **client-side**.
 
 ---
 
 ## 2️⃣ Scope & Business Objectives
 
-- 🎯 Deliver a single-session karaoke experience where users connect to a controller and manage/search songs.  
+- Deliver a single-session karaoke experience where users connect to a controller and manage/search songs.
-- ✅ Use Firebase for real-time multi-user sync of queues, history, and playback state.  
+- Use Firebase for real-time multi-user sync of queues, history, and playback state.
-- ✅ Prioritize fast performance, reusable modular architecture, and clear business logic separation.  
+- Prioritize fast performance, reusable modular architecture, and clear business logic separation.
-- ✅ Enable adding songs from multiple entry points (search, history, top played, favorites, new songs, artists, song lists).  
+- Enable adding songs from multiple entry points (search, history, top played, favorites, new songs, artists, song lists).
-- ✅ Ensure graceful handling of Firebase sync issues using retry patterns and partial node updates.
+- Ensure graceful handling of Firebase sync issues using retry patterns and partial node updates.
-- ✅ True Separation of Concerns - UI components only handle presentation
+- True Separation of Concerns - UI components only handle presentation
-- ✅ Reusable Business Logic - Hooks can be used across components
+- Reusable Business Logic - Hooks can be used across components
-- ✅ Testable Code - Business logic separated from UI
+- Testable Code - Business logic separated from UI
-- ✅ Maintainable - Changes to logic don't affect UI
+- Maintainable - Changes to logic don't affect UI
-- ✅ Performance - Memoized selectors and optimized hooks
+- Performance - Memoized selectors and optimized hooks
-- ✅ Type Safety - Full TypeScript coverage throughout
+- Type Safety - Full TypeScript coverage throughout
-- ✅ The codebase needs to follow the Single Responsibility Principle perfectly - each file has one clear purpose!
+- The codebase needs to follow the Single Responsibility Principle perfectly - each file has one clear purpose!
 
 ---
 
 ## 3️⃣ User Roles & Permissions
 
-| Role         | Search Songs | Add Songs | Delete Songs | Reorder Queue | Playback Control | Manage Singers | View All Features |
+**Requirements (Platform-Agnostic):**
-|--------------|---------------|-----------|--------------|----------------|------------------|----------------|-------------------|
+- Two roles: Host/Admin and Singer/User.
-| **Host/Admin** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+- Only admins can reorder or delete queue items, control playback, and manage singers.
-| **Singer/User** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
+- Admin access is a privileged mode (see platform details for how it's triggered).
+- First queue item cannot be deleted while playing (only when stopped/paused).
+- Singers are automatically added to the singers list when they join.
 
-**Additional Permissions:**
+**Web Implementation Details:**
-- **Admin Access:** Available via URL parameter `?admin=true`
+- Admin access is triggered by a URL parameter (`?admin=true`) and removed from the URL after login.
-- **Queue Management:** Only admins can reorder queue items using up/down arrows
+- Session is lost on browser reload.
-- **First Item Protection:** First queue item cannot be deleted while playing (only when stopped/paused)
-- **Singer Auto-Add:** Singers are automatically added to the singers list when they join
 
 ---
 
 ## 4️⃣ Feature Overview
 
-### **Authentication & Session Management:**
+### Authentication & Session Management
-- **Login Flow:** Simple form-based authentication with Party ID and singer name
+**Requirements (Platform-Agnostic):**
-- **Admin Mode:** Special admin access via URL parameter with enhanced privileges
+- Login requires both Party ID and singer name.
-- **Session Persistence:** Authentication state managed in Redux with automatic logout on page reload
+- Party ID is validated against the backend before login is allowed.
-- **Controller Connection:** Users connect to specific controller/party sessions
+- Authentication state is managed in the app state and lost on app reload (unless platform supports persistence).
 
-### **Search:**  
+**Web Implementation Details:**
-- **Local Search:** Redux-managed search on preloaded song catalog
+- Admin access via URL parameter (`?admin=true`), removed after login.
-- **Real-time Results:** Instant search results as user types
+- Session is lost on browser reload.
-- **Infinite Scroll:** Paginated results with automatic loading
-- **Context Actions:** Common song item view with context-based action panel
 
-### **Queue Management:**  
+### Search
-- **Real-time Sync:** Shared queue synchronized across all connected clients
+**Requirements (Platform-Agnostic):**
-- **Admin Controls:** Only admins can reorder using up/down arrow buttons
+- Local search on preloaded song catalog.
-- **User Actions:** All users can delete songs (except first item when playing)
+- Instant search results as user types.
-- **Order Management:** Sequential order system with automatic cleanup of inconsistent keys
+- Paginated/infinite scroll results.
-- **Duplicate Prevention:** Based on `path` field of each song
+- Context actions for each song (add to queue, favorite, etc).
-- **Singer Attribution:** Each queue item shows which singer added it
 
-### **Favorites:**  
+**Web Implementation Details:**
-- **Real-time Sync:** Shared favorites list synchronized across all clients
+- Uses Ionic InfiniteScrollList for pagination.
-- **Universal Access:** Anyone can add/remove favorites
-- **Duplicate Prevention:** Based on `path` field of each song
-- **Infinite Scroll:** Paginated display with automatic loading
 
-### **New Songs:**  
+### Queue Management
-- **Latest Additions:** Shows recently added songs from the `newSongs` node
+**Requirements (Platform-Agnostic):**
-- **Real-time Updates:** Automatically syncs when new songs are added
+- Shared queue synchronized across all clients.
-- **Infinite Scroll:** Paginated display with automatic loading
+- Queue items must always use sequential numerical keys (0, 1, 2, ...).
+- The system must automatically fix any inconsistencies in order values or keys on every update.
+- Queue reordering must be atomic; when two items are swapped, both order values are updated in a single operation.
+- Only admins can reorder or delete queue items, and only when playback is stopped or paused.
+- Duplicate songs are prevented in the queue by checking the song’s `path`.
+- Each queue item shows which singer added it.
 
-### **Artists:**  
+**Web Implementation Details:**
-- **Artist Browse:** Browse songs by artist with search functionality
+- Queue reordering and deletion are exposed via UI controls only visible to admins.
-- **Modal View:** Click artist to see all their songs in a modal
+- UI uses drag handles and swipe actions (Ionic components) for reordering and deletion.
-- **Song Count:** Shows number of songs per artist
-- **Infinite Scroll:** Paginated artist list with automatic loading
 
-### **Song Lists:**  
+### Favorites
-- **Predefined Lists:** Curated song lists with specific themes or collections
+**Requirements (Platform-Agnostic):**
-- **Song Matching:** Automatically matches list songs to available catalog
+- Shared favorites list synchronized across all clients.
-- **Expandable View:** Click to expand and see available song versions
+- Anyone can add/remove favorites.
-- **Modal Interface:** Full-screen modal for viewing list contents
+- Duplicate prevention by song `path`.
-- **Availability Status:** Shows which songs are available in the catalog
+- Paginated/infinite scroll display.
 
-### **History Tracking:**  
+**Web Implementation Details:**
-- **Play History:** Songs automatically added to history when played
+- Uses Ionic InfiniteScrollList for pagination.
-- **Date Display:** Shows when each song was last played
-- **Append-only:** History is append-only, shared across all clients
-- **Infinite Scroll:** Paginated display with automatic loading
 
-### **Top Played:**  
+### New Songs
-- **Popular Songs:** Generated by Firebase Cloud Function based on history
+**Requirements (Platform-Agnostic):**
-- **Play Count:** Shows number of times each song has been played
+- Shows recently added songs from the `newSongs` node.
-- **Real-time Updates:** Automatically updates when new plays are recorded
+- Real-time updates and infinite scroll.
-- **Infinite Scroll:** Paginated display with automatic loading
 
-### **Singer Management:**  
+**Web Implementation Details:**
-- **Admin Control:** Only admins can add/remove singers
+- Uses Ionic InfiniteScrollList for pagination.
-- **Auto-Add:** Singers automatically added when they join the session
-- **View Access:** All users can view the current singers list
-- **Last Login:** Tracks when each singer last joined
 
-### **Playback Control:**  
+### Artists
-- **Admin Only:** Playback controls only visible to admin users
+**Requirements (Platform-Agnostic):**
-- **State Sync:** Playback state synced to all clients using the `player.state` node
+- Browse songs by artist with search functionality.
-- **Player States:** Playing, Paused, Stopped (mapped to PlayerState enum)
+- Modal view for all songs by an artist.
-- **Queue Integration:** Controls work with the current queue
+- Song count per artist.
+- Paginated/infinite scroll artist list.
 
-### **Error Handling & Sync:**  
+**Web Implementation Details:**
-- **Retry Patterns:** Graceful handling of Firebase sync failures
+- Uses Ionic modals and InfiniteScrollList.
-- **Full Load:** Complete controller object loaded on initial connection
+
-- **Incremental Updates:** Subsequent updates target specific child nodes
+### Song Lists
-- **Connection Status:** Real-time connection status monitoring
+**Requirements (Platform-Agnostic):**
-- **Empty State Handling:** Graceful handling of missing or empty data
+- Predefined song lists with themes/collections.
+- Song matching to catalog.
+- Expandable view for available versions.
+- Modal interface for viewing list contents.
+- Shows which songs are available in the catalog.
+
+**Web Implementation Details:**
+- Uses Ionic modals and InfiniteScrollList.
+
+### History Tracking
+**Requirements (Platform-Agnostic):**
+- Songs automatically added to history when played.
+- Shows when each song was last played.
+- Append-only, shared across all clients.
+- Paginated/infinite scroll display.
+
+**Web Implementation Details:**
+- Uses Ionic InfiniteScrollList for pagination.
+
+### Top Played
+**Requirements (Platform-Agnostic):**
+- Popular songs generated by backend based on history.
+- Shows play count for each song.
+- Real-time updates and infinite scroll.
+
+**Web Implementation Details:**
+- Uses Ionic InfiniteScrollList for pagination.
+
+### Singer Management
+**Requirements (Platform-Agnostic):**
+- Only admins can add or remove singers.
+- Singer names must be unique and non-empty.
+- Singers are automatically added to the list when they join.
+- All users can view the current singers list.
+- Tracks when each singer last joined.
+
+**Web Implementation Details:**
+- Singer management UI is available only to admins via the settings page.
+
+### Playback Control
+**Requirements (Platform-Agnostic):**
+- Only admins can control playback (play, pause, stop).
+- Play button is disabled if the queue is empty.
+- UI state (play/pause/stop) must reflect the current player state.
+
+**Web Implementation Details:**
+- Player controls are only rendered for admins.
+- State-based UI: play/pause/stop buttons shown/hidden based on current state.
+
+### Error Handling & Sync
+**Requirements (Platform-Agnostic):**
+- Graceful handling of sync failures with retry patterns.
+- Full controller object loaded on initial connection.
+- Incremental updates target specific child nodes.
+- Real-time connection status monitoring.
+- Graceful handling of missing or empty data.
+
+**Web Implementation Details:**
+- Uses web-specific toast notifications and error boundaries.
+
+### Disabled Songs
+**Requirements (Platform-Agnostic):**
+- Admins can disable or enable songs.
+- Disabled songs are stored using a hash of the song path for key safety.
+
+**Web Implementation Details:**
+- Disabled songs are managed via a modal dialog with search and filter capabilities.
+
+### Settings
+**Requirements (Platform-Agnostic):**
+- Only admins can change player settings (autoadvance, userpick).
+
+**Web Implementation Details:**
+- Debug logging is a web-only feature, toggled via the settings page.
+
+### Navigation
+**Requirements (Platform-Agnostic):**
+- Admin-only pages (e.g., settings) must be hidden from non-admin users.
+
+**Web Implementation Details:**
+- Navigation adapts based on admin status; settings page is only visible to admins.
+
+### UI/UX & Platform-Specifics
+**Requirements (Platform-Agnostic):**
+- All business logic, validation, and permissions must be enforced at the application level, not just in the UI.
+
+**Web Implementation Details:**
+- The web implementation uses Ionic React and Tailwind CSS for UI.
+- Features like infinite scroll, swipe actions, modals, and toasts are implemented using Ionic components.
+- Session persistence, URL parameter handling, and debug logging are web-specific.
 
 ---
 
@@ -180,141 +263,105 @@ controllers: {
 
 ## 7️⃣ UI/UX Behavior
 
-### **Design System:**
+**Requirements (Platform-Agnostic):**
-- **Responsive Design:** Works on all device sizes (mobile, tablet, desktop)
+- Responsive design that works on all device sizes.
-- **Light/Dark Mode:** Support for both themes (implementation pending)
+- Support for light/dark mode themes.
-- **Modern UI:** Clean, intuitive interface with consistent styling
+- Modern, clean, intuitive interface with consistent styling.
-- **Accessibility:** Keyboard navigation and screen reader support
+- Accessibility support (keyboard navigation, screen readers).
+- Tab-based navigation with clear active states.
+- Consistent empty state views for all lists.
+- Loading states with spinner animations.
+- Toast notifications for success/error feedback.
+- Consistent button styling with variants.
+- Reusable song display with context-aware actions.
+- Infinite scroll for automatic loading of additional content.
+- Context-specific behavior for different screens (search, queue, history, etc.).
+- Admin-specific UI elements (playback controls, queue reorder, singer management).
 
-### **Navigation:**
+**Web Implementation Details:**
-- **Tab-based Navigation:** Horizontal navigation bar with icons
+- Uses Ionic React components for responsive design and accessibility.
-- **Active States:** Clear indication of current page
+- Horizontal navigation bar with icons.
-- **Breadcrumbs:** Context-aware navigation (implementation pending)
+- Toast notifications positioned at top-right corner.
-
+- Modal views for artist songs and song lists.
-### **Common Components:**
+- Drag handles and swipe actions for queue management.
-- **Empty State View:** Consistent empty state for all lists
-- **Loading States:** Spinner animations during data loading
-- **Toast Notifications:** Success/error feedback for user actions
-- **Action Buttons:** Consistent button styling with variants
-- **Song Items:** Reusable song display with context-aware actions
-- **Infinite Scroll:** Automatic loading of additional content
-
-### **Context-Specific Behavior:**
-- **Search Context:** Add to queue, toggle favorite actions
-- **Queue Context:** Remove from queue, reorder (admin), toggle favorite
-- **History Context:** Add to queue, toggle favorite, show play date
-- **Favorites Context:** Add to queue, remove from favorites
-- **Artist Context:** Modal view with all artist songs
-- **Song List Context:** Expandable song matching with availability status
-
-### **Admin-Specific UI:**
-- **Playback Controls:** Only visible to admin users
-- **Queue Reorder:** Up/down arrow buttons for queue management
-- **Singer Management:** Add/remove singer functionality
-- **Enhanced Permissions:** Visual indicators for admin capabilities
 
 ---
 
 ## 8️⃣ UI Rules & Constraints
 
+**Requirements (Platform-Agnostic):**
+
 ### **Queue Management Rules:**
-- **Admin-Only Reordering:** Only admin users can reorder queue items using up/down arrows
+- Only admin users can reorder queue items.
-- **First Item Protection:** First queue item cannot be deleted while playing (only when stopped/paused)
+- First queue item cannot be deleted while playing (only when stopped/paused).
-- **Reorder Constraints:** 
+- Reorder constraints: items not at top/bottom can move up/down.
-  - Items with `order > 2` can move up (↑ button visible)
+- Queue items must maintain sequential order (1, 2, 3, etc.).
-  - Items with `order > 1` AND `order < queue.length` can move down (↓ button visible)
+- Automatic cleanup of inconsistent order values on queue initialization.
-  - First item (order = 1) cannot be moved up
+- Queue items use sequential numerical keys (0, 1, 2, etc.).
-  - Last item cannot be moved down
-- **Sequential Ordering:** Queue items must maintain sequential order (1, 2, 3, etc.)
-- **Order Validation:** Automatic cleanup of inconsistent order values on queue initialization
-- **Key Management:** Queue items use sequential numerical keys (0, 1, 2, etc.)
 
 ### **Playback Control Rules:**
-- **Admin-Only Visibility:** Player controls only visible to admin users (`isAdmin = true`)
+- Player controls only visible to admin users.
-- **Queue Dependency:** Play button is disabled when queue is empty (`hasSongsInQueue = false`)
+- Play button is disabled when queue is empty.
-- **State-Based Controls:**
+- State-based controls: play/pause/stop buttons shown/hidden based on current state.
-  - When `playing`: Show pause button, hide play button
+- Current player state must be clearly displayed.
-  - When `paused` or `stopped`: Show play button, hide pause button
-  - When `playing` or `paused`: Show stop button
-  - When `stopped`: Hide stop button
-- **State Display:** Current player state shown with color-coded badges (green=playing, yellow=paused, gray=stopped)
 
 ### **Search Rules:**
-- **Minimum Search Length:** Search only activates after 2+ characters (`MIN_SEARCH_LENGTH = 2`)
+- Search only activates after 2+ characters.
-- **Debounce Delay:** 300ms delay before search execution (`DEBOUNCE_DELAY = 300`)
+- Debounce delay before search execution.
-- **Search Scope:** Searches both song title and artist fields (case-insensitive)
+- Search scope includes both song title and artist fields (case-insensitive).
-- **Empty Search:** When search term is empty or too short, shows all songs
+- Empty search shows all songs.
-- **Page Reset:** Search resets to page 1 when search term changes
+- Search resets to page 1 when search term changes.
 
 ### **Pagination & Infinite Scroll Rules:**
-- **Items Per Page:** 20 items loaded per page (`ITEMS_PER_PAGE = 20`)
+- 20 items loaded per page.
-- **Load More Logic:** Only shows "load more" when there are more items than currently displayed
+- Load more logic only shows when there are more items than currently displayed.
-- **Intersection Observer:** Triggers load more when user scrolls to bottom 10% of list
+- Triggers load more when user scrolls to bottom 10% of list.
-- **Page State:** Each feature maintains its own page state independently
+- Each feature maintains its own page state independently.
-
+- All lists must use pagination to prevent UI blocking.
-### **Mandatory List Pagination Requirements:**
+- Progressive loading of items as user scrolls.
-- **All Lists Must Use InfiniteScrollList:** Every list in the application MUST use the `InfiniteScrollList` component to prevent UI blocking
+- Loading state management with spinner when no items are loaded yet.
-- **No Direct Array Rendering:** Never render large arrays directly in components - always use pagination
+- Page reset on search term changes.
-- **Consistent Page Size:** All lists use exactly 20 items per page (`ITEMS_PER_PAGE = 20`)
+- Memory optimization for smooth scrolling.
-- **Progressive Loading:** Items are loaded progressively as user scrolls, not all at once
+- Error handling for load more failures.
-- **Intersection Observer Threshold:** 10% threshold for triggering load more (`threshold: 0.1`)
+- Accessibility support for infinite scroll.
-- **Loading State Management:** Show loading spinner only when no items are loaded yet
-- **HasMore Calculation:** Only show "load more" when `currentItems.length < totalItems.length`
-- **Page Reset on Search:** Reset to page 1 when search term changes
-- **Independent Page States:** Each feature (Search, History, Favorites, etc.) maintains separate page state
-- **Memory Optimization:** Only render currently visible items plus buffer for smooth scrolling
-- **Performance Monitoring:** Log render times and intersection detection for debugging
-- **Error Handling:** Graceful handling of load more failures with retry options
-- **Accessibility:** Ensure infinite scroll works with keyboard navigation and screen readers
-
-### **InfiniteScrollList Component Rules:**
-- **Required Props:** All lists must provide `items`, `isLoading`, `hasMore`, `onLoadMore`
-- **Context Support:** Must support all contexts: 'search', 'queue', 'history', 'topPlayed', 'favorites'
-- **Loading States:** 
-  - Show spinner when `isLoading && items.length === 0`
-  - Show empty state when `items.length === 0 && !isLoading`
-  - Show load more trigger when `hasMore && items.length > 0`
-- **Observer Management:** Automatic cleanup of intersection observers on unmount
-- **Debug Information:** Optional debug info display for development
-- **Extra Content Support:** Allow custom content rendering per item
-- **Admin Controls:** Pass through admin status for context-specific actions
 
 ### **Toast Notification Rules:**
-- **Duration Settings:**
+- Duration settings: Success/Info 3 seconds, Error 5 seconds.
-  - Success messages: 3 seconds (`SUCCESS: 3000`)
+- Auto-dismiss after duration.
-  - Error messages: 5 seconds (`ERROR: 5000`)
+- Manual dismiss option.
-  - Info messages: 3 seconds (`INFO: 3000`)
+- Multiple toasts can be displayed simultaneously.
-- **Auto-dismiss:** Toasts automatically disappear after duration
-- **Manual Dismiss:** Users can manually close toasts with × button
-- **Stacking:** Multiple toasts can be displayed simultaneously
-- **Position:** Fixed position at top-right corner with z-index 50
 
 ### **Authentication Rules:**
-- **Admin Access:** Available via URL parameter `?admin=true`
+- Admin access is a privileged mode (see platform details for implementation).
-- **URL Cleanup:** Admin parameter removed from URL after successful authentication
+- Session persistence behavior varies by platform.
-- **Session Persistence:** Authentication state lost on page reload (requires re-login)
+- Both Party ID and singer name required for login.
-- **Required Fields:** Both Party ID and singer name required for login
-- **Admin Default:** Admin mode pre-fills singer name as "Admin"
 
 ### **Data Display Rules:**
-- **Loading States:** Show spinner when data count is 0
+- Loading states with spinner when data count is 0.
-- **Empty States:** Show empty state when data exists but filtered results are empty
+- Empty states when data exists but filtered results are empty.
-- **Debug Information:** Show data counts and loading status in development
+- Debug information display for development.
-- **User Attribution:** Show "(You)" indicator for current user's queue items
+- User attribution indicators for current user's queue items.
-- **Availability Status:** Show "Not available in catalog" for unmatched song list items
+- Availability status for unmatched song list items.
 
 ### **Action Button Rules:**
-- **Context-Based Actions:** Different actions available based on context (search, queue, history, etc.)
+- Context-based actions for different screens.
-- **Permission-Based Visibility:** Actions hidden based on user role (admin vs regular user)
+- Permission-based visibility based on user role.
-- **State-Based Disabling:** Buttons disabled based on current state (e.g., play button when queue empty)
+- State-based disabling of buttons.
-- **Confirmation Feedback:** All actions show success/error toast notifications
+- Confirmation feedback for all actions.
 
 ### **Modal & Overlay Rules:**
-- **Artist Modal:** Full-screen modal for viewing artist songs
+- Modal views for artist songs and song lists.
-- **Song List Modal:** Full-screen modal with expandable song sections
+- Proper backdrop and close actions.
-- **Z-Index Management:** Modals use high z-index (9999) to appear above all content
+
-- **Backdrop:** Semi-transparent black backdrop (50% opacity)
+**Web Implementation Details:**
-- **Close Actions:** Modal can be closed via close button or backdrop click
+- Admin access via URL parameter (`?admin=true`), removed after authentication.
+- Session lost on page reload.
+- Uses Ionic InfiniteScrollList component for pagination.
+- Toast notifications positioned at top-right corner with z-index 50.
+- Modals use high z-index (9999) with semi-transparent backdrop.
+- Admin mode pre-fills singer name as "Admin".
+- Intersection Observer API for infinite scroll detection.
+- Debug information display for development builds.
 
 ### **Error Handling Rules:**
 - **Error Boundaries:** React error boundaries catch component-level errors