From 267ff65da4ae9054c129439319752db18a4aca31 Mon Sep 17 00:00:00 2001 From: JSC Date: Wed, 13 Aug 2025 09:56:15 +0200 Subject: [PATCH] Update CLAUDE.md to enhance documentation with new dashboard and file serving systems; add dependencies and improve admin user management details --- CLAUDE.md | 208 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 199 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9c9482f..2350d92 100644 --- a/CLAUDE.md +++ b/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