# Pinterest — Frontend High-Level Design (HLD)

Framework: Next.js 15 App Router (React 19 Server + Client Components)
Structure: RADIO — Requirements · Architecture · Data model · Interface (API) · Optimizations & deep dive
Companion doc: FRONTEND_DESIGN.md — mini LLD with component trees, code samples, and implementation detail
System context: DESIGN.md — full-stack design
Domain glossary: CONTEXT.md

# Tech stack (apps/web)

Intentionally not used: global state library (Redux, Zustand), data-fetching framework (React Query, SWR), UI component library, CSS-in-JS. State is component-local; data fetching is native fetch (server) and XMLHttpRequest (S3 upload progress).

# Requirements

# Functional

# Non-functional

# Out of scope

• Auth implementation (boundaries documented only)
• Save-to-board UI and API
• Pin detail related pins / masonry
• Canvas-based pin editor (future extension — see CONTEXT.md)
• Video upload

# Constraints (locked)

• Search: Blocking SSR (5 pins) on initial load, CSR for viewport fill + infinite scroll (ADR-0001)
• Pin creation: CSR only — no SEO value, highly interactive
• Search indexing: eventual consistency via CDC — newly published pins appear in search after backend processing (not a frontend concern)
• Published is user-facing; internal processing status (Sharp variants) is never shown in the UI

# Architecture / High-Level Design

# Rendering strategy by route

# Core principle

Keep data fetching on the server; push interactivity to the client boundary.

Server Components own initial data loads (search results, pin detail). Client Components own browser APIs and user interaction (scroll, upload progress, suggestions debounce, masonry virtualization after hydration).

# Component layering

Search page
├── SearchPage [Server]           — fetches 5 above-fold pins; reads ?q= from URL; estimates container width from Client Hints / UA
├── SearchBar [Client]              — input, submit, URL sync
│   └── SuggestionsDropdown [Client]  — lazy-loaded; debounced fetch, keyboard nav
└── PinBrowser [Client]             — owns grid ↔ pin-detail view switch; preserves loaded pins across remounts
    ├── VirtualMasonryGrid [Client] — SSR initial 5 pins; client viewport fill + virtualization + infinite scroll
    │   └── PinCard [Client]        — next/image, click intercept via onPinClick
    └── PinDetailView [Client]      — shown when a pin is opened from the grid (client-fetched)

Pin creation
└── CreatePinPage [Server]          — thin wrapper
    └── PinCreateForm [Client]      — file pick/drop, XHR upload to S3, description, publish

Pin detail
└── PinDetailPage [Server]          — fetches pin on server
    └── PinDetailView [Client]      — hero image + description + back button + published banner

# Server vs client boundary

# Auth boundaries (annotated, not implemented)

# State ownership (no global store)

# Data Model

Frontend-facing shapes — source of truth remains Postgres / Elasticsearch on the backend (see DESIGN.md §2).

# Pin (search grid card)

type PinGridItem = {
  id: string;
  description: string;
  width: number;           // original px — masonry height calc
  height: number;
  dominant_color: string;  // hex, e.g. "#a3b4c5"
  images: {
    '236w': string;        // CDN URL
    '474w': string;
  };
};

# Pin (detail page)

type PinDetail = {
  id: string;
  description: string;
  dominant_color: string;
  images: {
    '736w'?: string;
    original: string;      // fallback until variants exist
  };
};

# Search results page

type SearchResults = {
  pins: PinGridItem[];
  next_cursor: string | null;
};

# Suggestions

type Suggestions = string[];   // completion terms from ES suggester

# Upload / publish

type UploadUrlResponse = {
  pin_id: string;
  upload_url: string;
  expires_in: number;        // seconds
};

type CreatePinResponse = {
  pin_id: string;
  status: 'processing';      // internal — UI treats as Published
};

# URL parameters

Cursor is not in the URL — opaque search_after token held in client useRef.

# Interface Design (API)

# Routes

# API surface (frontend consumer)

# User flows

Search

User types → GET /api/suggestions (debounced)
  → submit → /search?q=
  → SSR GET /api/search (5 pins, blocking)
  → client mount → GET /api/search (viewport fill)
  → scroll → GET /api/search?cursor=… → append pins
  → click pin → pushState /pin/:id → GET /api/pins/:id → PinDetailView overlay
  → browser back → popstate → grid remounts with saved pins + scroll position
  → right-click / open in new tab → full /pin/[id] page (SSR)

Create

Select file → POST /api/pins/upload-url → PUT S3 (XHR)
  → POST /api/pins → navigate /pin/[id]?published=1

# Optimizations & Deep Dive

# Search initial load (two-phase blocking SSR)

1. Server reads q from searchParams.
2. Server fetches GET /api/search with limit=5 only — response closes immediately (no Suspense boundary).
3. Server estimates container width from Sec-CH-Viewport-Width (Client Hints) or UA fallback.
4. Client hydrates PinBrowser → VirtualMasonryGrid with 5 pins in the DOM.
5. On mount, grid fetches the next batch to fill the viewport, then infinite scroll via IntersectionObserver.

# Masonry grid

• Layout: JS absolute positions from stored width / height; shortest-column placement; zero CLS.
• Placeholder: dominant_color slot behind next/image.
• Virtualization: @tanstack/react-virtual with a custom rangeExtractor that uses masonry slot positions (not sequential item heights).
• Scheduling: ResizeObserver debounced ~150 ms for container width; scroll handled by the virtualizer.
• SSR: First 5 pins in blocking HTML; virtualization activates after hydration when the virtualizer reports items.

# Image loading

# Image error handling

On onerror for a pin image:

1. Wait 2s and retry src once — catches transient mobile network drops and brief S3 hiccups silently.
2. If retry fails: keep the pre-calculated masonry slot, display dominant color background + subtle broken-image icon overlay.
3. Never collapse the slot — collapsing requires column recalculation and causes layout shift, violating CLS.

# Caching

Two layers, complementary:

• CDN — caches the SSR HTML of the first page of results for hot queries (e.g. q=keyboards). TTL-based invalidation. Handles thundering herd on trending terms.
• Redis — caches API-layer search results (JSON) for all cursor pages and suggestion requests. Cache key: q={query}&cursor={cursor}. 60s TTL — acceptable given CDC lag already introduces eventual consistency.

# Suggestions

200 ms debounce · AbortController per keystroke · lazy-loaded on first focus · listbox / keyboard nav (see Mini LLD §7).

# Pin creation UX

Published = upload + description submit succeed — navigate immediately. Internal processing / Sharp / CDC never surfaced. XHR (not fetch) for S3 upload progress.

# Bundle strategy

• App Router route splitting (automatic)
• VirtualMasonryGrid SSR-enabled for LCP
• SuggestionsDropdown dynamic import on focus
• /pin/create lazy route

# Core Web Vitals

# Observability

# Failure modes

# Accessibility

Masonry grid:

• Grid container: role="list"
• Each pin card: role="listitem", aria-label="{description}"
• Each <img>: alt="{description}"
• Infinite scroll trigger: aria-live="polite" region announcing when new pins load
• Keyboard navigation follows DOM (insertion) order — tab order is not overridden to match visual column order

Suggestions: listbox / option dropdown · aria-activedescendant for keyboard highlight · ↑/↓ navigate, Enter submits, Escape closes.

Pin creation form: standard label/input associations, no custom a11y needed.

# Decision log

For calcPositions, TypeScript samples, ARIA markup, and route file tree — see FRONTEND_DESIGN.md (Mini LLD).