# Sprint G005 — Image Processing Engine

## Objective

The Media Engine Foundation (G004) has already been implemented successfully.

Do NOT redesign or replace it.

Your responsibility is to review the existing implementation first, then extend it into a production-ready Image Processing Engine while preserving the current architecture.

---

# Phase 1 — Architecture Review (Mandatory)

Before writing any code, perform a complete review of the existing Media Engine implementation.

Analyze:

- MediaService responsibilities
- Upload flow
- Controller responsibilities
- Routing
- Storage hierarchy
- JSON metadata structure
- Validation flow
- Current extension points
- Existing UI interaction
- Security implementation

Determine whether the current architecture is suitable for image processing.

If it is already appropriate:

- Extend it.
- Do NOT redesign it.
- Only introduce changes if they provide a clear architectural benefit with minimal breaking changes.

---

# Existing Architecture

The Media Engine (G004) already provides:

- Secure upload
- Secure delete
- Secure serve
- JSON metadata persistence
- Drag & Drop UI
- Slot management
- Filesystem storage

This architecture must remain intact.

---

# Goal

Transform the upload pipeline into:

Upload
→ Validation
→ Temporary File
→ Crop (optional)
→ Resize
→ Compress
→ Strip Metadata (EXIF)
→ Convert to WebP
→ Save
→ Persist JSON

without changing how MediaService is consumed.

---

# Image Processing Pipeline

Implement a reusable Image Processing Engine.

Recommended architecture:

MediaService

- validate()
- upload()

↓

ImageProcessor

- crop()
- resize()
- optimise()
- stripMetadata()
- convertToWebP()
- save()

↓

persist()

The ImageProcessor should be reusable for future modules.

---

# Cropping

Implement interactive image cropping before upload.

Recommended library:

Cropper.js

Enable cropping for:

- Hero Image
- Couple Photos
- Gallery Images
- Story Images
- Gift QR Image
- Music Cover

Do NOT enable cropping for:

- MP3 files

---

# Resize

Automatically resize uploaded images.

Requirements:

- Maintain aspect ratio
- Never upscale images

Recommended maximum dimensions:

Hero:
1920px

Couple:
1600px

Gallery:
1600px

Story:
1600px

Gift:
1200px

Music Cover:
1200px

---

# Compression

Automatically optimise images.

Goals:

- Small file size
- High visual quality
- No visible artifacts

---

# WebP Conversion

Convert processed images into WebP.

Requirements:

- Preserve transparency
- Preserve orientation
- Generate only WebP output unless another format is technically required

---

# Metadata Removal

Strip unnecessary metadata.

Remove:

- EXIF
- GPS
- Camera information

while preserving image orientation.

---

# Validation

Review the existing validation.

Maintain:

- MIME validation
- File size validation
- Upload security

Improve only if necessary.

---

# Storage

Do NOT change:

storage/uploads/couples/

Do NOT modify:

- Folder hierarchy
- JSON schema
- Database structure

---

# Controller

Keep controllers thin.

Business logic belongs inside services.

---

# Routing

Keep existing routes unchanged unless absolutely necessary.

---

# UI

Preserve the current Media Manager UI.

Enhance it with:

- Crop dialog
- Processing indicator
- Upload progress
- Preview after optimisation

Do not redesign the page.

---

# Performance

Optimise memory usage.

Large images should be processed safely without exhausting PHP memory.

---

# Compatibility

Maintain compatibility with:

- Hero
- Couple
- Gallery
- Story
- Gift
- Music Cover

Do NOT process:

- MP3 files

---

# Security

Maintain all existing security protections.

Review:

- MIME validation
- Path traversal prevention
- UUID filenames
- Direct storage protection

Improve only where necessary.

---

# Deliverables

Produce:

- New services (if required)
- Updated MediaService
- Updated Media UI
- Configuration updates (if required)
- Technical documentation

Do NOT create database migrations unless absolutely necessary.

---

# Validation

Before completing the sprint:

- Verify every modified file
- Ensure no syntax errors
- Verify upload flow
- Verify processed images render correctly
- Verify JSON metadata remains compatible
- Verify existing Media Engine functionality continues to work

---

# Important

This sprint is an extension of G004, not a rewrite.

Prioritise:

- Maintainability
- Backward compatibility
- Clean architecture
- Minimal breaking changes

Always review the existing implementation before introducing any modifications.