Performance Optimization Strategy

This document details the high-performance architecture of Instant Ship™, aimed at achieving a perfect 100/100 Lighthouse score and sub-second Largest Contentful Paint (LCP).

1. Core Web Vitals Targets

Our architecture is optimized for the following North Star metrics:

LCP (Largest Contentful Paint): < 1.2s
CLS (Cumulative Layout Shift): < 0.1
INP (Interaction to Next Paint): < 200ms

2. Rendering & Asset Strategy

A. Critical Path Optimization

Font Preloading: Essential fonts (Inter) are preloaded in index.html using rel="preload". We use font-display: swap to ensure text is visible during the font swap period.
Zero-JS Initial Shell: The basic CSS and HTML structure are designed to render before the React bundle hydrates.

B. Image Strategy (The LazyImage Component)

Intersection Observer: Images are only fetched when they approach the viewport (200px margin).
Modern Formats: We recommend using WebP or AVIF. The LazyImage component handles smooth transitions to prevent "popping."
Aspect Ratio Boxes: We reserve vertical space for images using CSS aspect-ratio or container padding to eliminate CLS.

C. Hybrid Build Pipeline

Dev Mode: Uses native ESM and CDN scripts for instant HMR (Hot Module Replacement).
Prod Mode: Vite tree-shakes unused code, minifies CSS, and generates a compact bundle that removes all development-only dependencies.

3. Edge-First Infrastructure

A. Cloudflare Tiered Caching

Utilizing _headers, we instruct the Cloudflare Global Edge to cache static assets aggressively:


text
/assets/*
  Cache-Control: public, max-age=31536000, immutable

B. Smart Prefetching

The App.tsx router logic can be extended to prefetch route chunks when a user hovers over a navigation link, reducing perceived latency to near-zero.

4. Continuous Monitoring

Lighthouse CI: Integrated into GitHub Actions to prevent performance regression.
Real User Monitoring (RUM): Leverages Microsoft Clarity to observe how performance impacts actual user behavior.