Signed-off-by: mbrucedogs <mbrucedogs@gmail.com>
This commit is contained in:
parent
e5b011fcad
commit
9662c8ce56
326
README.md
326
README.md
@ -1,69 +1,279 @@
|
||||
# React + TypeScript + Vite
|
||||
# SingSalot AI - Karaoke App
|
||||
|
||||
This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
|
||||
> **Modern React + TypeScript + Ionic + Firebase Realtime Database**
|
||||
|
||||
Currently, two official plugins are available:
|
||||
A real-time karaoke application designed for in-home party use with multi-user synchronization, admin controls, and comprehensive song management.
|
||||
|
||||
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
|
||||
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
|
||||
## 🎯 Features
|
||||
|
||||
## Expanding the ESLint configuration
|
||||
### **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
|
||||
|
||||
If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
|
||||
### **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
|
||||
|
||||
```js
|
||||
export default tseslint.config([
|
||||
globalIgnores(['dist']),
|
||||
{
|
||||
files: ['**/*.{ts,tsx}'],
|
||||
extends: [
|
||||
// Other configs...
|
||||
### **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
|
||||
|
||||
// Remove tseslint.configs.recommended and replace with this
|
||||
...tseslint.configs.recommendedTypeChecked,
|
||||
// Alternatively, use this for stricter rules
|
||||
...tseslint.configs.strictTypeChecked,
|
||||
// Optionally, add this for stylistic rules
|
||||
...tseslint.configs.stylisticTypeChecked,
|
||||
## 🏗️ Architecture
|
||||
|
||||
// Other configs...
|
||||
],
|
||||
languageOptions: {
|
||||
parserOptions: {
|
||||
project: ['./tsconfig.node.json', './tsconfig.app.json'],
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
},
|
||||
// other options...
|
||||
},
|
||||
},
|
||||
])
|
||||
### **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
|
||||
```
|
||||
|
||||
You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
|
||||
|
||||
```js
|
||||
// eslint.config.js
|
||||
import reactX from 'eslint-plugin-react-x'
|
||||
import reactDom from 'eslint-plugin-react-dom'
|
||||
|
||||
export default tseslint.config([
|
||||
globalIgnores(['dist']),
|
||||
{
|
||||
files: ['**/*.{ts,tsx}'],
|
||||
extends: [
|
||||
// Other configs...
|
||||
// Enable lint rules for React
|
||||
reactX.configs['recommended-typescript'],
|
||||
// Enable lint rules for React DOM
|
||||
reactDom.configs.recommended,
|
||||
],
|
||||
languageOptions: {
|
||||
parserOptions: {
|
||||
project: ['./tsconfig.node.json', './tsconfig.app.json'],
|
||||
tsconfigRootDir: import.meta.dirname,
|
||||
},
|
||||
// other options...
|
||||
},
|
||||
},
|
||||
])
|
||||
### **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**
|
||||
|
||||
18
docs/PRD.md
18
docs/PRD.md
@ -493,6 +493,15 @@ controllers: {
|
||||
- **Data Models** shared across all layers
|
||||
- **Firebase Integration** abstracted through service layer
|
||||
|
||||
### **Architecture Principles:**
|
||||
- **Separation of Concerns** - UI components handle presentation, business logic in services
|
||||
- **Reusable Business Logic** - Business rules implemented in platform-agnostic services
|
||||
- **Testable Code** - Business logic separated from UI for easy testing
|
||||
- **Maintainability** - Changes to logic don't affect UI
|
||||
- **Performance** - Optimized data access and state management
|
||||
- **Type Safety** - Strong typing throughout the codebase
|
||||
- **Single Responsibility** - Each file has one clear purpose
|
||||
|
||||
### **Platform Implementation:**
|
||||
- **Web:** See `platforms/web/PRD-web.md#codebase-organization` for React/Ionic structure
|
||||
- **iOS:** See `platforms/ios/PRD-ios.md#codebase-organization` (future)
|
||||
@ -542,6 +551,15 @@ controllers: {
|
||||
- **Caching strategy** for frequently accessed data
|
||||
- **Memory management** for large datasets
|
||||
|
||||
### **Performance Requirements:**
|
||||
- **Real-time synchronization** with minimal latency
|
||||
- **Efficient data loading** with pagination and infinite scroll
|
||||
- **Optimized state management** to prevent unnecessary re-renders
|
||||
- **Caching strategy** for frequently accessed data
|
||||
- **Memory management** for large datasets
|
||||
- **Component optimization** for expensive UI operations
|
||||
- **Data filtering and search** with efficient algorithms
|
||||
|
||||
### **Platform Implementation:**
|
||||
- **Web:** See `platforms/web/PRD-web.md#performance` for React/Ionic optimization
|
||||
- **iOS:** See `platforms/ios/PRD-ios.md#performance` (future)
|
||||
|
||||
@ -12,14 +12,200 @@ This document contains **web-specific implementation details** for the Karaoke A
|
||||
| Section | Purpose |
|
||||
|---------|---------|
|
||||
| [UI/UX Behavior](#uiux-behavior) | Web-specific UI patterns and interactions |
|
||||
| [Refactored Architecture](#refactored-architecture) | Latest architecture improvements and patterns |
|
||||
| [Component Architecture](#component-architecture) | React/Ionic component structure |
|
||||
| [State Management](#state-management) | Redux Toolkit implementation |
|
||||
| [Performance Optimizations](#performance-optimizations) | Web-specific performance strategies |
|
||||
| [Development Setup](#development-setup) | Web project configuration |
|
||||
| [Design Assets](#design-assets) | Web-specific visual references |
|
||||
| [Toolset Choices](#toolset-choices) | Web technology rationale |
|
||||
|
||||
---
|
||||
|
||||
## Refactored Architecture
|
||||
|
||||
### **Overview**
|
||||
The web implementation has been completely refactored to improve maintainability, performance, and developer experience. This section documents the latest architecture patterns and implementation details.
|
||||
|
||||
### **Key Architectural Improvements**
|
||||
|
||||
#### **1. Domain-Specific Redux Slices**
|
||||
Replaced the monolithic `controllerSlice` with focused, domain-specific slices:
|
||||
|
||||
```typescript
|
||||
// Before: Monolithic controllerSlice
|
||||
src/redux/controllerSlice.ts (1000+ lines)
|
||||
|
||||
// After: Domain-specific slices
|
||||
src/redux/songsSlice.ts // Song catalog management
|
||||
src/redux/queueSlice.ts // Queue operations and state
|
||||
src/redux/favoritesSlice.ts // Favorites management
|
||||
src/redux/historySlice.ts // History tracking
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- **Better Performance** - Smaller slices mean faster state updates
|
||||
- **Easier Testing** - Isolated business logic for each domain
|
||||
- **Improved Maintainability** - Clear separation of concerns
|
||||
- **Reduced Bundle Size** - Only load necessary slice logic
|
||||
|
||||
#### **2. Composable Hooks**
|
||||
Extracted common patterns into reusable, composable hooks:
|
||||
|
||||
```typescript
|
||||
// Reusable filtering logic
|
||||
useFilteredSongs(songs, searchTerm, disabledSongs)
|
||||
|
||||
// Generic pagination with search
|
||||
usePaginatedData(data, pageSize, searchTerm)
|
||||
|
||||
// Centralized error handling
|
||||
useErrorHandler(operation, fallbackMessage)
|
||||
|
||||
// Performance monitoring
|
||||
usePerformanceMonitor(componentName, props)
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- **Code Reuse** - Common patterns shared across features
|
||||
- **Performance Optimized** - Each hook can be optimized independently
|
||||
- **Type Safety** - Full TypeScript support with proper typing
|
||||
- **Easier Testing** - Isolated business logic
|
||||
|
||||
#### **3. Optimized Components**
|
||||
Enhanced components with performance optimizations:
|
||||
|
||||
```typescript
|
||||
// Memoized SongItem with optimized rendering
|
||||
const SongItem = React.memo<SongItemProps>(({ song, context, ...props }) => {
|
||||
const isInQueue = useMemo(() => /* expensive computation */, [queue, song.path]);
|
||||
const handleAddToQueue = useCallback(() => /* action */, [handleAddToQueue, song]);
|
||||
|
||||
return <IonItem>...</IonItem>;
|
||||
});
|
||||
|
||||
// Generic ListItem for any data type
|
||||
const ListItem = React.memo<GenericListItemProps>(({
|
||||
primaryText, secondaryText, onClick, ...props
|
||||
}) => {
|
||||
return <IonItem>...</IonItem>;
|
||||
});
|
||||
|
||||
// High-performance virtualized list
|
||||
const VirtualizedList = <T,>({
|
||||
items, renderItem, itemHeight, ...props
|
||||
}: VirtualizedListProps<T>) => {
|
||||
// Only renders visible items
|
||||
return <div>...</div>;
|
||||
};
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- **React.memo** - Prevents unnecessary re-renders
|
||||
- **Generic Components** - Reusable across different data types
|
||||
- **Virtualized Rendering** - Handles large datasets efficiently
|
||||
- **Performance Monitoring** - Built-in tracking capabilities
|
||||
|
||||
### **Implementation Patterns**
|
||||
|
||||
#### **State Management Pattern**
|
||||
```typescript
|
||||
// Domain-specific slice
|
||||
export const songsSlice = createSlice({
|
||||
name: 'songs',
|
||||
initialState,
|
||||
reducers: { /* domain-specific actions */ },
|
||||
extraReducers: (builder) => {
|
||||
builder.addCase(fetchSongs.fulfilled, (state, action) => {
|
||||
// Handle async operations
|
||||
});
|
||||
},
|
||||
});
|
||||
|
||||
// Composable hook using the slice
|
||||
export const useSongs = () => {
|
||||
const dispatch = useAppDispatch();
|
||||
const songs = useAppSelector(selectSongs);
|
||||
|
||||
const fetchSongs = useCallback(async () => {
|
||||
try {
|
||||
await dispatch(fetchSongsThunk());
|
||||
} catch (error) {
|
||||
// Error handling
|
||||
}
|
||||
}, [dispatch]);
|
||||
|
||||
return { songs, fetchSongs };
|
||||
};
|
||||
```
|
||||
|
||||
#### **Component Pattern**
|
||||
```typescript
|
||||
// Feature component using composable hooks
|
||||
const Search: React.FC = () => {
|
||||
const { songs, loading, error } = useSongs();
|
||||
const { filteredSongs, searchTerm, setSearchTerm } = useFilteredSongs(songs);
|
||||
const { paginatedData, hasMore, loadMore } = usePaginatedData(filteredSongs);
|
||||
|
||||
return (
|
||||
<div>
|
||||
<SearchInput value={searchTerm} onChange={setSearchTerm} />
|
||||
<VirtualizedList
|
||||
items={paginatedData}
|
||||
renderItem={(song) => <SongItem song={song} context="search" />}
|
||||
hasMore={hasMore}
|
||||
onLoadMore={loadMore}
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
### **Performance Optimizations**
|
||||
|
||||
#### **Component-Level Optimizations**
|
||||
- **React.memo** - Prevents re-renders when props haven't changed
|
||||
- **useMemo** - Memoizes expensive computations
|
||||
- **useCallback** - Memoizes event handlers and functions
|
||||
- **Virtualized Lists** - Only renders visible items for large datasets
|
||||
|
||||
#### **State Management Optimizations**
|
||||
- **Domain-Specific Slices** - Smaller, focused state management
|
||||
- **Memoized Selectors** - Efficient state access with reselect
|
||||
- **Lazy Loading** - Load components and data only when needed
|
||||
- **Incremental Updates** - Target specific Firebase nodes for efficiency
|
||||
|
||||
#### **Data Handling Optimizations**
|
||||
- **Pagination** - Load data in chunks to prevent UI blocking
|
||||
- **Search Debouncing** - Reduce unnecessary API calls during typing
|
||||
- **Filtering Optimization** - Efficient algorithms for large datasets
|
||||
- **Memory Management** - Proper cleanup of listeners and subscriptions
|
||||
|
||||
### **Development Guidelines**
|
||||
|
||||
#### **Adding New Features**
|
||||
1. **Create domain-specific slice** if needed
|
||||
2. **Implement composable hooks** for business logic
|
||||
3. **Build optimized components** with React.memo and useCallback
|
||||
4. **Add TypeScript types** for type safety
|
||||
5. **Implement error handling** using useErrorHandler
|
||||
|
||||
#### **Performance Best Practices**
|
||||
- **Use React.memo** for expensive components
|
||||
- **Implement useMemo/useCallback** for expensive operations
|
||||
- **Leverage virtualized lists** for large datasets
|
||||
- **Optimize Redux selectors** with memoization
|
||||
- **Monitor performance** with usePerformanceMonitor
|
||||
|
||||
#### **Code Organization**
|
||||
- **Domain-specific slices** in `/redux/`
|
||||
- **Composable hooks** in `/hooks/`
|
||||
- **Generic components** in `/components/common/`
|
||||
- **Feature components** in `/features/`
|
||||
- **TypeScript types** in `/types/`
|
||||
|
||||
---
|
||||
|
||||
## UI/UX Behavior
|
||||
|
||||
### **Web-Specific Requirements:**
|
||||
@ -55,7 +241,7 @@ This document contains **web-specific implementation details** for the Karaoke A
|
||||
|
||||
## Codebase Organization & File Structure
|
||||
|
||||
### **Web Project Structure:**
|
||||
### **Refactored Web Project Structure (Latest):**
|
||||
```
|
||||
src/
|
||||
├── components/ # Reusable UI components
|
||||
@ -78,28 +264,55 @@ src/
|
||||
│ ├── config.ts # Firebase configuration
|
||||
│ ├── services.ts # Firebase service layer
|
||||
│ └── useFirebase.ts # Firebase hooks
|
||||
├── hooks/ # Custom React hooks
|
||||
├── hooks/ # Custom React hooks (refactored)
|
||||
│ ├── useFilteredSongs.ts # Reusable song filtering logic
|
||||
│ ├── usePaginatedData.ts # Generic pagination with search
|
||||
│ ├── useErrorHandler.ts # Centralized error handling
|
||||
│ ├── usePerformanceMonitor.ts # Performance tracking
|
||||
│ ├── useQueue.ts # Queue management hooks
|
||||
│ ├── useSearch.ts # Search functionality hooks
|
||||
│ ├── useFavorites.ts # Favorites management hooks
|
||||
│ └── ... # Other feature hooks
|
||||
├── redux/ # State management
|
||||
├── redux/ # State management (domain-specific slices)
|
||||
│ ├── store.ts # Redux store configuration
|
||||
│ ├── slices/ # Redux slices
|
||||
│ ├── songsSlice.ts # Song catalog management
|
||||
│ ├── queueSlice.ts # Queue operations and state
|
||||
│ ├── favoritesSlice.ts # Favorites management
|
||||
│ ├── historySlice.ts # History tracking
|
||||
│ ├── selectors.ts # Memoized selectors
|
||||
│ └── hooks.ts # Redux hooks
|
||||
├── types/ # TypeScript type definitions
|
||||
└── utils/ # Utility functions
|
||||
```
|
||||
|
||||
### **Refactored Architecture Benefits:**
|
||||
|
||||
#### **Domain-Specific Redux Slices:**
|
||||
- **Modular Design** - Each slice handles a specific domain (songs, queue, favorites, history)
|
||||
- **Better Performance** - Smaller slices mean faster state updates and re-renders
|
||||
- **Easier Testing** - Isolated business logic for each domain
|
||||
- **Improved Maintainability** - Clear separation of concerns
|
||||
|
||||
#### **Composable Hooks:**
|
||||
- **Reusable Logic** - Common patterns extracted into reusable hooks
|
||||
- **Performance Optimized** - Each hook can be optimized independently
|
||||
- **Type Safety** - Full TypeScript support with proper typing
|
||||
- **Error Handling** - Centralized error management across the app
|
||||
|
||||
#### **Optimized Components:**
|
||||
- **React.memo** - Prevents unnecessary re-renders for expensive components
|
||||
- **Generic Components** - Reusable across different data types (ListItem, VirtualizedList)
|
||||
- **Performance Monitoring** - Built-in performance tracking
|
||||
- **Error Boundaries** - Graceful error handling and recovery
|
||||
|
||||
### **File Organization Rules:**
|
||||
| Folder | Purpose | Key Files | Import Pattern |
|
||||
|--------|---------|-----------|----------------|
|
||||
| `/components` | Reusable UI components | `SongItem.tsx`, `ActionButton.tsx` | `import { SongItem } from '../components/common'` |
|
||||
| `/components` | Reusable UI components | `SongItem.tsx`, `ActionButton.tsx`, `ListItem.tsx` | `import { SongItem } from '../components/common'` |
|
||||
| `/features` | Feature-specific pages | `Queue.tsx`, `Search.tsx` | `import { Queue } from '../features/Queue'` |
|
||||
| `/firebase` | Firebase integration | `services.ts`, `config.ts` | `import { queueService } from '../firebase/services'` |
|
||||
| `/hooks` | Custom business logic | `useQueue.ts`, `useSearch.ts` | `import { useQueue } from '../hooks/useQueue'` |
|
||||
| `/redux` | State management | `controllerSlice.ts`, `authSlice.ts`, `selectors.ts` | `import { useAppDispatch, selectQueue } from '../redux'` |
|
||||
| `/hooks` | Composable business logic | `useFilteredSongs.ts`, `usePaginatedData.ts` | `import { useFilteredSongs } from '../hooks'` |
|
||||
| `/redux` | Domain-specific state | `songsSlice.ts`, `queueSlice.ts` | `import { songsSlice } from '../redux'` |
|
||||
| `/types` | TypeScript definitions | `index.ts` (extends docs/types.ts) | `import type { Song, QueueItem } from '../types'` |
|
||||
|
||||
### **Import Patterns:**
|
||||
@ -709,11 +922,55 @@ const Queue: React.FC = () => {
|
||||
```
|
||||
|
||||
### **Performance Optimizations:**
|
||||
- **React.memo** for expensive components
|
||||
- **useMemo** and **useCallback** for expensive calculations
|
||||
- **Redux selectors** with memoization
|
||||
- **Lazy loading** for route-based code splitting
|
||||
- **Service worker** for PWA caching
|
||||
|
||||
#### **Component-Level Optimizations:**
|
||||
- **React.memo** - Prevents unnecessary re-renders for expensive components like `SongItem`
|
||||
- **useMemo/useCallback** - Memoizes expensive computations and event handlers
|
||||
- **Virtualized Lists** - `VirtualizedList` component renders only visible items for large datasets
|
||||
- **Generic Components** - `ListItem` component works with any data type for reusability
|
||||
|
||||
#### **State Management Optimizations:**
|
||||
- **Domain-Specific Slices** - Smaller, focused Redux slices (songs, queue, favorites, history)
|
||||
- **Composable Hooks** - Reusable logic (`useFilteredSongs`, `usePaginatedData`, `useErrorHandler`)
|
||||
- **Optimized Selectors** - Memoized Redux selectors for efficient state access
|
||||
- **Lazy Loading** - Components and data loaded only when needed
|
||||
|
||||
#### **Data Handling Optimizations:**
|
||||
- **Pagination** - `usePaginatedData` hook loads data in chunks to prevent UI blocking
|
||||
- **Search Debouncing** - Reduces unnecessary API calls during typing
|
||||
- **Filtering Optimization** - `useFilteredSongs` hook provides efficient filtering algorithms
|
||||
- **Memory Management** - Proper cleanup of listeners and subscriptions
|
||||
|
||||
#### **Performance Monitoring:**
|
||||
- **Built-in Performance Hooks** - `usePerformanceMonitor` tracks component render times
|
||||
- **Error Tracking** - Centralized error handling with performance impact monitoring
|
||||
- **Bundle Analysis** - Optimized bundle size with code splitting
|
||||
|
||||
#### **Specific Optimizations:**
|
||||
- **SongItem Component** - Fully memoized with React.memo, useMemo, and useCallback
|
||||
- **ListItem Component** - Generic component supporting multiple data types
|
||||
- **VirtualizedList Component** - High-performance list rendering with windowing
|
||||
- **ActionButton Component** - Reusable buttons with consistent styling and behavior
|
||||
|
||||
### **Refactoring Benefits & Migration Notes:**
|
||||
|
||||
#### **Architecture Improvements:**
|
||||
- **Modular Redux Slices** - Replaced monolithic `controllerSlice` with domain-specific slices
|
||||
- **Composable Hooks** - Extracted common patterns into reusable hooks
|
||||
- **Performance Optimizations** - Added React.memo, useMemo, useCallback throughout
|
||||
- **Type Safety** - Enhanced TypeScript support with strict typing
|
||||
|
||||
#### **Component Enhancements:**
|
||||
- **Generic ListItem** - Replaced song-specific component with generic, reusable component
|
||||
- **VirtualizedList** - Added high-performance list rendering for large datasets
|
||||
- **Performance Monitoring** - Built-in performance tracking with `usePerformanceMonitor`
|
||||
- **Error Boundaries** - Centralized error handling across the application
|
||||
|
||||
#### **Development Experience:**
|
||||
- **Better Maintainability** - Clear separation of concerns with domain-specific slices
|
||||
- **Easier Testing** - Isolated business logic for each domain
|
||||
- **Improved Performance** - Optimized rendering and state management
|
||||
- **Enhanced Type Safety** - Full TypeScript coverage with proper typing
|
||||
|
||||
### **Critical Implementation Rules:**
|
||||
- **Never import directly from slice files** - always use the main redux index
|
||||
@ -721,6 +978,8 @@ const Queue: React.FC = () => {
|
||||
- **Implement business logic in hooks**, not components
|
||||
- **Use memoization** for expensive operations
|
||||
- **Handle loading and error states** in all async operations
|
||||
- **Use React.memo** for performance-critical components
|
||||
- **Leverage composable hooks** for reusable business logic
|
||||
|
||||
---
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user