Architecture & Design Decisions

Overview

The Media Processor is built using a Service-Oriented Architecture (SOA) pattern with emphasis on separation of concerns, reusability, and maintainability. This document outlines the architectural decisions and design patterns used.

Architecture Layers

┌─────────────────────────────────────────┐
│         Program.cs (Entry Point)        │
│  ├─ Argument Parsing                    │
│  └─ Error Handling                      │
├─────────────────────────────────────────┤
│     MediaProcessorService (Orchestrator)│
│  ├─ Coordinates all services            │
│  └─ Executes workflow                   │
├─────────────────────────────────────────┤
│            Service Layer                │
│  ├─ FileValidationService               │
│  ├─ TemporaryFolderService              │
│  ├─ ImageProcessingService              │
│  └─ VideoProcessingService              │
├─────────────────────────────────────────┤
│            Model Layer                  │
│  ├─ MediaType (Enum)                    │
│  ├─ MediaFile (Domain Model)            │
│  └─ OperationResult (Result Pattern)    │
└─────────────────────────────────────────┘

Design Patterns Used

1. Service-Oriented Architecture

Each logical responsibility is encapsulated in its own service:

FileValidationService

Validates file format
Checks file integrity
Manages supported format lists

TemporaryFolderService

Creates temporary directories
Manages subfolder creation
Handles cleanup operations

ImageProcessingService

Copies images to destination
Handles image-specific operations

VideoProcessingService

Extracts video frames
Gets video metadata
Manages FFMpeg integration

MediaProcessorService (Orchestrator)

Coordinates all services
Executes the main workflow
Manages service lifecycle

2. Result Pattern

Operations return standardized OperationResult objects instead of throwing exceptions:

public class OperationResult
{
    public bool Success { get; set; }
    public string Message { get; set; }
    public string? OutputPath { get; set; }
}

Benefits:

Explicit error handling
No hidden exceptions
Fluent API for result inspection
Better for error logging and reporting

3. Domain Models

MediaType Enum: Ensures type safety for media classification
MediaFile: Encapsulates file information and validation state
OperationResult: Standardizes all operation responses

4. Resource Management (IDisposable)

TemporaryFolderService implements IDisposable:

public class TemporaryFolderService : IDisposable
{
    public void Dispose() { /* cleanup */ }
}

Used with using statement in Program.cs:

using (var processor = new MediaProcessorService())
{
    // Processing happens here
} // Automatic cleanup on exit

Benefits:

Guaranteed cleanup of temporary files
Proper resource disposal
Finalizer for safety net

5. Fail-Fast Validation

Each step validates its inputs before proceeding:

1. File exists? → No → Return error
2. Valid format? → No → Return error
3. Temp folder created? → Yes → Continue
4. Process file → Return result

Separation of Concerns

Service	Responsibility	Dependencies
FileValidationService	Format validation	None - Stateless
TemporaryFolderService	Folder lifecycle	System.IO, IDisposable
ImageProcessingService	Image operations	System.IO
VideoProcessingService	Video operations	FFMpegCore
MediaProcessorService	Orchestration	All services
Program	Application flow	MediaProcessorService

Data Flow

User Input (file path)
        ↓
Program.cs validates argument
        ↓
MediaProcessorService.ProcessMedia()
        ├─ FileValidationService.ValidateMediaFile()
        │   └─ Returns MediaFile with validation status
        ├─ TemporaryFolderService.CreateTempFolder()
        │   └─ Returns temp folder path
        └─ Based on media type:
           ├─ Image: ImageProcessingService.CopyImage()
           │   └─ Returns OperationResult
           └─ Video: TemporaryFolderService.CreateSubfolder("video-frames")
               + VideoProcessingService.ExtractFrames()
               └─ Returns OperationResult
        ↓
Program.cs displays result

Error Handling Strategy

Multiple Levels of Error Handling

Service Level: Each service catches exceptions and returns results
Orchestrator Level: MediaProcessorService coordinates and reports errors
Program Level: Program.cs is the final error handler

Exception Handling

Example from VideoProcessingService:

try
{
    FFMpegArguments
        .FromFileInput(sourceVideoPath)
        .OutputToFile(frameOutputPattern, overwrite: true, options => ...)
        .ProcessSynchronously();
}
catch (FFMpegException ex)
{
    return OperationResult.CreateFailure($"FFMpeg error: {ex.Message}");
}
catch (Exception ex)
{
    return OperationResult.CreateFailure($"Unexpected error: {ex.Message}");
}

Error Messages

All error messages are:

User-friendly: Clear indication of what went wrong
Actionable: Guides user on what to do
Technical: Enough detail for debugging

Examples:

✗ Error: File does not exist: C:\nonexistent\video.mp4
✗ Error: Unsupported file format: .txt
✗ Error: Video file is corrupted or not accessible

Extensibility Points

The architecture allows easy extension for future features:

1. Add New Media Type

Add to MediaType enum
Create new [Type]ProcessingService
Update FileValidationService with extensions
Add handler in MediaProcessorService

2. Add Batch Processing

Create BatchProcessorService
Reuse existing services
Return batch results

3. Add Configuration

Create IConfigurationService
Pass to services via constructor
Modify behavior without code changes

4. Add Logging

Implement ILogger interface
Inject into services
Log at decision points

Technology Stack

Framework

.NET 8.0: Latest LTS framework
C# 12: Latest language features used
Nullable reference types: Type safety

Dependencies

FFMpegCore v5.1.0: Video frame extraction
- Wrapper around FFMpeg CLI
- Handles async operations
- Cross-platform support

Built-in Libraries

System.IO: File and folder operations
System.Collections.Generic: Collections

Performance Considerations

Memory Usage

Streams for large file reading (not in current version)
Lazy initialization of services
GC-friendly disposal patterns

Processing Efficiency

FFMpeg native performance (optimized C implementation)
Frame extraction runs synchronously (blocking)
Suitable for single files

Scalability Notes

Single file processing per execution
Batch processing requires separate implement
Video frame extraction uses FFMpeg's native speed

Configuration Options

Currently, configuration is hardcoded as safe defaults:

Supported Extensions (FileValidationService.cs):

Update SupportedImageExtensions set
Update SupportedVideoExtensions set

Temporary Folder (TemporaryFolderService.cs):

Uses Path.GetTempPath() (user's temp folder)
Could be configured for specific location

Frame Output (VideoProcessingService.cs):

PNG format (lossless)
Sequential naming: frame_0001.png, frame_0002.png
Could support format/naming configuration

Code Quality Standards

Documentation

XML documentation on all public members
Clear comments for complex logic
README and architecture guides

Naming Conventions

PascalCase for classes and methods
camelCase for private fields
Descriptive names explaining purpose

Error Handling

No swallowing exceptions
All operations return results
Meaningful error messages

Testing Readiness

Service classes are testable
Dependencies can be injected
No static dependencies (except for now)

Future Improvements

Short Term (Phase 2)

Configuration file support
Advanced image processing
Command-line options for frame extraction

Medium Term

Dependency injection container
Logging framework integration
Unit tests structure
Batch processing service

Long Term

REST API wrapper
Plugin architecture
Cloud storage support
Performance metrics/monitoring

Conclusion

The Media Processor is designed with maintainability, extensibility, and reliability as core principles. The service-oriented architecture makes it easy to understand, test, and extend, while solid error handling ensures robustness in production environments.

The foundation is flexible enough to support significant feature additions while maintaining code quality and architecture integrity.

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History