Media & Imaging - Integration Guide

Overview

The Media & Imaging system handles all image uploads for Malets — product photos, service images, banners, and more. It features progressive loading with blur-up placeholders, direct-to-cloud uploads via presigned URLs, and optional AI-powered background removal.

Quick Start

Uploading Images

The MediaUploader component is used throughout the management interface (product creation, service editing, blog posts, etc.):

1. Click the "+ Add Media" button or drag and drop files onto the upload area
2. Watch the circular progress ring as the file uploads directly to cloud storage
3. After upload, the server processes the image (generates thumbnails, blur placeholder)
4. The image appears with a smooth blur-to-sharp transition

Supported Formats

Size limit: 10 MB per file

AI Background Removal

When uploading product images, enable the "Remove BG" toggle to automatically remove the background:

1. Toggle the checkbox before uploading
2. Upload your image normally
3. The server's AI model processes the image during confirmation
4. Result: clean product image with transparent background and adaptive shadow

Progressive Image Loading

How It Works

Every image across the Ngwenya platform uses progressive loading for a polished experience:

1. Instant: A tiny, blurred version (LQIP — Low Quality Image Placeholder) renders immediately
2. Loading: The full-resolution image loads in the background
3. Transition: A smooth 400ms cross-fade reveals the sharp image

If no blur placeholder is available, a shimmer animation plays instead.

Image Uploader

Upload Flow (Presigned S3)

The upload process is secure and efficient — files go directly to cloud storage without passing through the app server:

┌─────────┐     1. requestUploadUrl      ┌──────────┐
│ Browser │ ───────────────────────────▶  │  Media   │
│         │ ◀──── {uploadUrl, fileId} ──  │ Service  │
│         │                               └──────────┘
│         │     2. PUT file
│         │ ───────────────────────────▶  ┌──────────┐
│         │ ◀──── 200 OK ─────────────   │    S3    │
│         │                               └──────────┘
│         │     3. confirmUpload(fileId)  ┌──────────┐
│         │ ───────────────────────────▶  │  Media   │
│         │ ◀──── MediaFile ──────────   │ Service  │
└─────────┘                               └──────────┘

MediaUploader Component (Frontend)

<script>
	import MediaUploader from '$lib/components/manage/MediaUploader.svelte';
	let images = [];
</script>

<MediaUploader
	bind:images
	label="Product Images"
	maxImages={10}
	maletId="your-malet-id"
	allowBackgroundRemoval={true}
	on:change={(e) => console.log('Updated:', e.detail)}
/>

GraphQL Operations

requestUploadUrl (Mutation)

Request a presigned S3 upload URL:

mutation RequestUploadUrl($input: RequestUploadUrlInput!) {
	requestUploadUrl(input: $input) {
		uploadUrl # Presigned PUT URL (expires in 1 hour)
		fileId # Unique ID for confirmation step
		expiresAt # ISO timestamp
	}
}

confirmUpload (Mutation)

Confirm the upload and trigger processing:

mutation ConfirmUpload($fileId: String!) {
	confirmUpload(fileId: $fileId) {
		id
		url # Public CDN URL
		blurDataUrl # Base64 LQIP (for ProgressiveImage)
		thumbnails {
			label
			url
			width
			height
		}
		metadata {
			width
			height
			format
			size
		}
		status # PENDING → COMPLETE
	}
}

Integration Checklist

Progressive Image Loading

• Render ProgressiveImage with blurDataUrl — verify blur placeholder visible
• Wait for image to load — verify smooth cross-fade transition
• Render without blurDataUrl — verify shimmer animation plays
• Test with broken src — verify error placeholder appears

Image Uploader

• Click "+ Add Media" — verify file dialog opens
• Select a valid image — verify progress ring appears
• After processing — verify image thumbnail appears in the grid
• Drag and drop files — verify drop zone highlight and upload
• Reach maxImages limit — verify "+ Add Media" button disappears

AI Background Removal

• Enable "Remove BG" toggle before uploading
• Upload a product photo — verify processing takes slightly longer
• Verify result has transparent/clean background

Environment Variables