Skip to content
SiteSwarm Platform Documentation

Image And Media Management

Image & Media Management Capability

1. Executive Summary & Capability Purpose

Client web applications rely on high-resolution photography (products, facilities, portfolios, and menus), but serving raw multi-megabyte uploads directly to mobile visitors causes slow page loads and layout shifts.

The Image & Media Management Capability provides end-to-end storage, transformation, and responsive delivery for client media assets across three invariants:

  1. Zero-Egress Master Storage: Master media uploads are stored in Cloudflare R2 under content-addressed, immutable object keys with zero bandwidth egress fees.
  2. Edge Format & Size Transformation: Media requests route through the Cloudflare Images edge pipeline to automatically negotiate modern formats (AVIF and WebP) and generate responsive viewport widths (srcset) on demand.
  3. Zero-Layout-Shift Delivery (0.00 CLS): Rendered images reserve their intrinsic aspect ratio (width / height) before bytes arrive and load lazily by default (with at most one priority hero image above the fold).
flowchart LR
    Upload["Media Upload"] --> R2["Cloudflare R2 Master Storage\n(Immutable Content-Addressed Key)"]
    R2 --> Transform["Cloudflare Images Edge Pipeline\n(AVIF / WebP & Responsive Widths)"]
    Transform --> Browser["Visitor Browser\n(Intrinsic Aspect Ratio & Lazy Loading)"]

2. Storage & Transformation Mechanics

  1. Content-Addressed Object Keys & Immutable Caching:
    • Uploaded assets receive collision-free keys (uploads/<collection>/<hash-or-uuid>/<sanitized-filename>.<ext>) and are served with permanent HTTP cache headers (Cache-Control: public, max-age=31536000, immutable).
  2. Isolated Write Bindings:
    • R2 write bindings are attached to the backing service worker (app-hosted CMS or media worker, see MULTI_WORKER_PLATFORM_SERVICES.md), keeping heavy upload processing off the public frontend worker.
  3. Metadata Sanitization & Progressive Rendering:
    • Edge transformations strip camera EXIF/GPS metadata while preserving creator copyright where applicable, and pages rely on native browser progressive decoding and CSS aspect-ratio reservation rather than client-side JavaScript loading state machines.