184 lines
6.2 KiB
Markdown
184 lines
6.2 KiB
Markdown
# 🎤 Karaoke Web App — Product Requirements Document (PRD)
|
||
|
||
---
|
||
|
||
## 1️⃣ Purpose
|
||
|
||
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
|
||
|
||
- 🎯 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.
|
||
- ✅ Prioritize fast performance, reusable modular architecture, and clear business logic separation.
|
||
- ✅ Enable adding songs from multiple entry points (search, history, top played).
|
||
- ✅ 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
|
||
|
||
| Role | Search Songs | Add Songs | Delete Songs | Reorder Queue | Playback Control | Manage Singers |
|
||
|--------------|---------------|-----------|--------------|----------------|------------------|----------------|
|
||
| **Host/Admin** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||
| **Singer/User** | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
|
||
|
||
---
|
||
|
||
## 4️⃣ Feature Overview
|
||
|
||
- **Search:**
|
||
- Local, Redux-managed search on a preloaded song list.
|
||
- Common song item view with context-based action panel.
|
||
|
||
- **Queue Management:**
|
||
- Shared real-time synced queue.
|
||
- Admin can reorder; all users can delete songs.
|
||
- Duplicate prevention based on `fileLocation` field of each song.
|
||
|
||
- **Favorites:**
|
||
- Shared real-time synced.
|
||
- Anyone can do this
|
||
- Duplicate prevention based on `fileLocation` field of each song.
|
||
|
||
- **Latest Songs:**
|
||
- This is the newSongs node in the controller.
|
||
- Shared real-time synced.
|
||
|
||
- **Playback Control:**
|
||
- Managed by Admin only.
|
||
- Playback state synced to all clients using the `player` node in Firebase.
|
||
- The Player.state is mapped to the PlayerState enum in the types.ts.
|
||
|
||
- **History Tracking:**
|
||
- Songs added to history automatically when played.
|
||
- Append-only log, shared across clients.
|
||
|
||
- **Top Played:**
|
||
- Generated by a Firebase Cloud Function based on history.
|
||
- Stored inside the `controller` node for client reference.
|
||
|
||
- **Singer Management:**
|
||
- Admin can add/remove singers.
|
||
- All users can view the current singers list.
|
||
|
||
- **Error Handling:**
|
||
- Retry options for sync failures.
|
||
- Full controller object loaded on start; incremental sync after.
|
||
|
||
---
|
||
|
||
## 5️⃣ Data Models
|
||
|
||
Data models are defined externally in:
|
||
> [`types.ts`](./types.ts)
|
||
|
||
This file contains TypeScript interfaces describing:
|
||
- `Song` — Used in queue, search results, and UI actions.
|
||
- `Controller` — Main object containing queue, singers, history, player state, and top played list.
|
||
- `PlayerState` — Playback status object synced in Firebase.
|
||
|
||
---
|
||
|
||
## 6️⃣ Firebase Realtime Database Structure
|
||
|
||
Defined externally in:
|
||
> [`firebase_schema.json`](./firebase_schema.json)
|
||
|
||
Example structure:
|
||
```json
|
||
controllers: {
|
||
[controllerName]: {
|
||
favorites: { ... },
|
||
history: { ... },
|
||
topPlayed: { ... },
|
||
newSongs: { ... },
|
||
player: {
|
||
queue: { ... },
|
||
settings: { ... },
|
||
singers: { ... },
|
||
state: "..."
|
||
},
|
||
songList: { ... },
|
||
songs: { ... }
|
||
}
|
||
}
|
||
```
|
||
|
||
- Initial sync loads the full `controller` object.
|
||
- Subsequent updates target specific child nodes.
|
||
|
||
---
|
||
|
||
## 7️⃣ UI/UX Behavior
|
||
|
||
- Shared **Empty State View** for empty lists or missing data.
|
||
- Toast notifications for user actions like add/remove/favorite.
|
||
- Playback controls only visible to Admin.
|
||
- Common song list item with dynamic action panel based on context (search, queue, history).
|
||
|
||
---
|
||
|
||
## 8️⃣ Codebase Organization
|
||
|
||
| Folder | Purpose |
|
||
|--------|---------|
|
||
| `/components/common` | Shared UI components (EmptyState, Toast, ActionButton) |
|
||
| `/features` | Feature-specific components (Search, Queue, History, TopPlayed) |
|
||
| `/redux` | State management slices (controller, queue, player) |
|
||
| `/firebase` | Firebase CRUD and real-time sync services |
|
||
|
||
---
|
||
|
||
## 9️⃣ Cloud Function Design — Top Played
|
||
|
||
- Triggered when a new song is added to `history`.
|
||
- Increments the play count inside `/controllers/{controllerName}/topPlayed/{songId}`.
|
||
- Ensures Top Played is up-to-date without blocking client-side actions.
|
||
|
||
---
|
||
|
||
## 🔟 External Reference Files
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| [`types.ts`](./types.ts) | TypeScript interfaces for app data models and validation |
|
||
| [`firebase_schema.json`](./firebase_schema.json) | Firebase Realtime Database structure reference |
|
||
|
||
---
|
||
|
||
## 11️⃣ Data Access Model & Validation
|
||
|
||
> **Client-Controlled Access Model**
|
||
|
||
This app does **not** use Firebase Realtime Database Security Rules.
|
||
All permissions, validation, and business logic are enforced in the client application.
|
||
|
||
### Enforced Client-Side:
|
||
- ✅ Admin-only permissions for queue reorder, playback control, and singer management.
|
||
- ✅ Duplicate song prevention enforced before adding to the queue.
|
||
- ✅ Singer is auto-added on join if not already present in the list.
|
||
- ✅ Data validated against `types.ts` before being written to Firebase.
|
||
|
||
**Assumed Environment:**
|
||
- The app is used in trusted, in-home scenarios with controlled participants.
|
||
- Open Firebase access is considered acceptable for this use case.
|
||
|
||
---
|
||
|
||
## ✅ Summary
|
||
|
||
This PRD serves as the primary 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.
|
||
|