sdb2-claude/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Backend (Python/FastAPI)
- **Development server**: `cd backend && uv run python run.py` or `cd backend && uv run uvicorn app.main:app --reload`
- **Tests**: `cd backend && uv run pytest` (uses pytest with asyncio support)
- **Coverage**: `cd backend && uv run coverage run -m pytest && uv run coverage report`
- **Linting**: `cd backend && uv run ruff check` and `cd backend && uv run ruff format`
- **Type checking**: `cd backend && uv run mypy .`
- **Install dependencies**: `cd backend && uv sync`

### Frontend (React/TypeScript/Vite)
- **Development server**: `cd frontend && bun dev` (runs on port 8001)
- **Build**: `cd frontend && bun run build`
- **Linting**: `cd frontend && bun run lint`
- **Preview build**: `cd frontend && bun run preview`
- **Install dependencies**: `cd frontend && bun install`

## Architecture Overview

This is a soundboard application with a FastAPI backend and React frontend.

### Backend Architecture
- **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, apscheduler
- **Structure**:
  - `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, credit_decorators.py)
  - `tests/`: Comprehensive test suite with pytest and asyncio support

### Frontend Architecture
- **Framework**: React 19 with TypeScript
- **Build Tool**: Vite with SWC for fast development and builds
- **UI Library**: Comprehensive Radix UI component system with shadcn/ui
- **Styling**: Tailwind CSS v4 with custom components
- **Theming**: next-themes with dark mode support via ThemeProvider and ModeToggle
- **Routing**: React Router v7
- **Package Manager**: Bun for fast package management
- **Key Dependencies**: @radix-ui components, lucide-react icons, recharts, sonner notifications
- **Structure**:
  - `src/components/ui/`: Complete UI component library (button, card, dialog, table, etc.)
  - `src/components/`: App-specific components (ThemeProvider, ModeToggle)
  - `src/hooks/`: Custom React hooks (use-mobile.ts)
  - `src/lib/`: Utility functions (utils.ts with cn helper)
  - `src/contexts/`: React contexts (empty, ready for state management)
  - `src/assets/`: Static assets

### Key Models
- **User**: Authentication, plans, credits, API tokens
- **UserOAuth**: OAuth provider connections (Google, GitHub) with unique constraints
- **Plan**: User subscription plans and limits
- **Sound**: Audio files with metadata, normalization fields, play counts, **unique hash constraint**
- **Playlist**: User-created sound collections
- **PlaylistSound**: Many-to-many relationship between playlists and sounds
- **Extraction**: Audio extraction jobs from external services with async processing and flexible service detection
- **SoundPlayed**: Play history tracking with user and sound associations
- **CreditTransaction**: Comprehensive credit system transaction logging with metadata

### Database
- SQLite database at `backend/data/soundboard.db`
- Models use SQLModel (Pydantic + SQLAlchemy)
- Async database operations with aiosqlite
- **Data Integrity**: Unique constraints on sound hash, OAuth provider+user combinations
- **Foreign Key Relationships**: Proper cascading and relationship management

### Configuration
- Backend settings in `backend/app/core/config.py` using pydantic-settings
- Environment variables loaded from `.env` files
- Configurable settings: database URL, JWT secrets, OAuth2 client credentials, logging, cookies, audio normalization, audio extraction, credits system
- Default ports: Backend (8000), Frontend (8001)
- OAuth redirect URL: `http://localhost:8001/auth/callback`

### Development Notes
- Backend runs on port 8000 by default (configurable via HOST/PORT env vars)
- Frontend dev server runs on port 8001
- Project uses Python 3.12+ with uv package manager for backend
- Frontend uses TypeScript 5.8+ with strict mode enabled
- Comprehensive linting: Ruff (backend), ESLint (frontend)
- Type checking: mypy (backend), TypeScript (frontend)
- Testing: pytest with asyncio support and coverage reporting (90+ comprehensive tests including repository, service, and integration tests)
- Logs stored in `backend/logs/app.log` with rotation
- Audio files stored in `backend/sounds/` directory structure (originals, normalized, extracted)
- Database file at `backend/data/soundboard.db`
- Extraction processing uses background workers with configurable concurrency limits

## Credit System

The application includes a comprehensive credit-based system for managing user actions and resource consumption.

### Credit Features
- **Action-based Deductions**: Credits are deducted for specific actions (VLC play, audio extraction, etc.)
- **Transaction Logging**: All credit changes are logged with detailed metadata
- **Plan Integration**: Credit limits and replenishment tied to user subscription plans
- **Real-time Updates**: WebSocket events notify users of credit changes
- **Admin Management**: Administrative controls for credit adjustments

### Credit Actions
- **VLC Play Sound**: Deducts credits when playing sounds through VLC
- **Audio Extraction**: Deducts credits for extracting audio from external URLs
- **Credit Addition**: Administrative credit bonuses and plan-based replenishment

### Database Schema (CreditTransaction Model)
- **Comprehensive Tracking**: User ID, action type, amount, balance before/after
- **Metadata Storage**: JSON metadata for action-specific details
- **Success Tracking**: Boolean flag for successful/failed transactions
- **Temporal Ordering**: Created/updated timestamps for audit trails

### API Integration
- **Automatic Deduction**: Services automatically deduct credits during operations
- **Balance Checking**: Credit validation before expensive operations
- **Transaction History**: API endpoints for viewing credit transaction history
- **Real-time Events**: WebSocket emission of `user_credits_changed` events

### Technical Implementation
- **Service**: `app/services/credit.py` - Core credit management with WebSocket integration
- **Repository**: `app/repositories/credit_transaction.py` - Database operations for credit transactions
- **Models**: `CreditTransaction` model with comprehensive metadata tracking
- **Testing**: 14 comprehensive tests covering all credit scenarios

## Sound Management System

Enhanced sound management with comprehensive duplicate prevention and integrity features.

### Sound Features
- **Duplicate Prevention**: Unique hash constraint prevents duplicate audio files
- **Metadata Tracking**: Complete audio file metadata (duration, size, hash, type)
- **Play Count Tracking**: Usage statistics for popular sounds analysis
- **Type Classification**: SDB (soundboard), TTS (text-to-speech), EXT (extracted) categorization
- **Normalization Support**: Integration with audio normalization system
- **File Integrity**: SHA-256 hash verification for data integrity

### Database Constraints
- **Unique Hash**: `UniqueConstraint("hash", name="uq_sound_hash")` prevents duplicate files
- **Data Integrity**: Proper foreign key relationships and nullable field handling
- **Indexed Fields**: Optimized queries for common operations (filename, hash, type)

### API Endpoints
- `GET /api/v1/sounds/`: Get all sounds with optional type filtering (authenticated users only)
  - Query parameters: `types` (can be specified multiple times for filtering by multiple types)
  - Examples: 
    - `GET /api/v1/sounds/` - Returns all sounds
    - `GET /api/v1/sounds/?types=SDB` - Returns only SDB type sounds  
    - `GET /api/v1/sounds/?types=SDB&types=EXT` - Returns SDB and EXT type sounds
- `POST /api/v1/sounds/play/{sound_id}`: Play sound with VLC (requires 1 credit)
- `POST /api/v1/sounds/stop`: Stop all VLC instances

### Sound Type Filtering Features
- **Authentication Required**: All sound endpoints require valid user authentication
- **Type-based Filtering**: Filter sounds by one or more types (SDB, TTS, EXT)
- **Flexible Query Parameters**: Multiple `types` parameters supported for complex filtering
- **Empty Results**: Invalid types return empty list without error
- **Performance Optimized**: Uses SQLAlchemy `IN` clause for efficient multi-type queries

### Technical Implementation
- **Repository**: `app/repositories/sound.py` - Complete CRUD operations with specialized queries including `get_by_types()` for type filtering
- **Models**: Enhanced `Sound` model with unique constraints and relationship management
- **API Integration**: Sound creation, update, deletion with duplicate prevention, authenticated sound retrieval
- **Testing**: 15+ comprehensive tests covering all sound operations including constraint validation and API endpoint testing

## Player System

Comprehensive audio player service with VLC backend for playlist management and audio playback.

### Player Features
- **VLC Integration**: Uses VLC media player as the backend for reliable audio playback
- **Playlist Management**: Dynamic playlist loading and reloading with state persistence
- **Intelligent Track Handling**: Smart playlist reload logic with track position tracking
- **Multiple Playback Modes**: Continuous, loop, loop-one, random, and single play modes
- **Play Count Tracking**: Automatic play count updates with 20% threshold detection
- **Real-time Position Tracking**: Background thread for position updates and auto-advance
- **WebSocket Broadcasting**: Real-time state updates via WebSocket connections
- **Credit Integration**: Automatic credit deduction for VLC-based sound plays

### Playlist Reload Logic
- **ID-based Comparison**: Compares playlist IDs to determine reload behavior
- **Playlist Change Handling**: When playlist ID changes, stops player and resets to first track
- **Track Position Tracking**: When same playlist, tracks if current song moved to different index
- **Missing Track Handling**: When current track removed, stops player and sets first available track
- **Empty Playlist Support**: Graceful handling of empty playlists with state clearing
- **State Consistency**: Ensures player state remains consistent across all reload scenarios

### Player State Management
- **Status Tracking**: Playing, paused, stopped states with proper transitions
- **Sound Information**: Current track ID, index, position, duration tracking
- **Playlist Metadata**: Playlist ID, name, length, total duration, and sound list
- **Volume Control**: Volume management with range validation (0-100)
- **Position Tracking**: Real-time playback position with seek functionality

### Database Integration
- **Play History**: Records `SoundPlayed` entries for player-based plays (no user association)
- **Sound Statistics**: Updates sound play counts automatically when 20% threshold reached
- **Playlist Synchronization**: Syncs with database playlist changes via reload mechanism
- **Session Management**: Proper async database session handling with connection cleanup

### Technical Implementation
- **Service**: `app/services/player.py` - Core player logic with VLC integration
- **State Management**: PlayerState class for comprehensive state tracking
- **Background Threading**: Position tracking thread for non-blocking operations
- **Async Operations**: Full async/await support for database operations
- **Error Handling**: Comprehensive error handling with graceful degradation
- **Memory Management**: Proper cleanup of resources and background tasks

### Player Modes
- **Continuous**: Plays through playlist once then stops
- **Loop**: Repeats entire playlist indefinitely
- **Loop One**: Repeats current track indefinitely
- **Random**: Plays tracks in random order
- **Single**: Plays current track once then stops

### API Integration
- **REST Endpoints**: Player control via HTTP API (`app/api/v1/player.py`)
- **WebSocket Events**: Real-time state broadcasting to connected clients
- **Authentication**: Supports both authenticated and unauthenticated playback
- **Global Service**: Singleton player service accessible throughout the application

### Testing Coverage
- **49 comprehensive tests** covering all player functionality including:
  - State management and serialization
  - Playback control (play, pause, stop, seek)
  - Playlist reload scenarios with ID changes
  - Track position tracking and updates
  - Helper method validation
  - 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

Comprehensive repository pattern implementation with full test coverage for data access layer.

### Repository Architecture
- **Base Repository**: `app/repositories/base.py` - Generic CRUD operations with type safety
- **Specialized Repositories**: Domain-specific repositories extending base functionality
- **Async Operations**: Full async/await support for non-blocking database operations
- **Error Handling**: Comprehensive exception handling with logging

### Repository Coverage
- **User Repository**: User management, authentication, role-based operations
- **Sound Repository**: Audio file management with specialized queries including type-based filtering (`get_by_types()`, `get_by_type()`, `get_by_hash()`, `search_by_name()`, etc.)
- **Credit Transaction Repository**: Credit system transaction management  
- **User OAuth Repository**: OAuth provider management and authentication
- **Playlist Repository**: Playlist management and sound associations
- **Extraction Repository**: Audio extraction job management

### Testing Infrastructure
- **80+ Repository Tests**: Comprehensive test coverage across all repositories
- **Async Test Support**: Proper async/await testing with pytest-asyncio
- **SQLAlchemy Integration**: Proper session management and lazy loading handling
- **Type Safety**: Complete mypy type checking compliance
- **Fixture Management**: Reusable test fixtures with proper dependency injection

### Test Categories
- **CRUD Operations**: Create, read, update, delete operations for all entities
- **Constraint Validation**: Unique constraint and foreign key relationship testing
- **Pagination Testing**: Limit/offset pagination with proper ordering
- **Error Scenarios**: Exception handling and error condition testing
- **Performance Tests**: Query optimization and efficient data access patterns

## Sound Normalization System

The application includes a comprehensive audio normalization system using FFmpeg's loudnorm filter for professional-quality audio processing.

### Normalization Features
- **Two-pass normalization**: Default high-quality mode with analysis and normalization phases
- **One-pass normalization**: Fast mode for quick processing or as fallback
- **Intelligent fallback**: Automatically switches to one-pass for problematic audio (infinite analysis values)
- **Batch processing**: Normalize all sounds or filter by type (SDB, TTS, EXT)
- **Admin-only access**: Normalization endpoints require administrator privileges
- **Comprehensive logging**: Detailed FFmpeg output and error handling

### Directory Structure
```
backend/sounds/
├── originals/
│   ├── soundboard/     # SDB type sounds
│   ├── text_to_speech/ # TTS type sounds
│   └── extracted/      # EXT type sounds
└── normalized/
    ├── soundboard/     # Normalized SDB sounds
    ├── text_to_speech/ # Normalized TTS sounds
    └── extracted/      # Normalized EXT sounds
```

### Configuration (Environment Variables)
- `NORMALIZED_AUDIO_FORMAT`: Output format (default: "mp3")
- `NORMALIZED_AUDIO_BITRATE`: Bitrate setting (default: "256k")
- `NORMALIZED_AUDIO_PASSES`: 1 for one-pass, 2 for two-pass (default: 2)

### Database Fields (Sound Model)
- `is_normalized`: Boolean flag indicating normalization status
- `normalized_filename`: Filename of normalized audio file
- `normalized_duration`: Duration in milliseconds of normalized file
- `normalized_size`: File size in bytes of normalized file
- `normalized_hash`: SHA-256 hash of normalized file for integrity

### API Endpoints
- `POST /api/v1/sounds/normalize/all`: Normalize all unnormalized sounds
- `POST /api/v1/sounds/normalize/type/{sound_type}`: Normalize sounds by type
- `POST /api/v1/sounds/normalize/{sound_id}`: Normalize specific sound
- **Parameters**: `force` (re-normalize already processed), `one_pass` (override config)

### Technical Implementation
- **Service**: `app/services/sound_normalizer.py` - Core normalization logic
- **API**: `app/api/v1/sounds.py` - REST endpoints (consolidated with other sound endpoints)
- **Repository**: Enhanced `app/repositories/sound.py` with normalization queries
- **Dependencies**: Requires FFmpeg installed on system, uses ffmpeg-python library
- **Error Handling**: Graceful fallback for edge cases (silent audio, infinite values)
- **Session Management**: Handles SQLModel session detachment in batch operations

### Normalization Process
1. **Analysis Phase** (two-pass only): Analyze audio characteristics
2. **Validation**: Check for invalid analysis values (inf, -inf, nan)
3. **Fallback Logic**: Switch to one-pass if analysis contains invalid values
4. **Normalization**: Apply loudnorm filter with target levels (I=-23, TP=-2, LRA=7)
5. **Database Update**: Store normalized file metadata and set is_normalized flag

### Testing
- 17 comprehensive service tests covering all normalization scenarios
- 16 API endpoint tests with authentication and authorization checks
- Edge case handling for problematic audio files
- Mock FFmpeg operations for reliable testing

## Sound Scanner System

The application includes a sound scanner service for automatically discovering, importing, and managing audio files in the filesystem.

### Scanner Features
- **File Discovery**: Recursively scans sound directories for audio files
- **Format Support**: Handles multiple audio formats (.mp3, .wav, .flac, .ogg, .m4a, etc.)
- **Metadata Extraction**: Uses FFmpeg to extract duration and file information
- **Database Sync**: Automatically adds new files, updates existing ones, removes deleted files
- **Admin-only Access**: Scanning operations require administrator privileges
- **Comprehensive Reporting**: Detailed results showing added, updated, deleted, and skipped files
- **Duplicate Prevention**: Integration with unique hash constraint system

### Technical Implementation
- **Service**: `app/services/sound_scanner.py` - Core scanning and import logic
- **API**: `app/api/v1/sounds.py` - REST endpoint for scanning operations
- **Dependencies**: Requires FFmpeg for metadata extraction
- **Error Handling**: Graceful handling of corrupted or unreadable files
- **Hash-based Detection**: Uses SHA-256 hashing to detect file changes and prevent duplicates

### Scanning Process
1. **Directory Traversal**: Recursively scan configured sound directories
2. **File Validation**: Check file extensions and accessibility
3. **Metadata Extraction**: Extract duration, size, and hash using FFmpeg
4. **Database Comparison**: Compare with existing database records
5. **Duplicate Detection**: Check unique hash constraint before insertion
6. **Sync Operations**: Add new files, update changed files, remove deleted files
7. **Results Reporting**: Return detailed scan results with statistics

### API Endpoints
- `POST /api/v1/sounds/scan`: Scan and sync sound directories

## WebSocket/Socket.IO System

Real-time communication system using WebSocket connections for live updates and messaging.

### Socket Features
- **Real-time Communication**: WebSocket-based messaging between users
- **Connection Management**: Track connected users and connection status
- **User-to-User Messaging**: Send messages to specific users
- **Connection Status**: Get current connection status and user count
- **Authentication Integration**: Uses existing user authentication system
- **Credit Change Notifications**: Real-time credit balance updates via `user_credits_changed` events

### Technical Implementation
- **Service**: `app/services/socket.py` - Socket.IO manager and connection handling
- **API**: `app/api/v1/socket.py` - REST endpoints for socket operations
- **Manager**: Centralized socket connection management with user tracking
- **Authentication**: Integrated with existing JWT authentication system
- **Event System**: Structured event emission for various application events

### API Endpoints
- `GET /api/v1/socket/status`: Get current socket connection status
- `POST /api/v1/socket/send-message`: Send a message to a specific user via WebSocket

### Socket Events
- **Connection Management**: Connection and disconnection tracking
- **User Messages**: User-specific message routing
- **Credit Updates**: `user_credits_changed` events with detailed transaction data
- **Real-time Status**: Live application status updates

## Audio Utilities

Shared utility functions for audio file processing used across multiple services.

### Audio Utility Functions
- **File Hashing**: `get_file_hash()` - Calculate SHA-256 hash of audio files for integrity checking
- **File Size**: `get_file_size()` - Get file size in bytes for metadata storage
- **Duration Extraction**: `get_audio_duration()` - Extract audio duration in milliseconds using FFmpeg

### Technical Implementation
- **Module**: `app/utils/audio.py` - Shared audio processing utilities
- **Dependencies**: Uses FFmpeg via ffmpeg-python for duration extraction
- **Error Handling**: Graceful fallback for corrupted or unreadable files
- **Consistent Interface**: Same function signatures across all audio services

### Usage
- **Sound Scanner**: Uses utilities for file discovery and metadata extraction
- **Sound Normalizer**: Uses utilities for normalized file verification and metadata
- **Audio Extraction**: Uses utilities for extracted audio file metadata and validation
- **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
- **Health Check**: Available at `/api/v1/health` - API health status endpoint
- **Scalar**: Available at `/api/v1/docs/scalar` - Modern API reference
- **RapiDoc**: Available at `/api/v1/docs/rapidoc` - Fast, customizable docs
- **Stoplight Elements**: Available at `/api/v1/docs/elements` - 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.

### Extraction Features
- **Immediate Response**: API endpoints return immediately without waiting for yt-dlp processing
- **Background Processing**: Actual extraction happens asynchronously in background worker threads
- **Multi-Service Support**: Supports YouTube, SoundCloud, Vimeo, DailyMotion, TikTok, Twitter, Instagram
- **Non-blocking Operations**: yt-dlp operations run in thread pools to prevent event loop blocking
- **Concurrent Processing**: Configurable maximum concurrent extractions with queue management
- **Automatic Normalization**: Extracted audio is automatically normalized using the sound normalization system
- **Error Handling**: Comprehensive error handling with detailed logging and status tracking
- **Credit Integration**: Automatic credit deduction for extraction operations

### Database Schema (Extraction Model)
- **Flexible Service Detection**: `service` and `service_id` are nullable during creation, populated during processing
- **Status Tracking**: `pending` → `processing` → `completed`/`failed`
- **Metadata Storage**: URL, title, user association, linked sound record
- **Error Logging**: Detailed error messages for failed extractions

### Directory Structure
```
backend/sounds/temp/          # Temporary extraction workspace
backend/sounds/originals/extracted/  # Final extracted audio files
backend/sounds/originals/extracted/thumbnails/  # Extracted thumbnails
```

### Configuration (Environment Variables)
- `EXTRACTION_AUDIO_FORMAT`: Output audio format (default: "mp3")
- `EXTRACTION_AUDIO_BITRATE`: Audio bitrate setting (default: "256k")
- `EXTRACTION_TEMP_DIR`: Temporary extraction directory (default: "sounds/temp")
- `EXTRACTION_THUMBNAILS_DIR`: Thumbnail storage directory (default: "sounds/originals/extracted/thumbnails")
- `EXTRACTION_MAX_CONCURRENT`: Maximum concurrent extractions (default: 2)

### API Endpoints
- `POST /api/v1/extractions/`: Create extraction job (immediate response)
- `GET /api/v1/admin/extractions/status`: Get extraction processor status (admin only)
- `GET /api/v1/extractions/{extraction_id}`: Get specific extraction info
- `GET /api/v1/extractions/`: Get user's extraction history

### Technical Implementation
- **Service**: `app/services/extraction.py` - Core extraction logic with async yt-dlp operations
- **Processor**: `app/services/extraction_processor.py` - Background queue manager with concurrency control
- **Repository**: `app/repositories/extraction.py` - Database operations for extraction records
- **API**: `app/api/v1/extractions.py` - Dedicated extraction API endpoints, `app/api/v1/admin/extractions.py` - Admin extraction endpoints
- **Dependencies**: Requires yt-dlp for media extraction, FFmpeg for audio processing
- **Async Operations**: All blocking I/O operations wrapped in `asyncio.to_thread()` for non-blocking execution

### Extraction Process
1. **Creation**: Immediate API response with extraction record (service info null)
2. **Queue**: Background processor picks up pending extractions
3. **Service Detection**: yt-dlp identifies service and media metadata (non-blocking)
4. **Duplicate Check**: Verify no existing extraction for same service/media
5. **Media Download**: Extract audio and thumbnails using yt-dlp (non-blocking)
6. **File Processing**: Move files to final locations with sanitized names
7. **Sound Creation**: Create Sound database record with metadata and unique hash
8. **Normalization**: Automatically normalize extracted audio
9. **Status Update**: Mark extraction as completed with sound association

### Concurrency and Performance
- **Thread Pool Execution**: yt-dlp operations run in separate threads
- **Queue Management**: Background processor manages extraction queue
- **Concurrent Limits**: Configurable maximum concurrent extractions
- **Non-blocking API**: Other endpoints remain responsive during extraction
- **Resource Management**: Automatic cleanup of temporary files

### Error Handling
- **Service Detection Failures**: Invalid URLs handled gracefully during processing
- **Download Failures**: Network issues, geo-restrictions, or unavailable content
- **Processing Failures**: File system errors, FFmpeg issues, or corruption
- **Duplicate Prevention**: Service-level duplicate detection during processing
- **Comprehensive Logging**: Detailed error messages and extraction status tracking

### API Organization
- **Dedicated Extraction Endpoints**: Extraction functionality separated into `/api/v1/extractions/` for better organization
- **Admin Separation**: Admin-only endpoints moved to `/api/v1/admin/extractions/` for proper access control
- **Consistent URL Structure**: RESTful endpoint design following FastAPI best practices
- **Router Registration**: Proper router mounting and tag organization for API documentation

### Testing
- **16 comprehensive service tests** covering all extraction scenarios including async operations
- **API endpoint tests** with authentication and background processing validation
- **Error handling tests** for various failure scenarios
- **Mock yt-dlp operations** for reliable testing without network dependencies
- **Concurrency tests** validating non-blocking behavior and thread pool execution
- **Endpoint migration tests** ensuring proper URL routing and authentication

## Data Integrity & Performance

### Database Constraints
- **Sound Hash Uniqueness**: Prevents duplicate audio files via unique hash constraint
- **OAuth Provider Uniqueness**: Prevents duplicate OAuth connections per provider
- **Foreign Key Integrity**: Proper cascading relationships between all models
- **Index Optimization**: Strategic indexing for common query patterns

### Type Safety & Code Quality
- **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**: 100+ comprehensive tests with high critical path coverage including repository, service, integration, and API tests

### Performance Optimizations
- **Lazy Loading Management**: Proper SQLAlchemy relationship loading
- **Query Optimization**: Efficient database queries with pagination support
- **Background Processing**: Non-blocking operations for expensive tasks
- **Resource Management**: Proper cleanup of temporary files and connections

## Development Best Practices

### Code Organization
- **Repository Pattern**: Clean separation of data access logic
- **Service Layer**: Business logic encapsulation with dependency injection
- **Type Safety**: Comprehensive type annotations and mypy compliance
- **Error Handling**: Structured exception handling with proper logging

### Testing Strategy
- **Unit Tests**: Comprehensive repository and service layer testing
- **Integration Tests**: End-to-end API testing with authentication
- **Async Testing**: Proper async/await testing patterns with pytest-asyncio
- **Mock Strategies**: External service mocking for reliable testing

### Security & Authentication
- **JWT Token Management**: Secure token-based authentication
- **OAuth Integration**: Third-party authentication with proper scoping
- **Role-based Access**: Admin/user role separation for sensitive operations
- **Input Validation**: Comprehensive request validation with Pydantic schemas

### Monitoring & Logging
- **Structured Logging**: Consistent logging patterns across all services
- **Error Tracking**: Comprehensive exception logging with context
- **Performance Monitoring**: Request timing and resource usage tracking
- **Audit Trails**: Complete transaction history for credit and user operations