Update CLAUDE.md to enhance documentation with new dashboard and file serving systems; add dependencies and improve admin user management details

CLAUDE.md

@@ -27,17 +27,17 @@ This is a soundboard application with a FastAPI backend and React frontend.
 - **Framework**: FastAPI with SQLModel for database ORM
 - **Database**: SQLite with aiosqlite async driver
 - **Authentication**: JWT tokens with OAuth2 support (Google, GitHub)
-- **Dependencies**: FastAPI, SQLModel, aiosqlite, bcrypt, PyJWT, pydantic-settings, uvicorn, ffmpeg-python, yt-dlp, python-vlc
+- **Dependencies**: FastAPI, SQLModel, aiosqlite, bcrypt, PyJWT, pydantic-settings, uvicorn, ffmpeg-python, yt-dlp, python-vlc, apscheduler
 - **Structure**:
-  - `app/api/v1/`: API endpoints for v1 (auth.py, main.py, sounds.py, extractions.py, socket.py, player.py, playlists.py)
-  - `app/api/v1/admin/`: Admin-only API endpoints (sounds.py, extractions.py)
-  - `app/models/`: Database models (User, Sound, Playlist, Extraction, Plan, UserOAuth, CreditTransaction, SoundPlayed, etc.)
-  - `app/services/`: Business logic layer (auth.py, oauth.py, socket.py, player.py, sound_scanner.py, sound_normalizer.py, extraction.py, extraction_processor.py, credit.py)
-  - `app/repositories/`: Data access layer (base.py, user.py, user_oauth.py, sound.py, extraction.py, credit_transaction.py, playlist.py)
-  - `app/schemas/`: Pydantic schemas for API requests/responses (auth.py)
+  - `app/api/v1/`: API endpoints for v1 (auth.py, main.py, sounds.py, extractions.py, socket.py, player.py, playlists.py, dashboard.py, files.py)
+  - `app/api/v1/admin/`: Admin-only API endpoints (sounds.py, extractions.py, users.py)
+  - `app/models/`: Database models (User, Sound, Playlist, Extraction, Plan, UserOAuth, CreditTransaction, SoundPlayed, CreditAction, etc.)
+  - `app/services/`: Business logic layer (auth.py, oauth.py, socket.py, player.py, sound_scanner.py, sound_normalizer.py, extraction.py, extraction_processor.py, credit.py, scheduler.py, dashboard.py, vlc_player.py)
+  - `app/repositories/`: Data access layer (base.py, user.py, user_oauth.py, sound.py, extraction.py, credit_transaction.py, playlist.py, plan.py)
+  - `app/schemas/`: Pydantic schemas for API requests/responses (auth.py, common.py, player.py, playlist.py, user.py)
   - `app/core/`: Configuration, database setup, logging, dependencies, seeds
   - `app/middleware/`: Custom middleware (logging)
-  - `app/utils/`: Utility functions (auth.py, cookies.py, audio.py)
+  - `app/utils/`: Utility functions (auth.py, cookies.py, audio.py, credit_decorators.py)
   - `tests/`: Comprehensive test suite with pytest and asyncio support
 
 ### Frontend Architecture
@@ -235,6 +235,8 @@ Comprehensive audio player service with VLC backend for playlist management and
   - Mode switching and volume control
   - Play count tracking and credit integration
   - Error handling and edge cases
+- **VLC Player Service**: 12 comprehensive tests for subprocess-based playback
+- **Scheduler Service**: 8 tests covering periodic task execution and error handling
 
 ## Repository Pattern & Testing
 
@@ -415,6 +417,194 @@ Shared utility functions for audio file processing used across multiple services
 - **Duplicate Prevention**: Hash calculation for unique constraint enforcement
 - **Centralized Logic**: Eliminates code duplication between audio processing services
 
+## Dashboard System
+
+Comprehensive dashboard system providing statistical insights and analytics for soundboard usage.
+
+### Dashboard Features
+- **Soundboard Statistics**: Overview metrics for total sounds, playlists, and storage usage
+- **Track Statistics**: Play count analytics and user activity metrics
+- **Top Sounds**: Ranking system with flexible filtering by sound type and time period
+- **Historical Data**: Time-based analytics for tracking usage trends
+- **Real-time Updates**: Live statistics updates for current session data
+
+### API Endpoints
+- `GET /api/v1/dashboard/soundboard-statistics`: General soundboard overview statistics
+- `GET /api/v1/dashboard/track-statistics`: Track and play count analytics
+- `GET /api/v1/dashboard/top-sounds`: Top sounds by play count with filtering options
+  - Query parameters: `sound_type` (SDB, TTS, EXT, or 'all'), `period` (today, 1_day, 1_week, 1_month, 1_year, all_time), `limit` (1-100)
+
+### Technical Implementation
+- **Service**: `app/services/dashboard.py` - Core dashboard data aggregation and analytics
+- **API**: `app/api/v1/dashboard.py` - REST endpoints for dashboard data retrieval
+- **Authentication**: All dashboard endpoints require user authentication
+- **Performance**: Optimized queries for efficient data aggregation
+
+## File Serving System
+
+Secure file serving system for audio files and thumbnails with authentication and access control.
+
+### File Serving Features
+- **Audio File Downloads**: Secure serving of original and normalized audio files
+- **Thumbnail Serving**: Image thumbnails for extracted audio content (YouTube, etc.)
+- **Authentication Required**: All file serving requires user authentication
+- **MIME Type Detection**: Automatic content type detection for proper browser handling
+- **Cache Control**: Optimized caching headers for performance
+
+### API Endpoints
+- `GET /api/v1/files/sounds/{sound_id}/download`: Download audio file (normalized version preferred)
+- `GET /api/v1/files/sounds/{sound_id}/thumbnail`: Get thumbnail image for extracted content
+
+### Technical Implementation
+- **API**: `app/api/v1/files.py` - File serving endpoints with security validation
+- **Access Control**: Flexible authentication allowing both authenticated users and API tokens
+- **Error Handling**: Comprehensive error handling for missing files and permissions
+- **Path Security**: Secure file path resolution preventing directory traversal
+
+### Security Features
+- **Authentication**: Uses `get_current_active_user_flexible` for token or session auth
+- **File Validation**: Validates file existence and user permissions
+- **Safe Downloads**: Proper Content-Disposition headers for secure file downloads
+- **Cache Headers**: Optimized caching for thumbnails (1 hour cache time)
+
+## VLC Player Service
+
+Subprocess-based VLC player service for immediate sound playback with comprehensive process management.
+
+### VLC Player Features
+- **Subprocess-based Playback**: Launches VLC instances via subprocess for reliable audio playback
+- **Cross-platform Support**: Automatic VLC executable detection (Linux, macOS, Windows)
+- **Immediate Response**: Non-blocking VLC launches for responsive UI
+- **Play Count Tracking**: Automatic sound play count updates and history recording
+- **Process Management**: Kill all VLC instances functionality for cleanup
+- **WebSocket Integration**: Real-time `sound_played` event broadcasting
+
+### VLC Configuration
+- **Audio-only Mode**: `--no-video` flag for audio-only playback
+- **Exit After Play**: `--play-and-exit` for automatic VLC termination
+- **No Interface**: `--intf dummy` for headless operation
+- **No Repeat/Loop**: Single playback mode
+
+### API Integration
+- **Immediate Playback**: Used by sound endpoints for instant VLC-based playback
+- **Background Recording**: Async play count recording without blocking playback
+- **Global Service**: Singleton service accessible throughout application
+- **Process Cleanup**: Stop all VLC instances endpoint for system cleanup
+
+### Technical Implementation
+- **Service**: `app/services/vlc_player.py` - Core VLC subprocess management
+- **Process Detection**: Cross-platform VLC executable discovery
+- **Async Operations**: Non-blocking subprocess creation and management
+- **Resource Management**: Background task handling for play count recording
+- **Error Handling**: Comprehensive error handling with logging
+
+### Play Count Integration
+- **Automatic Recording**: Play counts updated automatically on VLC playback
+- **History Tracking**: `SoundPlayed` records created for audit trails
+- **Admin Association**: Play events associated with admin user as placeholder
+- **WebSocket Events**: Real-time `sound_played` events with user and sound details
+
+## Scheduler Service
+
+Automated task scheduling system using APScheduler for periodic background operations.
+
+### Scheduler Features
+- **Daily Credit Recharge**: Automated daily credit replenishment for all users
+- **Cron-based Scheduling**: Flexible cron expression support for task timing
+- **Database Integration**: Full database session management for scheduled tasks
+- **Error Handling**: Comprehensive error handling with detailed logging
+- **Graceful Shutdown**: Proper scheduler cleanup on application shutdown
+
+### Scheduled Tasks
+- **Daily Credit Recharge**: Runs at midnight UTC daily, replenishes user credits based on plan limits
+- **Future Extensibility**: Framework ready for additional periodic tasks
+
+### Technical Implementation
+- **Service**: `app/services/scheduler.py` - APScheduler integration and task management
+- **Dependencies**: Uses APScheduler AsyncIOScheduler for async task execution
+- **Session Management**: Database session factory integration for data access
+- **Logging**: Detailed task execution logging and error reporting
+
+### Lifecycle Integration
+- **Application Startup**: Scheduler automatically started during app initialization
+- **Application Shutdown**: Graceful scheduler shutdown with task completion
+- **Job Management**: Replace existing jobs on restart, prevent duplicate scheduling
+
+## Credit Decorators System
+
+Advanced decorator system for credit validation and automatic deduction with comprehensive error handling.
+
+### Credit Decorator Features
+- **Function Decorators**: `@requires_credits` and `@validate_credits_only` decorators
+- **Automatic Credit Handling**: Credit validation, deduction, and error handling
+- **Context Managers**: `CreditManager` async context manager for manual credit operations
+- **Metadata Support**: Flexible metadata extraction and storage
+- **Success Tracking**: Automatic success/failure detection for accurate billing
+
+### Decorator Types
+- **`@requires_credits`**: Full credit validation and deduction with success tracking
+- **`@validate_credits_only`**: Credit validation without deduction (pre-flight checks)
+- **`CreditManager`**: Async context manager for fine-grained credit control
+
+### Technical Implementation
+- **Module**: `app/utils/credit_decorators.py` - Comprehensive credit management decorators
+- **Parameter Extraction**: Intelligent user ID extraction from function signatures
+- **Error Handling**: Proper credit handling even during exceptions
+- **Type Safety**: Full type annotations and generic type support
+
+### Usage Examples
+- **Service Decoration**: Decorate service methods requiring credit deduction
+- **API Integration**: Pre-validate credits before expensive operations
+- **Context Management**: Manual credit control for complex multi-step operations
+
+## Admin User Management
+
+Comprehensive admin user management system with full CRUD operations and plan management.
+
+### Admin User Management Features
+- **User Listing**: Paginated user listing with plan information
+- **User Details**: Individual user profile viewing and editing
+- **Plan Management**: Assign and modify user subscription plans
+- **Account Control**: Enable/disable user accounts
+- **Credit Management**: Admin credit adjustments and balance control
+
+### API Endpoints
+- `GET /api/v1/admin/users/`: List all users with pagination
+- `GET /api/v1/admin/users/{user_id}`: Get specific user details
+- `PATCH /api/v1/admin/users/{user_id}`: Update user information
+- `POST /api/v1/admin/users/{user_id}/disable`: Disable user account
+- `POST /api/v1/admin/users/{user_id}/enable`: Enable user account
+- `GET /api/v1/admin/users/plans/list`: List all available plans
+
+### Technical Implementation
+- **API**: `app/api/v1/admin/users.py` - Admin user management endpoints
+- **Schema**: `app/schemas/user.py` - User update validation schemas
+- **Access Control**: Admin-only access with dependency injection
+- **Plan Integration**: Full plan assignment and validation
+
+### Security Features
+- **Admin Authentication**: All endpoints require admin role verification
+- **Input Validation**: Comprehensive request validation with Pydantic schemas
+- **Relationship Management**: Proper handling of user-plan relationships
+- **Data Integrity**: Foreign key validation for plan assignments
+
+## API Documentation System
+
+Multiple API documentation interfaces with modern documentation tools.
+
+### Documentation Interfaces
+- **Swagger UI**: Available at `/api/docs` - Interactive API exploration
+- **ReDoc**: Available at `/api/redoc` - Clean, responsive documentation
+- **Scalar**: Available at `/api/v1/scalar-docs` - Modern API reference
+- **RapiDoc**: Available at `/api/v1/rapidoc-docs` - Fast, customizable docs
+- **Stoplight Elements**: Available at `/api/v1/elements-docs` - Feature-rich documentation
+
+### Technical Implementation
+- **OpenAPI Schema**: Available at `/api/openapi.json` - Machine-readable API specification
+- **Custom HTML**: Custom HTML templates for each documentation interface
+- **CDN Integration**: Uses CDN-hosted documentation tools for performance
+- **Theme Support**: Dark theme support where available
+
 ## Audio Extraction System
 
 The application includes a comprehensive audio extraction system for downloading and processing audio content from external services using yt-dlp.
@@ -514,7 +704,7 @@ backend/sounds/originals/extracted/thumbnails/  # Extracted thumbnails
 - **Full mypy Compliance**: Complete type checking across all Python code
 - **Async/Await Patterns**: Proper async programming throughout the stack
 - **Error Handling**: Comprehensive exception handling with detailed logging
-- **Test Coverage**: 95+ comprehensive tests with 100% critical path coverage including repository, service, and integration tests
+- **Test Coverage**: 100+ comprehensive tests with high critical path coverage including repository, service, integration, and API tests
 
 ### Performance Optimizations
 - **Lazy Loading Management**: Proper SQLAlchemy relationship loading