Media Infrastructure — Developer Guide

Overview

The Ngwenya platform provides a two-service media architecture — a core media service for uploads, image processing, and storage abstraction, and a dedicated video service for FFmpeg-based transcoding. Together, these services power all product imagery, Malet branding, and video content on the platform.

Architecture

graph TD
    A["Upload Request"] --> B["MediaService"]

    B --> C{"Image?"}
    C -->|Yes| D["ImageProcessorService"]
    C -->|No| G{"Video?"}

    D --> D1["sharp: WebP conversion"]
    D --> D2["sharp: 3 Thumbnails (parallel)"]
    D --> D3["sharp: Blur Placeholder (LQIP)"]
    D --> D4["exifr: EXIF Extraction"]
    D --> D5{"AI Enhance?"}
    D5 -->|Yes| D6["ImageEnhancementService"]
    D5 -->|No| E

    D1 --> E["StorageProvider.upload()"]
    G -->|Yes| H["VideoTranscodeService (TCP)"]
    G -->|No| E

    E --> F["CdnService.rewriteUrl()"]
    F --> I[("MongoDB: media_files")]

    H --> H1["FFmpeg: HLS + poster"]
    H1 --> E

    B --> J{"SHA-256 match?"}
    J -->|Duplicate| K["Clone record, skip reprocessing"]
    J -->|New| C

    style B fill:#22c55e,color:#fff
    style D fill:#3b82f6,color:#fff
    style H fill:#f59e0b,color:#fff
    style K fill:#8b5cf6,color:#fff

Upload Pipeline

Two Upload Modes

The platform supports two upload flows to accommodate different client needs:

Direct Upload Flow

Client → POST /media/upload (multipart)
  ├── 1. SHA-256 hash → check for duplicate
  │    └── Duplicate? Clone record & return (skip processing)
  ├── 2. Is image? → ImageProcessorService pipeline
  │    ├── Auto-rotate (EXIF orientation)
  │    ├── Convert to WebP (quality: 80)
  │    ├── Generate 3 thumbnails (150px, 300px, 600px)
  │    ├── Generate blur placeholder (20px, base64 data URI)
  │    ├── Extract EXIF metadata (GPS, camera, date)
  │    └── Optional: AI background removal
  ├── 3. Upload to S3/R2 via StorageProvider
  ├── 4. Rewrite URLs through CdnService
  └── 5. Save MediaFile to MongoDB (status: COMPLETE)

Presigned URL Flow (confirmUpload)

// 1. Frontend requests a presigned URL
const { uploadUrl, fileId } = await requestUploadUrl({
	filename: 'product-photo.jpg',
	mimetype: 'image/jpeg',
	maletId: 'malet-123'
});

// 2. Frontend uploads directly to S3
await fetch(uploadUrl, { method: 'PUT', body: file });

// 3. Frontend confirms the upload — triggers server-side processing
const mediaFile = await confirmUpload({
	fileId,
	removeBackground: true // optional AI enhancement
});

The confirmUpload mutation validates the file exists in S3, downloads it, runs the full image pipeline (WebP, thumbnails, blur, EXIF), and re-uploads the optimized versions.

Image Processing

All image processing uses the sharp library for high-performance, zero-copy operations.

Thumbnail Generation

Three sizes are generated in parallel for every image upload:

const DEFAULT_THUMBNAIL_SIZES = [
	{ label: 'small', maxDimension: 150 },
	{ label: 'medium', maxDimension: 300 },
	{ label: 'large', maxDimension: 600 }
];

Blur Placeholder (LQIP)

Every image generates a Low Quality Image Placeholder — a tiny 20px-wide WebP encoded as a base64 data URI. The frontend uses this for instant-loading skeleton shimmer effects while the full image loads.

// Stored on the MediaFile document as `blurDataUrl`
// "data:image/webp;base64,UklGRvQAAABXRUJQ..."

EXIF Extraction

The exifr library extracts embedded metadata before sharp strips it during optimization:

const exif = await this.imageProcessorService.extractExif(buffer);
// { Make: 'Canon', Model: 'EOS R5', GPSLatitude: -33.86, ... }

SHA-256 Deduplication

Every file upload computes a SHA-256 hash of the raw buffer. If an identical hash already exists within the same Malet, the system clones the metadata record instead of re-processing and re-uploading.

How It Works

const hash = createHash('sha256').update(file.buffer).digest('hex');
const existing = await this.mediaFileModel.findOne({
	hash,
	maletId,
	status: MediaStatus.COMPLETE
});

if (existing) {
	// Clone the record — same S3 key, same thumbnails, new document ID
	return this.mediaFileModel.create({ ...existing, id: nanoid() });
}

Reference-Counted Deletion

When deleting a file, the system checks how many MediaFile documents reference the same S3 key:

• Last reference (refCount <= 1) → Delete from S3 + all thumbnails
• Other references remain → Delete the MongoDB document only, S3 objects stay

This prevents orphaned S3 objects while ensuring deduplication doesn't cause data loss.

Storage Abstraction

The media service uses a provider pattern for storage abstraction, supporting both platform defaults and custom Malet storage.

Provider Interface

interface StorageProvider {
	upload(file: Express.Multer.File, key: string): Promise<string>;
	delete(key: string): Promise<void>;
	exists(key: string): Promise<boolean>;
	download(key: string): Promise<Buffer>;
}

Provider Resolution

upload(file, maletId?)
  ├── No maletId → System S3 provider (default bucket)
  └── maletId provided
       ├── Malet has custom storage config → DynamicStorageFactory
       └── No custom config → System S3 provider (fallback)

R2 CORS Initialization

On service startup, the media service automatically configures CORS on the S3/R2 bucket:

// Runs on NestJS module init
await s3.send(
	new PutBucketCorsCommand({
		Bucket: 'ngwenya-media',
		CORSConfiguration: {
			CORSRules: [
				{
					AllowedOrigins: [process.env.FRONTEND_URL],
					AllowedMethods: ['GET', 'PUT'],
					AllowedHeaders: ['*'],
					MaxAgeSeconds: 3600
				}
			]
		}
	})
);

This ensures presigned URL uploads from the browser are never blocked by CORS, even after bucket recreation or environment changes.

CDN URL Rewriting

The CdnService transparently rewrites storage URLs (MinIO, S3, R2) to CDN URLs (Cloudflare) when enabled.

Configuration

CDN_ENABLED=true
CDN_BASE_URL=https://cdn.mallnline.com
CDN_ORIGIN_PATTERNS=localhost:9000,s3.us-east-1.amazonaws.com

When CDN_ENABLED=false (default in development), all URLs pass through unchanged.

Video Transcoding

The apps/video service is a dedicated microservice (TCP:30021) that handles FFmpeg-based video processing. It mirrors the apps/imaging architecture — intentionally decoupled from apps/media to keep the media service lightweight.

HLS Transcoding

Source video (MP4/MOV) → FFmpeg → HLS segments (.ts) + playlist (.m3u8) + poster (.jpg)

TCP Microservice Contract

// From apps/media — fire and forget
await this.videoTranscodeService.initiate(fileId, s3Key, maletId);

// apps/video receives via TCP MessagePattern
@MessagePattern('video.transcode')
async handleTranscode(payload: TranscodePayload): Promise<TranscodeResult>

Future: This NestJS implementation is a reference implementation. A Rust rewrite is planned for production scale, using ffmpeg-sys bindings for lower memory overhead. The TCP contract ensures the Rust binary is a drop-in replacement.

Environment Variables

Module Structure

apps/media/src/
├── media/
│   ├── media.service.ts              # Upload, dedup, confirm flow
│   ├── media.resolver.ts             # GraphQL mutations/queries
│   ├── media.controller.ts           # REST upload endpoint
│   ├── image-processor.service.ts    # sharp: WebP, thumbnails, blur, EXIF
│   ├── malet-config.service.ts       # Custom storage config resolution
│   ├── upload-cleanup.service.ts     # Orphan cleanup
│   ├── models/media-file.model.ts    # MediaFile entity
│   └── providers/
│       ├── storage-provider.interface.ts
│       ├── s3-storage.provider.ts
│       └── dynamic-storage.factory.ts
├── cdn/
│   └── cdn.service.ts                # URL rewriting
├── image-enhancement/                # AI background removal
├── gallery/                          # Gallery management
└── video-transcode/                  # TCP client to apps/video

apps/video/src/
└── video/
    ├── video.service.ts              # FFmpeg HLS transcoding
    └── video.controller.ts           # TCP message handler

Testing

Unit Tests

# Media service (includes image processor, CDN, dedup, gallery)
npm run test -- apps/media --no-coverage

# Video service
npm run test -- apps/video --no-coverage

E2E Tests

npx jest --config apps/media/test/jest-e2e.json --forceExit

Related

• Media Intelligence & Processing — EXIF extraction, SHA-256 deduplication, and video transcoding
• Media Analytics API — Upload volume, storage usage, and type distribution analytics
• Soft-Delete & Trash System — Data lifecycle management for catalog items that reference media