Signed-off-by: mbrucedogs <mbrucedogs@gmail.com>
This commit is contained in:
parent
8987c50d49
commit
17fe5cecf0
@ -15,7 +15,7 @@ A real-time karaoke application designed for in-home party use with multi-user s
|
||||
- **Artist Browsing** - Browse songs by artist with modal views
|
||||
- **Song Lists** - Predefined song collections with availability matching
|
||||
- **Top Played** - Popular songs based on play history
|
||||
- **New Songs** - Recently added songs to the catalog
|
||||
- **New Songs** - Recently added songs to the catalog (see PRD for implementation details)
|
||||
|
||||
### **Admin Features**
|
||||
- **Queue Control** - Reorder and delete queue items
|
||||
|
||||
13
docs/PRD.md
13
docs/PRD.md
@ -148,6 +148,19 @@ This document defines the functional, technical, and UX requirements for the Kar
|
||||
**Requirements (Platform-Agnostic):**
|
||||
- Shows recently added songs from the `newSongs` node
|
||||
- Real-time updates and infinite scroll
|
||||
- **Data Format Support**: Handles both full song objects and path-only references
|
||||
- **Reverse Lookup**: Automatically resolves song paths to full song objects from main catalog
|
||||
- **Backward Compatibility**: Works with both old and new data formats
|
||||
|
||||
**Implementation Details:**
|
||||
- **Format Detection**: Automatically detects whether `newSongs` contains full song objects or path-only references
|
||||
- **Reverse Lookup**: When path-only data is detected, performs lookup against main songs catalog
|
||||
- **Error Resilience**: Gracefully handles missing songs without breaking the UI
|
||||
- **Debug Logging**: Provides detailed logging for troubleshooting missing songs
|
||||
|
||||
**Data Formats Supported:**
|
||||
1. **New Format**: `{ path: "song_path", key: "firebase_key" }` → Performs reverse lookup
|
||||
2. **Old Format**: Full song objects with `artist`, `title`, `path`, etc. → Uses as-is
|
||||
|
||||
**Platform Implementation:**
|
||||
- **Web:** See `platforms/web/PRD-web.md#new-songs` for React/Ionic implementation
|
||||
|
||||
194
docs/README.md
194
docs/README.md
@ -1,194 +0,0 @@
|
||||
# 📄 Documentation & Reference Models
|
||||
|
||||
This `/docs` folder contains **Product Requirements Documents (PRD)**, **data model definitions**, and **Firebase schema references** for the Karaoke App project.
|
||||
|
||||
These files are intended for:
|
||||
- 📃 Developers reviewing the business logic and architecture.
|
||||
- 🤖 AI tools like Cursor or Copilot that reference documentation for context-aware coding.
|
||||
- 📝 Project planning, architecture decisions, and future enhancements.
|
||||
- 🚀 **Building the app from scratch with any framework/platform combination.**
|
||||
|
||||
---
|
||||
|
||||
## Contents
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `PRD.md` | **Complete Product Requirements Document** — platform-agnostic business logic, technical specifications, data flows, service APIs, component architecture, error handling, and performance optimizations. **Self-guiding for AI implementation.** |
|
||||
| `types.ts` | Reference TypeScript interfaces used for modeling app objects. **Not imported into app runtime code.** |
|
||||
| `firebase_schema.json` | Example Firebase Realtime Database structure for understanding data relationships and CRUD operations. |
|
||||
| `platforms/web/design/` | **Web UI/UX Design Assets** — mockups and visual references for web platform features. |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 How to Use This Documentation
|
||||
|
||||
### **For AI-Assisted Development:**
|
||||
Simply say **"Read this PRD"** in any new chat. The PRD contains:
|
||||
- **Self-guiding instructions** for AI implementation
|
||||
- **Complete technical specifications** for 100% accuracy
|
||||
- **Implementation questions** to determine platform/framework choices
|
||||
- **Step-by-step build process** with checklists
|
||||
|
||||
### **For Human Developers:**
|
||||
- **Reference during implementation** for business logic and data flows
|
||||
- **Guide for architecture decisions** and technology choices
|
||||
- **Source of truth** for all functional requirements
|
||||
- **Migration guide** when switching frameworks/platforms
|
||||
|
||||
### **For New Implementations:**
|
||||
1. **Read the PRD completely** - it contains comprehensive specifications
|
||||
2. **Review design assets** in `platforms/web/design/` folder for visual reference
|
||||
3. **Answer implementation questions** from Section 29
|
||||
4. **Follow the implementation checklist** for complete build process
|
||||
5. **Preserve business logic** while adapting UI to chosen framework
|
||||
|
||||
---
|
||||
|
||||
## 📋 Key Features of the Updated PRD
|
||||
|
||||
### **Platform-Agnostic Design:**
|
||||
- **Core business logic** completely separated from implementation details
|
||||
- **Firebase architecture** and data models for any platform
|
||||
- **Cross-platform references** to platform-specific PRDs
|
||||
- **Universal business rules** that apply to all implementations
|
||||
|
||||
### **Complete Technical Specifications:**
|
||||
- **Firebase data structure** and relationships
|
||||
- **Business logic patterns** and validation rules
|
||||
- **Real-time synchronization** requirements
|
||||
- **User role permissions** and access control
|
||||
- **Error handling scenarios** and recovery patterns
|
||||
- **Performance requirements** and optimization guidelines
|
||||
|
||||
### **Implementation Guide:**
|
||||
- **Platform selection questions** to determine technology stack
|
||||
- **5-phase implementation checklist** for complete builds
|
||||
- **Business logic preservation** guidelines
|
||||
- **Critical success factors** for accurate implementations
|
||||
|
||||
### **Design Assets:**
|
||||
- **Visual mockups** for all major features and screens
|
||||
- **Platform-specific designs** (web, mobile, etc.)
|
||||
- **UX patterns** and interaction flows
|
||||
- **Design system references** for consistent implementation
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Workflow for New Versions
|
||||
|
||||
### **When Creating New Implementations:**
|
||||
1. **Use the PRD as-is** - it's designed for any framework/platform
|
||||
2. **Reference design assets** for visual guidance and UX patterns
|
||||
3. **Follow the implementation guide** in Section 29
|
||||
4. **Preserve all business logic** while adapting UI layer
|
||||
5. **Test against specifications** for 100% accuracy
|
||||
|
||||
### **When Updating the PRD:**
|
||||
1. **Keep platform-agnostic requirements** intact
|
||||
2. **Add new implementation details** to appropriate sections
|
||||
3. **Update toolset sections** with new technology choices
|
||||
4. **Maintain self-guiding nature** for AI implementation
|
||||
|
||||
### **When Migrating Platforms:**
|
||||
1. **Keep all business logic** from core requirements
|
||||
2. **Replace only implementation details** in platform-specific sections
|
||||
3. **Add new platform sections** following the established pattern
|
||||
4. **Update toolset rationale** for new technology choices
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
- ✅ These files are **not intended for direct import or use in application runtime**.
|
||||
- ✅ Validation logic and data models here serve as **development references only**.
|
||||
- ✅ Any updates to business logic, data flow, or app architecture should be reflected here for documentation purposes.
|
||||
- ✅ AI tools may use this information to assist with code generation but will not access `/src` directly.
|
||||
- ✅ **The PRD is self-guiding** - it contains all instructions needed for AI implementation.
|
||||
- ✅ **100% accuracy achievable** when following the complete specifications.
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Design Assets Reference
|
||||
|
||||
### **Current Web Design Assets:**
|
||||
Located in `platforms/web/design/` folder with comprehensive mockups for all features:
|
||||
|
||||
#### **Core Navigation & Layout:**
|
||||
- `00-web-layout.JPG` - Overall web layout structure
|
||||
- `01-Login.png` - Login screen design
|
||||
- `02-menu.jpeg`, `02a-menu.jpeg`, `02b-menu.png`, `02c-menu.jpeg` - Navigation menu variations
|
||||
|
||||
#### **Queue Management:**
|
||||
- `02-queue.png` - Main queue view
|
||||
- `02-queue-delete.png` - Queue with delete functionality
|
||||
- `02-queue-drag.png` - Queue reordering with drag and drop
|
||||
- `02-queue-sorting.png` - Queue sorting interface
|
||||
|
||||
#### **Search & Discovery:**
|
||||
- `04-search.png` - Main search interface
|
||||
- `04-search typing .png` - Search with typing interaction
|
||||
- `04-search-song info.png` - Search results with song information
|
||||
|
||||
#### **User Management:**
|
||||
- `05-singers.png` - Singer list view
|
||||
- `05-singers add.png` - Singer management interface
|
||||
|
||||
#### **Content Browsing:**
|
||||
- `06-artists .png` - Artist browse interface
|
||||
- `06-artists (not admin).png` - Non-admin artist view
|
||||
- `06-artists search.png` - Artist search functionality
|
||||
- `06-artists songs.png` - Artist songs list
|
||||
|
||||
#### **User Features:**
|
||||
- `07-favorites.png` - Favorites management
|
||||
- `08-history.png` - Play history view
|
||||
- `09-songs list.png` - Main song lists view
|
||||
- `09-song lists - songs.png` - Song lists with song details
|
||||
- `09- song lists songs expand.png` - Song lists with expandable sections
|
||||
|
||||
#### **Admin Features:**
|
||||
- `10-Settings.png` - Settings interface
|
||||
- `11-top 100.png` - Top played songs
|
||||
- `12-favorites .png` - Favorites view
|
||||
- `12-favorite lists.png` - Favorite lists management
|
||||
|
||||
#### **Menu States:**
|
||||
- `03-menu.png` - General menu layout
|
||||
- `03-menu current page and non-admin.png` - Navigation with current page indicators
|
||||
- `03-menu playing (admin).png` - Admin view during playback
|
||||
|
||||
### **Future Platform Design Structure:**
|
||||
```
|
||||
docs/platforms/
|
||||
├── web/
|
||||
│ └── design/ # Current web mockups
|
||||
├── ios/
|
||||
│ └── design/ # Future iOS designs
|
||||
├── android/
|
||||
│ └── design/ # Future Android designs
|
||||
├── tablet/
|
||||
│ └── design/ # Future tablet designs
|
||||
└── desktop/
|
||||
└── design/ # Future desktop designs
|
||||
```
|
||||
|
||||
### **Using Design Assets:**
|
||||
- **Reference during implementation** for visual accuracy
|
||||
- **Understand UX patterns** and interaction flows
|
||||
- **Guide UI component design** and layout decisions
|
||||
- **Ensure consistency** across different implementations
|
||||
- **Validate feature completeness** against visual requirements
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Metrics
|
||||
- **Zero ambiguity** in technical requirements
|
||||
- **Framework independence** for easy migration
|
||||
- **Complete implementation path** from start to finish
|
||||
- **Consistent results** across different technology stacks
|
||||
- **Self-documenting** for future developers and AI tools
|
||||
|
||||
---
|
||||
|
||||
_This documentation is designed to be your **ultimate development tool** - enabling accurate builds with any framework/platform combination._
|
||||
|
||||
@ -108,14 +108,50 @@ export const selectFavoritesArrayWithoutDisabled = createSelector(
|
||||
);
|
||||
|
||||
export const selectNewSongsArray = createSelector(
|
||||
[selectNewSongs],
|
||||
(newSongs) => sortSongsByArtistAndTitle(objectToArray(newSongs))
|
||||
[selectNewSongs, selectSongs],
|
||||
(newSongs, songs) => {
|
||||
// Handle both formats:
|
||||
// 1. Array of objects with only path property (new format)
|
||||
// 2. Array of full song objects (old format)
|
||||
|
||||
const newSongsArray = objectToArray(newSongs);
|
||||
|
||||
// Check if the first item has only path and key properties (new format) or is a full song object (old format)
|
||||
if (newSongsArray.length > 0 &&
|
||||
typeof newSongsArray[0] === 'object' &&
|
||||
newSongsArray[0] !== null &&
|
||||
'path' in newSongsArray[0] &&
|
||||
!('artist' in newSongsArray[0]) &&
|
||||
!('title' in newSongsArray[0])) {
|
||||
// New format: array of objects with only path property - do reverse lookup
|
||||
const songPaths = (newSongsArray as { path: string }[]).map(item => item.path);
|
||||
const songsMap = new Map(Object.values(songs as Record<string, Song>).map(song => [song.path, song]));
|
||||
|
||||
const resolvedSongs = songPaths
|
||||
.map(path => songsMap.get(path))
|
||||
.filter((song): song is Song => song !== undefined);
|
||||
|
||||
debugLog('selectNewSongsArray - reverse lookup:', {
|
||||
pathsCount: songPaths.length,
|
||||
resolvedCount: resolvedSongs.length,
|
||||
missingPaths: songPaths.filter(path => !songsMap.has(path))
|
||||
});
|
||||
|
||||
return sortSongsByArtistAndTitle(resolvedSongs);
|
||||
} else {
|
||||
// Old format: array of full song objects
|
||||
return sortSongsByArtistAndTitle(newSongsArray as Song[]);
|
||||
}
|
||||
}
|
||||
);
|
||||
|
||||
// New songs array without disabled songs
|
||||
export const selectNewSongsArrayWithoutDisabled = createSelector(
|
||||
[selectNewSongsArray, (_state: RootState, disabledSongPaths: Set<string>) => disabledSongPaths],
|
||||
(newSongs, disabledSongPaths) => newSongs.filter(song => !disabledSongPaths.has(song.path))
|
||||
(newSongs, disabledSongPaths) => {
|
||||
// The selectNewSongsArray already handles the reverse lookup, so we just filter disabled songs
|
||||
return newSongs.filter(song => !disabledSongPaths.has(song.path));
|
||||
}
|
||||
);
|
||||
|
||||
export const selectSingersArray = createSelector(
|
||||
|
||||
@ -93,7 +93,7 @@ export interface Controller {
|
||||
favorites: Record<string, Song>;
|
||||
history: Record<string, Song>;
|
||||
topPlayed: Record<string, TopPlayed>;
|
||||
newSongs: Record<string, Song>;
|
||||
newSongs: Record<string, Song | { path: string }>; // Can be either Song objects or objects with only path property
|
||||
player: {
|
||||
queue: Record<string, QueueItem>;
|
||||
settings: Settings;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user