# Pinterest — Frontend High-Level Design (HLD)

Framework: Next.js App Router (React Server Components + Suspense streaming)
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

# 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: Streaming SSR on initial load, CSR for 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 page-1 results; reads ?q= from URL
├── SearchBar [Client]              — input, submit, URL sync
│   └── SuggestionsDropdown [Client]  — debounced fetch, keyboard nav
└── VirtualMasonryGrid [Client]     — SSR initial pins; client virtualization + infinite scroll
    ├── PinCard [Client]            — image loading, error retry
    └── InfiniteScrollTrigger [Client]  — IntersectionObserver sentinel

Pin creation
└── PinCreationPage [Client]        — entire page
    ├── FileDropzone [Client]       — validate, presigned URL, XHR upload to S3
    ├── UploadProgress [Client]
    └── PinForm [Client]            — description, publish

Pin detail
└── PinDetailPage [Server]          — hero image + description + 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 (page 1)
  → scroll → GET /api/search?cursor=… → append pins

Create

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

# Optimizations & Deep Dive

# Streaming SSR (search initial load)

1. Server reads q from searchParams (always page 1).
2. Server fetches GET /api/search (Redis → ES).
3. HTML shell streams immediately; <Suspense> streams skeleton then populated grid.
4. Client hydrates with pin data in the DOM — no re-fetch on hydration.

# Masonry grid

• Layout: JS absolute positions from stored width / height; shortest-column placement; zero CLS.
• Placeholder: dominant_color slot; image crossfades on load.
• Virtualization: Viewport ± 1 overscan; off-screen height placeholders preserve scroll.
• Scheduling: rAF (scroll), rIC + debounced ResizeObserver ~150 ms (resize).
• SSR: Full first page (~50 pins) on server; virtualization after hydration.

# 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).