Image Optimization

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/image-optimization/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Image Optimization automatically compresses and converts product images on upload to modern formats (WebP, AVIF) while preserving quality. Merchants upload 5MB photos from their phone; the system resizes to 3–4 standard dimensions (thumbnail, product detail, hero), compresses to <500KB per size, and stores WebP with JPEG fallback. This is core GPL functionality: infrastructure, no per-country obligation, no credential required.

The problem

Merchants upload 5MB photos from their phone camera; product pages load in 8 seconds instead of 2 seconds. Customers abandon carts due to slow checkout. Merchants can’t afford a CDN. Image optimization is infrastructure, not a luxury feature.

What it does

• Auto-compress on upload: detect JPEG/PNG, compress lossily to 80-85% quality, save <500KB
• Auto-resize on upload: create 3 variants (thumbnail 150×150, detail 500×500, hero 1200×1200)
• Modern format conversion: encode as WebP (90% smaller than JPEG), store JPEG fallback
• Metadata stripping: remove EXIF (location, camera model, timestamps)
• Dimension validation: warn if image too small for hero variant (< 400×400 rejected)
• Batch processing: if merchant uploads 100 images, process in parallel, show progress
• Storage efficiency: single source image → one WebP + one JPEG per variant (6 files), deduplicate if content identical
• Admin preview: show before/after comparison (original 5MB vs optimized 200KB)
• Storefront API: return correct variant based on container width (responsive image srcset)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• AI-powered smart cropping (crop to focus on product) — scope is resize only; smart crop is separate feature
• Watermark or branding overlay — scope is optimization; branding is storefront responsibility
• HEIC or raw format support — scope is JPEG/PNG/WebP/AVIF only; merchants must convert other formats offline

Data model

Modify asset storage: store metadata (original_size, optimized_size, format, variants[]). No schema migration if using new asset format.

API

• POST /api/assets/upload — upload image, auto-compress and create variants
• GET /api/assets/:id/info — fetch image variants and metadata (size before/after)
• GET /api/assets/:id/:variant — fetch specific variant (thumbnail, detail, hero)
• GET /api/assets/:id/srcset — return HTML srcset for responsive image

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Asset upload form shows progress: ‘Compressing… 100% done. Original 5.2MB → Optimized 280KB’. Preview pane shows thumbnail, detail, hero variants side-by-side. Dashboard metric: ‘Total image storage: 15 GB optimized (was 120 GB unoptimized, 87% reduction)’.

The seam — why this is core

Core owns: all image optimization logic (compression, resizing, format conversion, variant storage, srcset generation). No seam; this is purely core infrastructure.

Core owns the interface + honest compression/resizing; image optimization is infrastructure, not a per-country obligation or support commitment.

Dependencies

• core-asset-store (storage backend)
• image-lazy-loading (storefront uses optimized variants with lazy load)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• 5MB JPEG uploaded, auto-resized to 3 variants; largest variant <500KB
• WebP variant size 60% smaller than JPEG fallback; both stored and served
• EXIF metadata (GPS, camera model) removed from uploaded image
• Batch upload 100 images: all processed in parallel, progress bar shows 100/100 complete
• Storefront requests hero variant (1200×1200) via srcset; server returns WebP if browser supports, else JPEG
• Admin dashboard shows ‘1.2TB storage optimized; 87% reduction from original uploads’

Risks

JPEG quality too aggressive (70%) looks pixelated on hero images; must test threshold. WebP fallback missing causes display failure in older browsers; must validate fallback. Batch processing memory leak on 10,000 images; must use streaming/chunking. Dimension validation rejects legitimate vertical photos (portrait products); logic must allow aspect ratio variance.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.