280 lines
8.7 KiB
Markdown
280 lines
8.7 KiB
Markdown
# SingSalot AI - Karaoke App
|
|
|
|
> **Modern React + TypeScript + Ionic + Firebase Realtime Database**
|
|
|
|
A real-time karaoke application designed for in-home party use with multi-user synchronization, admin controls, and comprehensive song management.
|
|
|
|
## 🎯 Features
|
|
|
|
### **Core Functionality**
|
|
- **Real-time Queue Management** - Synchronized across all connected devices
|
|
- **Multi-User Support** - Admin and user roles with different permissions
|
|
- **Comprehensive Search** - Instant search through song catalog with pagination
|
|
- **Favorites System** - Shared favorites list across all users
|
|
- **History Tracking** - Automatic tracking of played songs
|
|
- **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
|
|
|
|
### **Admin Features**
|
|
- **Queue Control** - Reorder and delete queue items
|
|
- **Playback Control** - Play, pause, stop music
|
|
- **Singer Management** - Add/remove singers
|
|
- **Settings Management** - Configure autoadvance and userpick
|
|
- **Song Management** - Disable/enable songs
|
|
|
|
### **Technical Features**
|
|
- **Real-time Sync** - Firebase Realtime Database synchronization
|
|
- **Performance Optimized** - Memoized components, virtualized lists, pagination
|
|
- **Type Safety** - Full TypeScript implementation
|
|
- **Responsive Design** - Mobile-first with touch-friendly interface
|
|
- **Error Handling** - Graceful degradation and retry patterns
|
|
|
|
## 🏗️ Architecture
|
|
|
|
### **Refactored Architecture (Latest)**
|
|
The codebase has been completely refactored for better maintainability and performance:
|
|
|
|
#### **Domain-Specific Redux Slices**
|
|
- `songsSlice.ts` - Song catalog management
|
|
- `queueSlice.ts` - Queue operations and state
|
|
- `favoritesSlice.ts` - Favorites management
|
|
- `historySlice.ts` - History tracking
|
|
|
|
#### **Composable Hooks**
|
|
- `useFilteredSongs.ts` - Reusable song filtering logic
|
|
- `usePaginatedData.ts` - Generic pagination with search
|
|
- `useErrorHandler.ts` - Centralized error handling
|
|
- `usePerformanceMonitor.ts` - Performance tracking
|
|
|
|
#### **Optimized Components**
|
|
- `SongItem.tsx` - Memoized with React.memo and useCallback
|
|
- `ListItem.tsx` - Generic list item with TypeScript support
|
|
- `VirtualizedList.tsx` - High-performance list rendering
|
|
- `ActionButton.tsx` - Reusable action buttons
|
|
|
|
#### **Performance Optimizations**
|
|
- **React.memo** for component memoization
|
|
- **useMemo/useCallback** for expensive computations
|
|
- **Virtualized rendering** for large datasets
|
|
- **Infinite scroll** with pagination
|
|
- **Optimized Redux selectors**
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### **Prerequisites**
|
|
- Node.js 18+
|
|
- npm or yarn
|
|
- Firebase project setup
|
|
|
|
### **Installation**
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd singsalot-ai
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Set up environment variables
|
|
cp env.template .env.local
|
|
# Edit .env.local with your Firebase configuration
|
|
|
|
# Start development server
|
|
npm run dev
|
|
```
|
|
|
|
### **Environment Setup**
|
|
Create a `.env.local` file with your Firebase configuration:
|
|
```env
|
|
VITE_FIREBASE_API_KEY=your_api_key
|
|
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
|
|
VITE_FIREBASE_DATABASE_URL=https://your_project.firebaseio.com
|
|
VITE_FIREBASE_PROJECT_ID=your_project_id
|
|
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
|
|
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
|
|
VITE_FIREBASE_APP_ID=your_app_id
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
src/
|
|
├── components/ # Reusable UI components
|
|
│ ├── Auth/ # Authentication components
|
|
│ ├── common/ # Shared components (SongItem, ActionButton, etc.)
|
|
│ ├── Layout/ # Layout and navigation components
|
|
│ └── Navigation/ # Navigation components
|
|
├── features/ # Feature-specific components
|
|
│ ├── Artists/ # Artist browsing feature
|
|
│ ├── Favorites/ # Favorites management
|
|
│ ├── History/ # Play history
|
|
│ ├── NewSongs/ # New songs feature
|
|
│ ├── Queue/ # Queue management
|
|
│ ├── Search/ # Song search
|
|
│ ├── Settings/ # Settings and admin features
|
|
│ ├── Singers/ # Singer management
|
|
│ ├── SongLists/ # Song lists feature
|
|
│ └── TopPlayed/ # Top played songs
|
|
├── firebase/ # Firebase configuration and services
|
|
├── hooks/ # Custom React hooks (refactored)
|
|
├── redux/ # State management (domain-specific slices)
|
|
├── types/ # TypeScript type definitions
|
|
└── utils/ # Utility functions
|
|
```
|
|
|
|
## 🛠️ Development
|
|
|
|
### **Available Scripts**
|
|
```bash
|
|
npm run dev # Start development server
|
|
npm run build # Build for production
|
|
npm run preview # Preview production build
|
|
npm run lint # Run ESLint
|
|
npm run type-check # Run TypeScript type checking
|
|
```
|
|
|
|
### **Key Development Patterns**
|
|
|
|
#### **Adding New Features**
|
|
1. Create feature component in `src/features/`
|
|
2. Add corresponding Redux slice if needed
|
|
3. Create custom hooks for business logic
|
|
4. Add TypeScript types in `src/types/`
|
|
|
|
#### **Component Guidelines**
|
|
- Use `React.memo` for performance-critical components
|
|
- Implement `useMemo` and `useCallback` for expensive operations
|
|
- Follow the established prop patterns for consistency
|
|
|
|
#### **State Management**
|
|
- Use domain-specific Redux slices for related functionality
|
|
- Implement async thunks for Firebase operations
|
|
- Use memoized selectors for performance
|
|
|
|
## 🔧 Firebase Configuration
|
|
|
|
### **Database Structure**
|
|
The app uses Firebase Realtime Database with the following structure:
|
|
```json
|
|
{
|
|
"controllers": {
|
|
"[controllerName]": {
|
|
"favorites": {},
|
|
"history": {},
|
|
"topPlayed": {},
|
|
"newSongs": {},
|
|
"disabledSongs": {},
|
|
"player": {
|
|
"queue": {},
|
|
"settings": {},
|
|
"singers": {},
|
|
"state": {}
|
|
},
|
|
"songList": {},
|
|
"songs": {}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### **Security Rules**
|
|
The app uses client-side validation with permissive Firebase rules for real-time synchronization.
|
|
|
|
## 📱 User Experience
|
|
|
|
### **Authentication**
|
|
- Login requires Party ID and singer name
|
|
- Admin access is a privileged mode
|
|
- Session state managed in app (lost on reload)
|
|
|
|
### **Queue Management**
|
|
- Real-time synchronization across all clients
|
|
- Sequential numerical keys (0, 1, 2, ...)
|
|
- Admin-only reordering and deletion
|
|
- First item protection during playback
|
|
|
|
### **Search & Discovery**
|
|
- Instant search with debouncing
|
|
- Paginated results with infinite scroll
|
|
- Multiple entry points (search, history, favorites, etc.)
|
|
- Context-aware actions for each song
|
|
|
|
## 🧪 Testing
|
|
|
|
### **Current Testing Status**
|
|
- ✅ TypeScript compilation
|
|
- ✅ ESLint validation
|
|
- ✅ Build process
|
|
- 🔄 Unit tests (planned)
|
|
- 🔄 Integration tests (planned)
|
|
|
|
### **Testing Strategy**
|
|
- Unit tests for business logic and hooks
|
|
- Integration tests for Firebase operations
|
|
- Component testing with React Testing Library
|
|
- Performance testing for large datasets
|
|
|
|
## 🚀 Deployment
|
|
|
|
### **Build Process**
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
The build process:
|
|
- Compiles TypeScript
|
|
- Bundles with Vite
|
|
- Optimizes for production
|
|
- Generates static assets
|
|
|
|
### **Deployment Options**
|
|
- **Firebase Hosting** - Recommended for Firebase integration
|
|
- **Vercel** - Easy deployment with automatic builds
|
|
- **Netlify** - Static site hosting with CI/CD
|
|
- **Traditional hosting** - Any static file server
|
|
|
|
## 📚 Documentation
|
|
|
|
### **Related Documents**
|
|
- [`docs/PRD.md`](docs/PRD.md) - Product Requirements Document
|
|
- [`docs/platforms/web/PRD-web.md`](docs/platforms/web/PRD-web.md) - Web-specific implementation guide
|
|
- [`docs/firebase_schema.json`](docs/firebase_schema.json) - Firebase database schema
|
|
|
|
### **Design Assets**
|
|
- [`docs/platforms/web/design/`](docs/platforms/web/design/) - UI/UX design mockups and assets
|
|
|
|
## 🤝 Contributing
|
|
|
|
### **Development Workflow**
|
|
1. Create feature branch from main
|
|
2. Implement changes following established patterns
|
|
3. Ensure TypeScript compilation passes
|
|
4. Run linting and type checking
|
|
5. Test functionality manually
|
|
6. Submit pull request
|
|
|
|
### **Code Standards**
|
|
- Follow TypeScript best practices
|
|
- Use established component patterns
|
|
- Maintain performance optimizations
|
|
- Add appropriate error handling
|
|
- Update documentation as needed
|
|
|
|
## 📄 License
|
|
|
|
This project is proprietary software. All rights reserved.
|
|
|
|
## 🆘 Support
|
|
|
|
For technical support or questions about the implementation:
|
|
- Check the documentation in the `docs/` folder
|
|
- Review the TypeScript types for API contracts
|
|
- Examine the Firebase schema for data structure
|
|
- Refer to the platform-specific PRD for implementation details
|
|
|
|
---
|
|
|
|
**Built with ❤️ using React, TypeScript, Ionic, and Firebase**
|