quaik8/sdb2-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
JSC
2025-08-13 09:56:15 +02:00
parent 63e759a1a0
commit 267ff65da4
1 changed files with 199 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

208
CLAUDE.md
View File

@@ -27,17 +27,17 @@ This is a soundboard application with a FastAPI backend and React frontend.
- **Framework**: FastAPI with SQLModel for database ORM - **Framework**: FastAPI with SQLModel for database ORM
- **Database**: SQLite with aiosqlite async driver - **Database**: SQLite with aiosqlite async driver
- **Authentication**: JWT tokens with OAuth2 support (Google, GitHub) - **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**: - **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/`: 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) - `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, etc.) - `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) - `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) - `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) - `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/core/`: Configuration, database setup, logging, dependencies, seeds
- `app/middleware/`: Custom middleware (logging) - `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 - `tests/`: Comprehensive test suite with pytest and asyncio support
### Frontend Architecture ### Frontend Architecture
@@ -235,6 +235,8 @@ Comprehensive audio player service with VLC backend for playlist management and
- Mode switching and volume control - Mode switching and volume control
- Play count tracking and credit integration - Play count tracking and credit integration
- Error handling and edge cases - 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 ## 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 - **Duplicate Prevention**: Hash calculation for unique constraint enforcement
- **Centralized Logic**: Eliminates code duplication between audio processing services - **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 ## Audio Extraction System
The application includes a comprehensive audio extraction system for downloading and processing audio content from external services using yt-dlp. 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 - **Full mypy Compliance**: Complete type checking across all Python code
- **Async/Await Patterns**: Proper async programming throughout the stack - **Async/Await Patterns**: Proper async programming throughout the stack
- **Error Handling**: Comprehensive exception handling with detailed logging - **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 ### Performance Optimizations
- **Lazy Loading Management**: Proper SQLAlchemy relationship loading - **Lazy Loading Management**: Proper SQLAlchemy relationship loading