# 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
```rust
// 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
```rust
// 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