mbrucedogs/singsalot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactored PRD to be Platform Agnostic

Browse Source 
Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>
This commit is contained in:
Matt Bruce 2025-07-20 11:58:41 -05:00
parent 60b9fdc62e
commit 0abe78302e
1 changed files with 289 additions and 242 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

531
docs/PRD.md
View File

@ -1,131 +1,214 @@
# 🎤 Karaoke Web App — Product Requirements Document (PRD) # 🎤 Karaoke App — Product Requirements Document (PRD)
--- ---
## 1️⃣ Purpose > **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.
This document defines the functional, technical, and UX requirements for the Karaoke Web 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**.
--- ---
## 2️⃣ Scope & Business Objectives ## 1️⃣ Purpose
- 🎯 Deliver a single-session karaoke experience where users connect to a controller and manage/search songs. 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**.
- ✅ 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.
- ✅ 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.
- ✅ True Separation of Concerns - UI components only handle presentation
- ✅ Reusable Business Logic - Hooks can be used across components
- ✅ Testable Code - Business logic separated from UI
- ✅ Maintainable - Changes to logic don't affect UI
- ✅ Performance - Memoized selectors and optimized hooks
- ✅ Type Safety - Full TypeScript coverage throughout
- ✅ The codebase needs to follow the Single Responsibility Principle perfectly - each file has one clear purpose!
--- ---
## 3️⃣ User Roles & Permissions ## 2️⃣ Scope & Business Objectives
| Role | Search Songs | Add Songs | Delete Songs | Reorder Queue | Playback Control | Manage Singers | View All Features | - 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.
| **Host/Admin** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - Prioritize fast performance, reusable modular architecture, and clear business logic separation.
| **Singer/User** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | - 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.
**Additional Permissions:** - True Separation of Concerns - UI components only handle presentation
- **Admin Access:** Available via URL parameter `?admin=true` - Reusable Business Logic - Hooks can be used across components
- **Queue Management:** Only admins can reorder queue items using up/down arrows - Testable Code - Business logic separated from UI
- **First Item Protection:** First queue item cannot be deleted while playing (only when stopped/paused) - Maintainable - Changes to logic don't affect UI
- **Singer Auto-Add:** Singers are automatically added to the singers list when they join - Performance - Memoized selectors and optimized hooks
- Type Safety - Full TypeScript coverage throughout
- The codebase needs to follow the Single Responsibility Principle perfectly - each file has one clear purpose!
--- ---
## 4️⃣ Feature Overview ## 3️⃣ User Roles & Permissions
### **Authentication & Session Management:** **Requirements (Platform-Agnostic):**
- **Login Flow:** Simple form-based authentication with Party ID and singer name - Two roles: Host/Admin and Singer/User.
- **Admin Mode:** Special admin access via URL parameter with enhanced privileges - Only admins can reorder or delete queue items, control playback, and manage singers.
- **Session Persistence:** Authentication state managed in Redux with automatic logout on page reload - Admin access is a privileged mode (see platform details for how it's triggered).
- **Controller Connection:** Users connect to specific controller/party sessions - First queue item cannot be deleted while playing (only when stopped/paused).
- Singers are automatically added to the singers list when they join.
### **Search:** **Web Implementation Details:**
- **Local Search:** Redux-managed search on preloaded song catalog - Admin access is triggered by a URL parameter (`?admin=true`) and removed from the URL 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:**
- **Real-time Sync:** Shared queue synchronized across all connected clients
- **Admin Controls:** Only admins can reorder using up/down arrow buttons
- **User Actions:** All users can delete songs (except first item when playing)
- **Order Management:** Sequential order system with automatic cleanup of inconsistent keys
- **Duplicate Prevention:** Based on `path` field of each song
- **Singer Attribution:** Each queue item shows which singer added it
### **Favorites:**
- **Real-time Sync:** Shared favorites list synchronized across all clients
- **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:**
- **Latest Additions:** Shows recently added songs from the `newSongs` node
- **Real-time Updates:** Automatically syncs when new songs are added
- **Infinite Scroll:** Paginated display with automatic loading
### **Artists:**
- **Artist Browse:** Browse songs by artist with search functionality
- **Modal View:** Click artist to see all their songs in a modal
- **Song Count:** Shows number of songs per artist
- **Infinite Scroll:** Paginated artist list with automatic loading
### **Song Lists:**
- **Predefined Lists:** Curated song lists with specific themes or collections
- **Song Matching:** Automatically matches list songs to available catalog
- **Expandable View:** Click to expand and see available song versions
- **Modal Interface:** Full-screen modal for viewing list contents
- **Availability Status:** Shows which songs are available in the catalog
### **History Tracking:**
- **Play History:** Songs automatically added to history when played
- **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:**
- **Popular Songs:** Generated by Firebase Cloud Function based on history
- **Play Count:** Shows number of times each song has been played
- **Real-time Updates:** Automatically updates when new plays are recorded
- **Infinite Scroll:** Paginated display with automatic loading
### **Singer Management:**
- **Admin Control:** Only admins can add/remove singers
- **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:**
- **Admin Only:** Playback controls only visible to admin users
- **State Sync:** Playback state synced to all clients using the `player.state` node
- **Player States:** Playing, Paused, Stopped (mapped to PlayerState enum)
- **Queue Integration:** Controls work with the current queue
### **Error Handling & Sync:**
- **Retry Patterns:** Graceful handling of Firebase sync failures
- **Full Load:** Complete controller object loaded on initial connection
- **Incremental Updates:** Subsequent updates target specific child nodes
- **Connection Status:** Real-time connection status monitoring
- **Empty State Handling:** Graceful handling of missing or empty data
--- ---
## 5️⃣ Data Models ## 4️⃣ Feature Overview
Data models are defined externally in: ### Authentication & Session Management
> [`types.ts`](./types.ts) **Requirements (Platform-Agnostic):**
- Login requires both Party ID and singer name.
- Party ID is validated against the backend before login is allowed.
- Authentication state is managed in the app state and lost on app reload (unless platform supports persistence).
This file contains TypeScript interfaces describing: **Web Implementation Details:**
- Admin access via URL parameter (`?admin=true`), removed after login.
- Session is lost on browser reload.
### Search
**Requirements (Platform-Agnostic):**
- Local search on preloaded song catalog.
- Instant search results as user types.
- Paginated/infinite scroll results.
- Context actions for each song (add to queue, favorite, etc).
**Web Implementation Details:**
- Uses Ionic InfiniteScrollList for pagination.
### Queue Management
**Requirements (Platform-Agnostic):**
- Shared queue synchronized across all clients.
- 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.
**Web Implementation Details:**
- Queue reordering and deletion are exposed via UI controls only visible to admins.
- UI uses drag handles and swipe actions (Ionic components) for reordering and deletion.
### Favorites
**Requirements (Platform-Agnostic):**
- Shared favorites list synchronized across all clients.
- Anyone can add/remove favorites.
- Duplicate prevention by song `path`.
- Paginated/infinite scroll display.
**Web Implementation Details:**
- Uses Ionic InfiniteScrollList for pagination.
### New Songs
**Requirements (Platform-Agnostic):**
- Shows recently added songs from the `newSongs` node.
- Real-time updates and infinite scroll.
**Web Implementation Details:**
- Uses Ionic InfiniteScrollList for pagination.
### Artists
**Requirements (Platform-Agnostic):**
- Browse songs by artist with search functionality.
- Modal view for all songs by an artist.
- Song count per artist.
- Paginated/infinite scroll artist list.
**Web Implementation Details:**
- Uses Ionic modals and InfiniteScrollList.
### Song Lists
**Requirements (Platform-Agnostic):**
- 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.
---
## 5️⃣ Data Models
Data models are defined externally in:
> [`types.ts`](./types.ts)
This file contains TypeScript interfaces describing:
- `Song` — Core song data with artist, title, path, and metadata - `Song` — Core song data with artist, title, path, and metadata
- `QueueItem` — Queue entries with order, singer, and song data - `QueueItem` — Queue entries with order, singer, and song data
- `Singer` — User information with name and last login - `Singer` — User information with name and last login
@ -145,10 +228,10 @@ This file contains TypeScript interfaces describing:
--- ---
## 6️⃣ Firebase Realtime Database Structure ## 6️⃣ Firebase Realtime Database Structure
Defined externally in: Defined externally in:
> [`firebase_schema.json`](./firebase_schema.json) > [`firebase_schema.json`](./firebase_schema.json)
**Complete Structure:** **Complete Structure:**
```json ```json
@ -178,143 +261,107 @@ controllers: {
--- ---
## 7️⃣ UI/UX Behavior ## 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 ## 8️⃣ UI Rules & Constraints
**Requirements (Platform-Agnostic):**
### **Queue Management Rules:** ### **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:** ### **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:** ### **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:** ### **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:** ### **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:** ### **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:** ### **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:** ### **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:** ### **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 Handling Rules:**
- **Error Boundaries:** React error boundaries catch component-level errors - **Error Boundaries:** React error boundaries catch component-level errors
@ -355,7 +402,7 @@ controllers: {
--- ---
## 9️⃣ Codebase Organization & File Structure ## 9️⃣ Codebase Organization & File Structure
### **Folder Structure & Purpose:** ### **Folder Structure & Purpose:**
@ -734,7 +781,7 @@ import type { Song, QueueItem } from '../types';
--- ---
## 🔟 Cloud Function Design — Top Played ## 🔟 Cloud Function Design — Top Played
- **Trigger:** Firebase Cloud Function triggered when song added to `history` - **Trigger:** Firebase Cloud Function triggered when song added to `history`
- **Action:** Increments play count in `/controllers/{controllerName}/topPlayed/{songId}` - **Action:** Increments play count in `/controllers/{controllerName}/topPlayed/{songId}`
@ -743,7 +790,7 @@ import type { Song, QueueItem } from '../types';
--- ---
## 11️⃣ External Reference Files ## 11️⃣ External Reference Files
| File | Purpose | | File | Purpose |
|------|---------| |------|---------|
@ -753,11 +800,11 @@ import type { Song, QueueItem } from '../types';
--- ---
## 12️⃣ Data Access Model & Validation ## 12️⃣ Data Access Model & Validation
> **Client-Controlled Access Model** > **Client-Controlled Access Model**
This app does **not** use Firebase Realtime Database Security Rules. This app does **not** use Firebase Realtime Database Security Rules.
All permissions, validation, and business logic are enforced in the client application. All permissions, validation, and business logic are enforced in the client application.
### **Enforced Client-Side:** ### **Enforced Client-Side:**
@ -774,14 +821,14 @@ All permissions, validation, and business logic are enforced in the client appli
- **Data Integrity:** Type checking, required field validation - **Data Integrity:** Type checking, required field validation
- **State Management:** Redux state consistency, error handling - **State Management:** Redux state consistency, error handling
**Assumed Environment:** **Assumed Environment:**
- The app is used in trusted, in-home scenarios with controlled participants - The app is used in trusted, in-home scenarios with controlled participants
- Open Firebase access is considered acceptable for this use case - Open Firebase access is considered acceptable for this use case
- All users are trusted participants in the karaoke session - All users are trusted participants in the karaoke session
--- ---
## 13️⃣ Performance & Optimization ## 13️⃣ Performance & Optimization
### **State Management:** ### **State Management:**
- **Redux Toolkit:** Efficient state management with immutable updates - **Redux Toolkit:** Efficient state management with immutable updates
@ -816,7 +863,7 @@ All permissions, validation, and business logic are enforced in the client appli
--- ---
## 14️⃣ Error Handling & Resilience ## 14️⃣ Error Handling & Resilience
### **Firebase Connection:** ### **Firebase Connection:**
- **Connection Monitoring:** Real-time connection status tracking - **Connection Monitoring:** Real-time connection status tracking
@ -838,7 +885,7 @@ All permissions, validation, and business logic are enforced in the client appli
--- ---
## 15️⃣ Testing Strategy ## 15️⃣ Testing Strategy
### **Unit Testing:** ### **Unit Testing:**
- **Hook Testing:** Business logic hooks with isolated testing - **Hook Testing:** Business logic hooks with isolated testing
@ -860,7 +907,7 @@ All permissions, validation, and business logic are enforced in the client appli
--- ---
## 16️⃣ Deployment & Environment ## 16️⃣ Deployment & Environment
### **Build Configuration:** ### **Build Configuration:**
- **Vite:** Fast build tool with hot module replacement - **Vite:** Fast build tool with hot module replacement
@ -880,7 +927,7 @@ All permissions, validation, and business logic are enforced in the client appli
--- ---
## 17️⃣ Firebase Implementation Patterns ## 17️⃣ Firebase Implementation Patterns
### **Key Management & Data Structure:** ### **Key Management & Data Structure:**
- **Sequential Numerical Keys:** Queue items use sequential numerical keys (0, 1, 2, etc.) instead of Firebase push IDs - **Sequential Numerical Keys:** Queue items use sequential numerical keys (0, 1, 2, etc.) instead of Firebase push IDs
@ -969,7 +1016,7 @@ All permissions, validation, and business logic are enforced in the client appli
--- ---
## 18️⃣ Critical Implementation Notes ## 18️⃣ Critical Implementation Notes
### **DO NOT CHANGE These Patterns:** ### **DO NOT CHANGE These Patterns:**
- **Queue Key Management:** Sequential numerical keys (0, 1, 2, etc.) - changing this will break queue functionality - **Queue Key Management:** Sequential numerical keys (0, 1, 2, etc.) - changing this will break queue functionality
@ -1004,9 +1051,9 @@ All permissions, validation, and business logic are enforced in the client appli
--- ---
## ✅ Summary ## ✅ Summary
This PRD serves as the comprehensive source of truth for application logic, Firebase data flow, and feature requirements. This PRD serves as the comprehensive source of truth for application logic, Firebase data flow, and feature requirements.
It works alongside `types.ts` and `firebase_schema.json` to inform both human developers and AI tools for accurate implementation. It works alongside `types.ts` and `firebase_schema.json` to inform both human developers and AI tools for accurate implementation.
**Key Success Metrics:** **Key Success Metrics:**
@ -1018,7 +1065,7 @@ It works alongside `types.ts` and `firebase_schema.json` to inform both human de
--- ---
## 19️⃣ Environment Configuration & .env.local Setup ## 19️⃣ Environment Configuration & .env.local Setup
### **Environment File Structure:** ### **Environment File Structure:**
The application uses Vite's built-in environment variable support with the following file structure: The application uses Vite's built-in environment variable support with the following file structure:
@ -1175,7 +1222,7 @@ const validateFirebaseConfig = () => {
--- ---
## 20️⃣ Third-Party UI Library - Ionic React ## 20️⃣ Third-Party UI Library - Ionic React
### **Current UI Implementation:** ### **Current UI Implementation:**
The application currently uses **Tailwind CSS** for styling with custom components. While functional, this approach requires significant custom development for responsive design and native platform feel. The application currently uses **Tailwind CSS** for styling with custom components. While functional, this approach requires significant custom development for responsive design and native platform feel.
@ -1395,7 +1442,7 @@ No complex choices, no multiple libraries, no over-engineering. Just one library
--- ---
## 21️⃣ Design Folder & Mockups ## 21️⃣ Design Folder & Mockups
### **Design Folder Contents:** ### **Design Folder Contents:**
The `/docs/design/` folder contains UI/UX mockups that were created using an **older version of Ionic** to demonstrate the intended layout and user experience. The `/docs/design/` folder contains UI/UX mockups that were created using an **older version of Ionic** to demonstrate the intended layout and user experience.