church-api/.serena/memories/code_style_conventions.md

Church API Code Style & Conventions

Rust Code Style

Naming Conventions

• Functions: snake_case (e.g., get_video_duration_direct, transcode_hls_segment_ffmpeg)
• Types/Structs: PascalCase (e.g., StreamingTranscodingService, ChunkStreamingService)
• Constants: SCREAMING_SNAKE_CASE (e.g., TS_PACKET_SIZE, NUM_PACKETS)
• Variables: snake_case (e.g., source_path, media_item_id)
• Modules: snake_case (e.g., streaming_transcoding, chunk_streaming)

File Organization

• Handlers: src/handlers/*.rs - HTTP request handling
• Services: src/services/*.rs - Business logic layer
• Models: src/models/*.rs - Data models and database entities
• Utils: src/utils/*.rs - Shared utility functions
• DB: src/db/*.rs - Database access layer

Error Handling

• Uses custom ApiError type with Result<T> return type
• Comprehensive error mapping with .map_err() for external errors
• Structured error messages with context

Logging Style

// Informational with emoji indicators
tracing::info!("🚀 Using CLI ffmpeg with Intel QSV AV1 hardware decoding");
tracing::info!("✅ Segment {} transcoded successfully", segment_index);

// Warnings
tracing::warn!("⚠️ Creating placeholder segment {}", segment_index);

// Errors  
tracing::error!("❌ Failed to transcode segment {}: {:?}", segment_index, e);

// Debug information
tracing::debug!("🎬 FFmpeg command: {:?}", cmd);

Async/Await Patterns

• Extensive use of async/await with Tokio runtime
• Proper error propagation with ? operator
• Background task spawning with tokio::spawn()

Documentation

• Function-level documentation for public APIs
• Inline comments for complex logic
• TODO comments for known improvements needed

Architecture Patterns

Service Layer Pattern

• Services handle business logic
• Handlers are thin and focus on HTTP concerns only
• Clear separation between web layer and business logic

Error Handling Strategy

// Convert external errors to ApiError
.map_err(|e| ApiError::Internal(format!("Failed to run ffmpeg: {}", e)))?

Resource Management

• Use of Arc<RwLock<>> for shared mutable state
• Semaphores for limiting concurrent operations
• Proper cleanup in GStreamer pipelines

Configuration

• Environment variables used extensively (std::env::var)
• Sensible defaults provided
• Hardware acceleration detection and fallbacks

Performance Considerations

• Hardware acceleration preferred (VA-API, Intel QSV)
• Chunked/streaming processing for large media files
• Caching of transcoded segments
• Concurrent processing limits to prevent resource exhaustion

Dependencies Management

• Clear separation of concerns in Cargo.toml
• Comments explaining dependency purposes
• Both FFmpeg and GStreamer maintained during transition period