E-commerce Marketplace (e.g. Amazon)

App
├── PlatformShell
│   ├── Header
│   │   ├── SearchBar (autocomplete, recent searches)
│   │   ├── CartIcon (badge with item count)
│   │   └── AccountMenu
│   └── MobileNav
├── ProductListingPage
│   ├── BreadcrumbNav
│   ├── FilterSidebar
│   │   ├── FacetGroup (category, price range, brand, rating)
│   │   └── ActiveFilters
│   ├── SortControls
│   ├── ProductGrid
│   │   └── ProductCard (image, title, price, rating, add-to-cart)
│   └── Pagination / InfiniteScroll
├── ProductDetailPage
│   ├── ImageGallery (zoom, thumbnails, 360° view)
│   ├── ProductInfo
│   │   ├── VariantSelector (size/color matrix)
│   │   ├── PriceDisplay (sale price, discount %)
│   │   ├── InventoryStatus
│   │   └── AddToCartButton
│   ├── ProductTabs (description, specs, reviews)
│   └── RecommendationCarousel
├── CartDrawer (slide-over panel)
│   ├── CartItemList
│   │   └── CartItem (image, qty controls, remove, subtotal)
│   ├── CartSummary (subtotal, shipping estimate, tax)
│   └── CheckoutCTA
└── CheckoutFlow
    ├── ShippingStep (address form, saved addresses)
    ├── PaymentStep (hosted payment fields, saved cards)
    ├── ReviewStep (order summary, edit links)
    └── ConfirmationStep (order number, tracking)

interface Product {
  id: string;
  slug: string;
  title: string;
  description: string; // HTML-safe markdown
  brand: string;
  categoryPath: string[]; // ["Electronics", "Phones", "Android"]
  basePrice: Money;
  salePrice: Money | null;
  images: ProductImage[];
  variants: Variant[];
  attributes: Record<string, string>; // "material": "Cotton", "weight": "200g"
  rating: RatingAggregate;
  reviewCount: number;
  inventoryStatus: InventoryStatus;
  seoMeta: SEOMeta;
  createdAt: string; // ISO 8601
  updatedAt: string;
}

interface Variant {
  id: string;
  sku: string;
  attributes: VariantAttribute[]; // [{ name: "Size", value: "XL" }, { name: "Color", value: "Navy" }]
  price: Money;
  compareAtPrice: Money | null;
  inventory: number; // -1 = unlimited
  image: ProductImage | null; // variant-specific image override
  available: boolean;
}

interface VariantAttribute {
  name: string;
  value: string;
  swatch?: string; // hex color or image URL for visual selectors
}

interface Money {
  amount: number; // cents (integer) — never floating point
  currency: string; // ISO 4217: "USD", "EUR"
}

interface ProductImage {
  id: string;
  url: string; // base URL — append size params at runtime
  alt: string;
  width: number;
  height: number;
  position: number; // display order
}

interface CartItem {
  id: string; // cart-line ID (not product ID)
  productId: string;
  variantId: string;
  quantity: number;
  price: Money; // locked at add-time, revalidated at checkout
  title: string; // denormalized for offline display
  image: string; // denormalized thumbnail URL
  variantLabel: string; // "Size: XL, Color: Navy"
  addedAt: string;
}

interface Cart {
  id: string;
  items: CartItem[];
  itemCount: number; // sum of quantities
  subtotal: Money;
  estimatedTax: Money | null;
  estimatedShipping: Money | null;
  discounts: Discount[];
  updatedAt: string;
  expiresAt: string; // carts expire after 30 days
}

interface Discount {
  code: string;
  type: "percentage" | "fixed" | "shipping";
  value: number;
  appliedAmount: Money;
}

interface Order {
  id: string;
  orderNumber: string; // human-readable "ORD-2024-XXXXX"
  status: OrderStatus;
  items: OrderItem[];
  shippingAddress: Address;
  billingAddress: Address;
  paymentMethod: PaymentMethodSummary;
  subtotal: Money;
  tax: Money;
  shipping: Money;
  total: Money;
  placedAt: string;
  estimatedDelivery: string;
}

type OrderStatus =
  | "pending"
  | "confirmed"
  | "processing"
  | "shipped"
  | "delivered"
  | "cancelled"
  | "refunded";

interface Review {
  id: string;
  productId: string;
  author: ReviewAuthor;
  rating: number; // 1-5
  title: string;
  body: string;
  images: string[];
  verifiedPurchase: boolean;
  helpfulCount: number;
  createdAt: string;
}

interface RatingAggregate {
  average: number; // 4.3
  count: number; // total reviews
  distribution: [number, number, number, number, number]; // [1★, 2★, 3★, 4★, 5★] counts
}

interface SearchResult {
  query: string;
  hits: ProductHit[];
  facets: Facet[];
  totalHits: number;
  processingTimeMs: number;
  page: number;
  totalPages: number;
}

interface ProductHit {
  product: Product;
  highlights: Record<string, string>; // field → highlighted HTML snippet
  score: number;
}

interface Facet {
  field: string; // "brand", "price", "rating", "category"
  type: "list" | "range" | "rating";
  values: FacetValue[];
}

interface FacetValue {
  value: string;
  label: string;
  count: number;
  selected: boolean;
}

interface SEOMeta {
  title: string;
  description: string;
  canonical: string;
  structuredData: object; // JSON-LD Product schema
}

type InventoryStatus = "in_stock" | "low_stock" | "out_of_stock" | "preorder";

// GET /api/products?category=phones&brand=Apple,Samsung&price=100-500&sort=price_asc&page=1&limit=24
interface ProductListingRequest {
  category?: string;
  brand?: string[];
  priceMin?: number;
  priceMax?: number;
  rating?: number; // minimum rating filter
  sort:
    | "relevance"
    | "price_asc"
    | "price_desc"
    | "newest"
    | "rating"
    | "bestselling";
  page: number;
  limit: number; // 24 | 48 | 96
}

interface ProductListingResponse {
  products: Product[];
  facets: Facet[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
    hasNext: boolean;
  };
  appliedFilters: Record<string, string[]>;
  breadcrumbs: Breadcrumb[];
}

// GET /api/search?q=wireless+headphones&facets=brand,price_range&page=1
interface SearchRequest {
  query: string;
  facets?: string[];
  filters?: Record<string, string[]>;
  page?: number;
  hitsPerPage?: number;
  sortBy?: string;
}

interface SearchResponse {
  hits: ProductHit[];
  facets: Facet[];
  query: string;
  totalHits: number;
  processingTimeMs: number;
  suggestions: string[]; // "Did you mean..." alternatives
  pagination: PaginationMeta;
}

// GET /api/search/autocomplete?q=wire
interface AutocompleteResponse {
  suggestions: AutocompleteSuggestion[];
  products: ProductHit[]; // top 3-5 instant results
  categories: CategorySuggestion[];
}

interface AutocompleteSuggestion {
  text: string;
  highlighted: string; // "<mark>wire</mark>less headphones"
  category?: string;
}

// POST /api/cart/items
interface AddToCartRequest {
  productId: string;
  variantId: string;
  quantity: number;
}

// PATCH /api/cart/items/:lineId
interface UpdateCartItemRequest {
  quantity: number;
}

// DELETE /api/cart/items/:lineId

// GET /api/cart
interface CartResponse {
  cart: Cart;
  warnings: CartWarning[]; // price changes, stock issues
}

interface CartWarning {
  lineId: string;
  type: "price_changed" | "low_stock" | "out_of_stock" | "quantity_adjusted";
  message: string;
  previousValue?: string;
  currentValue?: string;
}

// POST /api/checkout/shipping
interface SetShippingRequest {
  address: Address;
  shippingMethod: string; // "standard" | "express" | "overnight"
}

interface SetShippingResponse {
  shippingOptions: ShippingOption[];
  estimatedTax: Money;
  orderSummary: OrderSummary;
}

// POST /api/checkout/payment-intent
interface CreatePaymentIntentResponse {
  clientSecret: string; // Stripe PaymentIntent client secret
  publishableKey: string;
}

// POST /api/checkout/confirm
interface ConfirmOrderRequest {
  paymentIntentId: string;
  shippingAddressId: string;
  billingAddressId: string;
  shippingMethod: string;
}

interface ConfirmOrderResponse {
  order: Order;
  redirectUrl: string; // confirmation page URL
}

// POST /api/inventory/check
interface InventoryCheckRequest {
  items: Array<{ variantId: string; quantity: number }>;
}

interface InventoryCheckResponse {
  available: boolean;
  items: Array<{
    variantId: string;
    requested: number;
    available: number;
    status: InventoryStatus;
  }>;
}

┌─────────────────────────────────────────────────────────────┐
│                     CACHING LAYERS                            │
├─────────────┬───────────────┬───────────────┬───────────────┤
│   Browser   │  Service      │   CDN Edge    │   Origin      │
│   Cache     │  Worker       │   (Vercel)    │   Cache       │
├─────────────┼───────────────┼───────────────┼───────────────┤
│ React Query │ Offline cart  │ ISR pages     │ Redis         │
│ in-memory   │ fallback      │ (60s stale)   │ (product DB)  │
│             │               │               │               │
│ localStorage│ Static assets │ Image CDN     │ Search index  │
│ (cart)      │ (immutable)   │ (1yr cache)   │ (Algolia)     │
└─────────────┴───────────────┴───────────────┴───────────────┘

// Cart persistence strategy: cookie (SSR) + localStorage (detail) + server (source of truth)

const CART_COOKIE_KEY = "cart_id";
const CART_LOCAL_KEY = "cart_items";

// On add-to-cart:
// 1. Optimistic update to Zustand store
// 2. Persist to localStorage (full cart for offline)
// 3. Sync cookie with cart ID (for SSR cart badge)
// 4. POST to server (source of truth)
// 5. BroadcastChannel notify other tabs

const cartChannel = new BroadcastChannel("cart_sync");

function syncCartAcrossTabs(cart: Cart): void {
  cartChannel.postMessage({ type: "CART_UPDATED", cart });
}

cartChannel.onmessage = (event) => {
  if (event.data.type === "CART_UPDATED") {
    useCartStore.getState().setCart(event.data.cart);
  }
};

function getProductImageUrl(baseUrl: string, options: ImageOptions): string {
  const params = new URLSearchParams();
  params.set('w', String(options.width));
  params.set('q', String(options.quality ?? 80));
  params.set('fm', options.format ?? 'auto');  // auto-negotiates AVIF/WebP
  if (options.fit) params.set('fit', options.fit);
  return `${baseUrl}?${params.toString()}`;
}

// Usage in ProductCard
<img
  src={getProductImageUrl(product.images[0].url, { width: 400, quality: 80 })}
  srcSet={`
    ${getProductImageUrl(product.images[0].url, { width: 200 })} 200w,
    ${getProductImageUrl(product.images[0].url, { width: 400 })} 400w,
    ${getProductImageUrl(product.images[0].url, { width: 800 })} 800w
  `}
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 25vw"
  alt={product.images[0].alt}
  loading="lazy"
  decoding="async"
/>

// app/products/[slug]/page.tsx
export const revalidate = 60; // fallback: revalidate every 60s

export async function generateStaticParams() {
  // Pre-render top 10,000 products (by traffic)
  const topProducts = await getTopProductSlugs(10_000);
  return topProducts.map((slug) => ({ slug }));
}

// On-demand revalidation webhook:
// POST /api/revalidate?path=/products/[slug]&secret=xxx
export async function POST(request: Request) {
  const { path, secret } = await request.json();
  if (secret !== process.env.REVALIDATION_SECRET) {
    return new Response("Unauthorized", { status: 401 });
  }
  revalidatePath(path);
  return new Response("OK");
}

// Product detail page with streaming
import { Suspense } from 'react';

export default async function ProductPage({ params }: { params: { slug: string } }) {
  const product = await getProduct(params.slug); // fast: cached in Redis

  return (
    <>
      {/* Immediate flush: SEO-critical content */}
      <ProductSEOHead product={product} />
      <ProductImageGallery images={product.images} />
      <ProductTitle title={product.title} brand={product.brand} />

      {/* Streamed: dynamic content */}
      <Suspense fallback={<PriceSkeleton />}>
        <ProductPrice productId={product.id} />
      </Suspense>

      <Suspense fallback={<InventorySkeleton />}>
        <InventoryStatus variantId={product.variants[0].id} />
      </Suspense>

      <Suspense fallback={<ReviewsSkeleton />}>
        <ProductReviews productId={product.id} />
      </Suspense>

      <Suspense fallback={<RecommendationsSkeleton />}>
        <PersonalizedRecommendations productId={product.id} />
      </Suspense>
    </>
  );
}

// ProductGrid skeleton — matches exact layout dimensions to prevent CLS
function ProductGridSkeleton({ count = 24 }: { count?: number }) {
  return (
    <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
      {Array.from({ length: count }, (_, i) => (
        <div key={i} className="animate-pulse">
          <div className="aspect-square bg-muted rounded-lg" />
          <div className="mt-2 h-4 bg-muted rounded w-3/4" />
          <div className="mt-1 h-4 bg-muted rounded w-1/2" />
          <div className="mt-1 h-5 bg-muted rounded w-1/4" />
        </div>
      ))}
    </div>
  );
}

// Payment step — card data NEVER enters our DOM
// Uses Stripe Elements (hosted iframes)

'use client';

import { Elements, CardElement, useStripe, useElements } from '@stripe/react-stripe-js';
import { loadStripe } from '@stripe/stripe-js';

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PK!);

function PaymentForm({ clientSecret }: { clientSecret: string }) {
  const stripe = useStripe();
  const elements = useElements();

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!stripe || !elements) return;

    const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
      payment_method: { card: elements.getElement(CardElement)! },
    });

    if (error) {
      // Display error.message to user
    } else if (paymentIntent?.status === 'succeeded') {
      // Redirect to confirmation
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <CardElement options={{ style: { base: { fontSize: '16px' } } }} />
      <button type="submit" disabled={!stripe}>Pay Now</button>
    </form>
  );
}

// Wrapper provides Stripe context
export function CheckoutPayment({ clientSecret }: { clientSecret: string }) {
  return (
    <Elements stripe={stripePromise} options={{ clientSecret }}>
      <PaymentForm clientSecret={clientSecret} />
    </Elements>
  );
}

// next.config.ts — CSP headers
const cspHeader = `
  default-src 'self';
  script-src 'self' 'unsafe-inline' https://js.stripe.com https://www.googletagmanager.com;
  frame-src https://js.stripe.com https://hooks.stripe.com;
  img-src 'self' https://images.cdn.example.com https://*.stripe.com data:;
  connect-src 'self' https://api.stripe.com https://*.algolia.net;
  style-src 'self' 'unsafe-inline';
  font-src 'self';
  object-src 'none';
  base-uri 'self';
  form-action 'self';
  frame-ancestors 'none';
`;

// Server-side: NEVER trust client-provided prices
async function validateCheckout(cart: Cart): Promise<ValidatedCart> {
  const serverPrices = await Promise.all(
    cart.items.map(async (item) => {
      const variant = await getVariant(item.variantId);
      return {
        lineId: item.id,
        clientPrice: item.price,
        serverPrice: variant.price,
        available: variant.inventory >= item.quantity,
        priceChanged: item.price.amount !== variant.price.amount,
      };
    }),
  );

  const warnings = serverPrices
    .filter((p) => p.priceChanged)
    .map((p) => ({
      lineId: p.lineId,
      type: "price_changed" as const,
      message: `Price updated from ${formatMoney(p.clientPrice)} to ${formatMoney(p.serverPrice)}`,
    }));

  const unavailable = serverPrices.filter((p) => !p.available);

  if (unavailable.length > 0) {
    throw new CheckoutError("ITEMS_UNAVAILABLE", { items: unavailable });
  }

  return { items: serverPrices, warnings, total: computeTotal(serverPrices) };
}

Normal traffic:  10,000 RPM on a product page
Flash sale:     100,000+ RPM on a single product page

┌──────────────────────────────────────────────────────────┐
│                 FLASH SALE ARCHITECTURE                    │
│                                                          │
│  ┌──────────┐     ┌──────────┐     ┌──────────────────┐ │
│  │  Static  │     │ Dynamic  │     │  Real-time       │ │
│  │  Shell   │ +   │ Overlay  │ +   │  Inventory       │ │
│  │  (CDN)   │     │  (Edge)  │     │  (WebSocket)     │ │
│  └──────────┘     └──────────┘     └──────────────────┘ │
│                                                          │
│  Product page is ISR-cached at CDN (static shell).       │
│  Price/inventory injected via edge middleware.           │
│  Real-time stock count pushed via WebSocket.             │
└──────────────────────────────────────────────────────────┘

// Optimistic UI with server validation
async function addToCart(
  productId: string,
  variantId: string,
  quantity: number,
) {
  // 1. Optimistic update — show item in cart immediately
  const optimisticItem = createOptimisticCartItem(
    productId,
    variantId,
    quantity,
  );
  useCartStore.getState().addItemOptimistic(optimisticItem);

  try {
    // 2. Server request — validates inventory
    const response = await fetch("/api/cart/items", {
      method: "POST",
      body: JSON.stringify({ productId, variantId, quantity }),
    });

    if (!response.ok) {
      const error = await response.json();
      if (error.code === "INSUFFICIENT_INVENTORY") {
        // 3a. Rollback optimistic update, show available quantity
        useCartStore.getState().rollbackItem(optimisticItem.id);
        toast.error(`Only ${error.available} available`);
        return;
      }
      throw new Error(error.message);
    }

    // 3b. Replace optimistic item with server-confirmed item
    const confirmedItem = await response.json();
    useCartStore.getState().confirmItem(optimisticItem.id, confirmedItem);
  } catch (error) {
    // 4. Network failure — keep optimistic item, retry on reconnect
    useCartStore.getState().markItemPending(optimisticItem.id);
    queueRetry(() => addToCart(productId, variantId, quantity));
  }
}

// Multi-step checkout with sessionStorage persistence
'use client';

import { useForm } from 'react-hook-form';
import { useEffect } from 'react';

const STORAGE_KEY = 'checkout_shipping_form';

export function ShippingForm({ onNext }: { onNext: (data: ShippingData) => void }) {
  const form = useForm<ShippingData>({
    defaultValues: loadFromStorage(STORAGE_KEY) ?? {
      firstName: '',
      lastName: '',
      address1: '',
      address2: '',
      city: '',
      state: '',
      zip: '',
      country: 'US',
    },
  });

  // Persist form state on every change (debounced)
  useEffect(() => {
    const subscription = form.watch((values) => {
      saveToStorage(STORAGE_KEY, values);
    });
    return () => subscription.unsubscribe();
  }, [form]);

  // Handle submission with retry logic
  async function onSubmit(data: ShippingData) {
    try {
      const response = await submitShipping(data);
      clearStorage(STORAGE_KEY);
      onNext(response);
    } catch (error) {
      if (isNetworkError(error)) {
        toast.info('Saved locally. Will retry when connection resumes.');
        // Form data already persisted via watch — user can close and return
      } else {
        toast.error('Please check your address and try again.');
      }
    }
  }

  return <form onSubmit={form.handleSubmit(onSubmit)}>{/* ... fields ... */}</form>;
}

function loadFromStorage<T>(key: string): T | null {
  try {
    const stored = sessionStorage.getItem(key);
    return stored ? JSON.parse(stored) : null;
  } catch {
    return null;
  }
}

function saveToStorage(key: string, value: unknown): void {
  try {
    sessionStorage.setItem(key, JSON.stringify(value));
  } catch {
    // Storage full — silently fail, form still works
  }
}

function clearStorage(key: string): void {
  sessionStorage.removeItem(key);
}

// Edge middleware for A/B testing — no client-side flicker
// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  const response = NextResponse.next();

  // Assign experiment bucket if not already assigned
  if (!request.cookies.get("exp_checkout_v2")) {
    const bucket = Math.random() < 0.5 ? "control" : "variant";
    response.cookies.set("exp_checkout_v2", bucket, {
      httpOnly: true,
      sameSite: "lax",
      maxAge: 60 * 60 * 24 * 30, // 30 days
    });
  }

  return response;
}

// Keyboard-navigable product grid with roving tabindex
'use client';

import { useRef, useState } from 'react';

interface ProductGridProps {
  products: Product[];
  columns: number;
}

export function ProductGrid({ products, columns }: ProductGridProps) {
  const [focusIndex, setFocusIndex] = useState(0);
  const gridRef = useRef<HTMLDivElement>(null);

  function handleKeyDown(e: React.KeyboardEvent) {
    let newIndex = focusIndex;

    switch (e.key) {
      case 'ArrowRight':
        newIndex = Math.min(focusIndex + 1, products.length - 1);
        break;
      case 'ArrowLeft':
        newIndex = Math.max(focusIndex - 1, 0);
        break;
      case 'ArrowDown':
        newIndex = Math.min(focusIndex + columns, products.length - 1);
        break;
      case 'ArrowUp':
        newIndex = Math.max(focusIndex - columns, 0);
        break;
      default:
        return;
    }

    e.preventDefault();
    setFocusIndex(newIndex);
    const cards = gridRef.current?.querySelectorAll('[data-product-card]');
    (cards?.[newIndex] as HTMLElement)?.focus();
  }

  return (
    <div
      ref={gridRef}
      role="grid"
      aria-label="Product results"
      onKeyDown={handleKeyDown}
    >
      {products.map((product, i) => (
        <ProductCard
          key={product.id}
          product={product}
          tabIndex={i === focusIndex ? 0 : -1}
          data-product-card
        />
      ))}
    </div>
  );
}

// Cart badge announces changes to screen readers
function CartIcon({ itemCount }: { itemCount: number }) {
  return (
    <button aria-label={`Shopping cart, ${itemCount} items`}>
      <ShoppingCartIcon />
      <span className="sr-only" aria-live="polite" aria-atomic="true">
        {itemCount} items in cart
      </span>
      <span aria-hidden="true" className="badge">{itemCount}</span>
    </button>
  );
}

// After add-to-cart action
function announceCartUpdate(productTitle: string) {
  const announcement = document.getElementById('cart-announcement');
  if (announcement) {
    announcement.textContent = `${productTitle} added to cart`;
  }
}

// Hidden announcement region in layout
<div id="cart-announcement" role="status" aria-live="assertive" className="sr-only" />

// Accessible form validation pattern
function AddressField({
  name,
  label,
  error,
  required
}: FieldProps) {
  const id = `field-${name}`;
  const errorId = `${id}-error`;
  const descriptionId = `${id}-description`;

  return (
    <div>
      <label htmlFor={id}>
        {label}
        {required && <span aria-hidden="true" className="text-destructive"> *</span>}
      </label>
      <input
        id={id}
        name={name}
        aria-required={required}
        aria-invalid={!!error}
        aria-describedby={error ? errorId : descriptionId}
      />
      {error && (
        <p id={errorId} role="alert" className="text-destructive text-sm">
          {error}
        </p>
      )}
    </div>
  );
}

// Price display with proper semantics
function PriceDisplay({ price, compareAtPrice }: PriceProps) {
  const hasDiscount = compareAtPrice && compareAtPrice.amount > price.amount;
  const discountPercent = hasDiscount
    ? Math.round((1 - price.amount / compareAtPrice!.amount) * 100)
    : 0;

  return (
    <div aria-label={
      hasDiscount
        ? `Sale price: ${formatMoney(price)}, was ${formatMoney(compareAtPrice!)}, ${discountPercent}% off`
        : `Price: ${formatMoney(price)}`
    }>
      <span aria-hidden="true" className="text-2xl font-bold">
        {formatMoney(price)}
      </span>
      {hasDiscount && (
        <>
          <span aria-hidden="true" className="line-through text-muted-foreground ml-2">
            {formatMoney(compareAtPrice!)}
          </span>
          <span aria-hidden="true" className="text-destructive ml-2">
            -{discountPercent}%
          </span>
        </>
      )}
    </div>
  );
}

// Analytics event tracking for checkout funnel
const CHECKOUT_EVENTS = {
  CART_VIEW: "checkout_funnel.cart_viewed",
  CHECKOUT_START: "checkout_funnel.started",
  SHIPPING_COMPLETE: "checkout_funnel.shipping_complete",
  PAYMENT_COMPLETE: "checkout_funnel.payment_complete",
  ORDER_CONFIRMED: "checkout_funnel.order_confirmed",
  CHECKOUT_ERROR: "checkout_funnel.error",
} as const;

function trackCheckoutStep(
  event: keyof typeof CHECKOUT_EVENTS,
  metadata: Record<string, unknown>,
) {
  analytics.track(CHECKOUT_EVENTS[event], {
    ...metadata,
    timestamp: Date.now(),
    sessionId: getSessionId(),
    cartValue: useCartStore.getState().cart?.subtotal.amount,
    itemCount: useCartStore.getState().cart?.itemCount,
  });
}

// Structured error reporting for checkout diagnostics
interface CheckoutError {
  step: "shipping" | "payment" | "confirmation";
  code: string;
  message: string;
  userId?: string;
  cartId: string;
  metadata: Record<string, unknown>;
}

function reportCheckoutError(error: CheckoutError) {
  // Sentry/DataDog structured error
  captureException(new Error(error.message), {
    tags: {
      checkout_step: error.step,
      error_code: error.code,
    },
    extra: {
      cartId: error.cartId,
      metadata: error.metadata,
    },
    level: error.step === "payment" ? "critical" : "error",
  });

  // Business metric
  analytics.track("checkout_error", {
    step: error.step,
    code: error.code,
    cartValue: error.metadata.cartValue,
  });
}

# Alert configurations
alerts:
  - name: LCP Regression
    condition: p75_lcp > 2500ms for 15 minutes
    severity: high
    channel: "#frontend-perf"
    runbook: "Check ISR cache hit rate, image CDN latency, server response time"

  - name: Checkout Conversion Drop
    condition: checkout_conversion_rate < 2% for 30 minutes
    severity: critical
    channel: "#revenue-alerts"
    runbook: "Check payment processor status, checkout error rates by step"

  - name: Cart Sync Failure Spike
    condition: cart_sync_error_rate > 2% for 5 minutes
    severity: high
    channel: "#frontend-eng"
    runbook: "Check cart service health, Redis connectivity, client error logs"

  - name: Flash Sale Load
    condition: product_page_rps > 50000
    severity: info
    channel: "#platform-ops"
    runbook: "Verify CDN cache hit rate > 99%, check inventory WebSocket connections"