Search Engine Results Page (e.g. Google Search)

Daily searches:           8.5 billion
Peak QPS:                 ~150,000
Avg results per query:    10 (page 1) + suggestions + knowledge panel
Avg response payload:     45KB (compressed JSON)
Suggestion requests/search: 4-6 (per keystroke after debounce)
Peak suggestion QPS:      ~700,000
Image results per grid:   20-40 thumbnails (lazy loaded)

Client constraints:
- Mobile: 60% of traffic, 3G+ networks
- Average device: mid-range Android (4GB RAM, Snapdragon 600-series)
- Target JS parse budget: <100ms on mid-range mobile
- Image budget per page: <500KB total (lazy loaded)

CDN edge nodes:          200+ global PoPs
Cache hit rate target:   85% for suggestions, 40% for results

URL Schema:
/search?q={query}&tbm={type}&p={page}&tbs={time_filter}&safe={0|1}&hl={lang}

Examples:
/search?q=react+fiber+architecture
/search?q=cats&tbm=isch&safe=1
/search?q=latest+news&tbm=nws&tbs=qdr:h
/search?q=restaurants&tbm=lcl&near=sf

SearchPage
├── SearchHeader
│   ├── Logo
│   ├── SearchInput
│   │   ├── InputField (controlled)
│   │   ├── VoiceSearchButton
│   │   ├── CameraSearchButton
│   │   └── SuggestionDropdown
│   │       ├── SuggestionItem (keyboard navigable)
│   │       ├── RecentSearchItem
│   │       └── TrendingSearchItem
│   └── UserMenu
├── SearchFilters
│   ├── TypeTabs (All | Images | News | Videos | Maps | Shopping)
│   ├── TimeFilter
│   └── RegionFilter
├── ResultsContainer (streaming boundary)
│   ├── FeaturedSnippet
│   ├── WebResultCard
│   │   ├── ResultTitle (with query highlighting)
│   │   ├── ResultURL (breadcrumb format)
│   │   ├── ResultSnippet (with bold matches)
│   │   └── SiteLinks (2x3 grid when available)
│   ├── ImageCarousel (horizontal scroll)
│   ├── VideoResultCard (thumbnail + duration)
│   ├── NewsResultCard (publisher + timestamp)
│   ├── PeopleAlsoAsk (accordion)
│   │   └── PAQItem (expandable, lazy-loads answer)
│   ├── MapResultCard (embedded mini-map)
│   └── ShoppingResultCard (price + rating + image)
├── KnowledgePanel (right sidebar on desktop)
│   ├── EntityHeader (image + title + description)
│   ├── FactsTable
│   ├── RelatedEntities (carousel)
│   └── SocialLinks
├── Pagination
│   ├── PageNumbers
│   └── NextButton
└── SearchFooter
    ├── RelatedSearches
    └── LocationInfo

// URL is the single source of truth
interface SearchState {
  query: string; // ?q=
  type: SearchType; // ?tbm=
  page: number; // ?p=
  timeRange: TimeRange; // ?tbs=
  safeSearch: boolean; // ?safe=
  language: string; // ?hl=
}

// Client-only ephemeral state (not URL-persisted)
interface EphemeralState {
  suggestionQuery: string; // Current typeahead input
  suggestions: Suggestion[]; // Dropdown items
  selectedSuggestionIndex: number; // Keyboard nav position
  isVoiceActive: boolean; // Microphone recording
  expandedPAQ: Set<string>; // Expanded accordion items
}

// Core search types
type SearchType = "web" | "images" | "news" | "videos" | "maps" | "shopping";
type TimeRange = "any" | "hour" | "day" | "week" | "month" | "year" | "custom";
type SafeSearch = "off" | "moderate" | "strict";

// Suggestion types
interface Suggestion {
  id: string;
  text: string;
  type: "query" | "calculator" | "entity" | "navigation";
  icon?: string;
  entityImage?: string; // For entity suggestions (people, places)
  estimatedResults?: number;
}

interface RecentSearch {
  query: string;
  timestamp: number;
  type: SearchType;
}

// Federated result union
type SearchResult =
  | WebResult
  | ImageResult
  | NewsResult
  | VideoResult
  | MapResult
  | ShoppingResult
  | FeaturedSnippetResult
  | PeopleAlsoAskResult
  | KnowledgePanelResult;

// Web result (organic link)
interface WebResult {
  kind: "web";
  id: string;
  position: number;
  title: string; // With <em> tags for query match
  url: string;
  displayUrl: string; // Breadcrumb format: example.com › path › page
  snippet: string; // With <em> tags for query match highlighting
  datePublished?: string;
  siteLinks?: SiteLink[]; // Up to 6 sub-links
  favicon: string;
  schema?: StructuredData; // Recipe, FAQ, HowTo, etc.
  trackingId: string; // For CTR measurement
}

interface SiteLink {
  title: string;
  url: string;
  snippet?: string;
}

// Image result
interface ImageResult {
  kind: "image";
  id: string;
  thumbnailUrl: string;
  fullUrl: string;
  width: number;
  height: number;
  alt: string;
  sourceUrl: string;
  sourceDomain: string;
  title: string;
  aspectRatio: number; // For masonry layout calculation
}

// News result
interface NewsResult {
  kind: "news";
  id: string;
  title: string;
  url: string;
  source: string;
  sourceIcon: string;
  publishedAt: string; // ISO 8601
  thumbnailUrl?: string;
  snippet: string;
  isTopStory: boolean;
}

// Video result
interface VideoResult {
  kind: "video";
  id: string;
  title: string;
  url: string;
  thumbnailUrl: string;
  duration: number; // Seconds
  channel: string;
  publishedAt: string;
  views: number;
  platform: "youtube" | "vimeo" | "other";
}

// Map/Local result
interface MapResult {
  kind: "map";
  id: string;
  name: string;
  address: string;
  rating: number; // 1-5
  reviewCount: number;
  category: string;
  hours: string;
  distance?: string;
  lat: number;
  lng: number;
  photoUrl?: string;
}

// Shopping result
interface ShoppingResult {
  kind: "shopping";
  id: string;
  title: string;
  price: number;
  currency: string;
  merchant: string;
  imageUrl: string;
  rating?: number;
  reviewCount?: number;
  url: string;
  freeShipping: boolean;
}

// Featured snippet (position zero)
interface FeaturedSnippetResult {
  kind: "featured_snippet";
  id: string;
  type: "paragraph" | "list" | "table";
  content: string; // HTML content
  sourceTitle: string;
  sourceUrl: string;
  sourceDisplayUrl: string;
}

// People Also Ask
interface PeopleAlsoAskResult {
  kind: "people_also_ask";
  id: string;
  questions: PAQQuestion[];
}

interface PAQQuestion {
  id: string;
  question: string;
  answer?: string; // Lazy loaded on expand
  sourceUrl?: string;
  sourceTitle?: string;
}

// Knowledge panel
interface KnowledgePanelResult {
  kind: "knowledge_panel";
  id: string;
  title: string;
  subtitle: string;
  description: string;
  imageUrl: string;
  facts: Record<string, string>; // Key-value pairs
  socialLinks: { platform: string; url: string }[];
  relatedEntities: { name: string; imageUrl: string; url: string }[];
}

// Full search response (streamed)
interface SearchResponse {
  query: string;
  totalResults: number;
  correctedQuery?: string; // "Did you mean..."
  results: SearchResult[];
  knowledgePanel?: KnowledgePanelResult;
  relatedSearches: string[];
  filters: AvailableFilter[];
  timing: {
    totalMs: number;
    serviceTimings: Record<string, number>;
  };
}

// Click tracking
interface ClickEvent {
  queryId: string;
  resultId: string;
  position: number;
  resultType: SearchResult["kind"];
  timestamp: number;
  dwellTimeMs?: number; // Time before user returns to SERP
}

// GET /api/search?q=react+hooks&tbm=web&p=1&tbs=qdr:w&safe=1&hl=en
// Response: Streamed JSON (NDJSON) for progressive rendering

interface SearchRequest {
  q: string;
  tbm?: SearchType;
  p?: number; // Page (1-indexed)
  tbs?: string; // Time filter
  safe?: "0" | "1";
  hl?: string; // Language
  num?: number; // Results per page (default 10)
}

// Response streams as newline-delimited JSON:
// {"type":"meta","totalResults":1230000,"correctedQuery":null,"timing":{"totalMs":180}}
// {"type":"featured_snippet","data":{...}}
// {"type":"web","data":{...}}
// {"type":"web","data":{...}}
// {"type":"people_also_ask","data":{...}}
// {"type":"web","data":{...}}
// {"type":"related_searches","data":["react hooks tutorial","react hooks vs classes"]}
// {"type":"knowledge_panel","data":{...}}
// {"type":"done"}

// GET /api/suggest?q=react+ho&type=web&hl=en
// Response: JSON (not streamed — must be <50ms)

interface SuggestionRequest {
  q: string; // Partial query
  type?: SearchType;
  hl?: string;
}

interface SuggestionResponse {
  suggestions: Suggestion[];
  recentSearches: RecentSearch[]; // Only if user is authenticated
}

// POST /api/track/click (beacon API — fire and forget)
interface ClickTrackRequest {
  queryId: string;
  resultId: string;
  position: number;
  resultType: string;
  action: "click" | "return" | "long_click";
  dwellTimeMs?: number;
}

// GET /api/paq/expand?questionId=abc123&query=react+hooks
interface PAQExpandResponse {
  answer: string; // HTML content
  sourceUrl: string;
  sourceTitle: string;
  relatedQuestions: PAQQuestion[]; // Load more questions on expand
}

// Suggestion cache — LRU with prefix matching
class SuggestionCache {
  private cache = new Map<string, { data: Suggestion[]; ts: number }>();
  private maxSize = 200;
  private ttlMs = 5 * 60 * 1000; // 5 minutes

  get(prefix: string): Suggestion[] | null {
    const entry = this.cache.get(prefix);
    if (!entry || Date.now() - entry.ts > this.ttlMs) return null;
    return entry.data;
  }

  // Also check if a longer cached prefix contains valid results
  getFromLongerPrefix(prefix: string): Suggestion[] | null {
    for (const [key, entry] of this.cache) {
      if (key.startsWith(prefix) && Date.now() - entry.ts < this.ttlMs) {
        return entry.data.filter((s) =>
          s.text.toLowerCase().startsWith(prefix.toLowerCase()),
        );
      }
    }
    return null;
  }
}

// Search result cache — sessionStorage for back/forward
const RESULT_CACHE_KEY = "serp_cache";

function cacheSearchResults(url: string, html: string): void {
  try {
    const cache = JSON.parse(sessionStorage.getItem(RESULT_CACHE_KEY) || "{}");
    cache[url] = { html, ts: Date.now() };
    // Evict oldest if >20 entries
    const keys = Object.keys(cache);
    if (keys.length > 20) {
      const oldest = keys.sort((a, b) => cache[a].ts - cache[b].ts)[0];
      delete cache[oldest];
    }
    sessionStorage.setItem(RESULT_CACHE_KEY, JSON.stringify(cache));
  } catch {
    /* quota exceeded — silent fail */
  }
}

Suggestion cache invalidation:
├── Trending queries → TTL 5 min (new trends appear fast)
├── Entity suggestions → TTL 1 hour (stable)
├── Calculator/unit results → TTL 24 hours (immutable)
└── Personalized suggestions → No CDN cache, client LRU only

Search results:
├── Never CDN-cached (personalization, freshness, legal)
├── bfcache (Back/Forward Cache) for instant back navigation
├── sessionStorage snapshot for client-side back/forward
└── Service Worker: cache suggestion API + static assets only

Timeline (target: first result visible in 400ms):

0ms    → Request sent
50ms   → Edge terminates TLS, routes to nearest search node
80ms   → Server begins streaming HTML shell + critical CSS (inlined)
100ms  → Browser receives first chunk: <head> + search input HTML
150ms  → Critical JS loaded (search input hydration: 12KB)
180ms  → Search input is interactive (can type new query)
200ms  → First result card HTML streams in (chunked transfer)
250ms  → Result cards render (zero JS needed — pure HTML + CSS)
400ms  → All 10 results rendered, LCP fires on first result title
600ms  → Knowledge panel streams in (right rail)
800ms  → Non-critical JS loads (click tracking, PAA, voice search)
1000ms → Full page interactive (all features hydrated)

// Server: Stream results as NDJSON, rendered to HTML chunks
async function streamSearchResults(req: Request): Promise<Response> {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    async start(controller) {
      // 1. Send HTML shell immediately
      controller.enqueue(encoder.encode(renderShell(req.query)));

      // 2. Start federated search (parallel backend calls)
      const resultStream = searchOrchestrator.stream(req.query);

      // 3. Stream each result as an HTML chunk
      for await (const result of resultStream) {
        const html = renderResultCard(result);
        controller.enqueue(encoder.encode(html));
      }

      // 4. Send closing HTML + deferred scripts
      controller.enqueue(encoder.encode(renderFooter()));
      controller.close();
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/html; charset=utf-8",
      "Transfer-Encoding": "chunked",
    },
  });
}

/* Reserve exact space for each result card type */
.result-card--web {
  min-height: 116px;
  contain: layout style;
}
.result-card--video {
  min-height: 138px;
  contain: layout style;
}
.result-card--news {
  min-height: 96px;
  contain: layout style;
}
.result-card--image-carousel {
  height: 180px;
  contain: strict;
}
.knowledge-panel {
  width: 360px;
  min-height: 400px;
  contain: layout;
}

/* Skeleton exactly matches final layout */
.result-skeleton {
  height: 116px;
  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
}

Total JS budget: 80KB gzipped (initial load)

Chunk split strategy:
├── critical.js (12KB) — Search input, form submission, URL state
├── suggestions.js (8KB) — Typeahead dropdown, keyboard nav
├── tracking.js (3KB) — Click beacon, visibility observer
├── voice.js (6KB) — Web Speech API wrapper (loaded on mic click)
├── paq.js (4KB) — People Also Ask accordion expand
├── images.js (15KB) — Masonry layout, lightbox (route: /images)
├── maps.js (20KB) — Map embed, local results (route: /maps)
└── vendor.js (12KB) — Shared utilities (debounce, intersection observer polyfill)

Loading strategy:
- critical.js: inline in HTML (no network request)
- suggestions.js: preload, execute on first keydown
- tracking.js: defer, execute after DOMContentLoaded
- voice.js: dynamic import on microphone button click
- images.js/maps.js: route-based code splitting

// Server-side: sanitize indexed content before storage
function sanitizeSnippet(raw: string): string {
  // Allow only <em> for query highlighting
  const allowed = new Set(['em']);
  return raw.replace(/<\/?([a-z]+)[^>]*>/gi, (match, tag) => {
    return allowed.has(tag.toLowerCase()) ? match : '';
  });
}

// Client-side: never use innerHTML for user content
function HighlightedSnippet({ snippet }: { snippet: string }) {
  // snippet contains only <em> tags (server-sanitized)
  // Use a restricted parser, not dangerouslySetInnerHTML
  const parts = parseHighlightedText(snippet); // splits on <em> boundaries
  return (
    <p className="snippet">
      {parts.map((part, i) =>
        part.highlighted
          ? <em key={i} className="font-bold">{part.text}</em>
          : <span key={i}>{part.text}</span>
      )}
    </p>
  );
}

// Tracking redirect handler
function handleTrackingRedirect(req: Request): Response {
  const targetUrl = req.searchParams.get("url");
  const queryId = req.searchParams.get("qid");

  // 1. Validate URL format
  let parsed: URL;
  try {
    parsed = new URL(targetUrl);
  } catch {
    return new Response("Invalid URL", { status: 400 });
  }

  // 2. Block dangerous schemes
  const allowedSchemes = new Set(["http:", "https:"]);
  if (!allowedSchemes.has(parsed.protocol)) {
    return new Response("Blocked scheme", { status: 400 });
  }

  // 3. Block internal redirects (prevent SSRF via redirect)
  const blockedHosts = new Set(["localhost", "127.0.0.1", "0.0.0.0"]);
  if (
    blockedHosts.has(parsed.hostname) ||
    parsed.hostname.endsWith(".internal")
  ) {
    return new Response("Blocked host", { status: 400 });
  }

  // 4. Log click asynchronously
  trackClick(queryId, targetUrl).catch(() => {});

  // 5. Redirect with safe headers
  return new Response(null, {
    status: 302,
    headers: {
      Location: targetUrl,
      "Referrer-Policy": "origin",
      "X-Robots-Tag": "noindex",
    },
  });
}

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'nonce-{SERVER_NONCE}' https://cdn.search.com;
  style-src 'self' 'unsafe-inline';
  img-src 'self' https: data:;
  connect-src 'self' https://suggest.search.com https://track.search.com;
  frame-src 'self' https://maps.search.com;
  font-src 'self' https://fonts.gstatic.com;
  base-uri 'self';
  form-action 'self';
  frame-ancestors 'none';

Must work (no JS required):
├── Display search results (server-rendered HTML)
├── Pagination links
├── Filter tab links
└── Result link clicks

Should work (critical JS):
├── Search input with form submission
├── URL state management
└── Back/forward cache restoration

Nice to have (deferred JS):
├── Suggestion dropdown
├── Voice search
├── People Also Ask expand
├── Click tracking
├── Image masonry layout
└── Knowledge panel interactions

<main role="main" aria-label="Search results for 'react hooks'">
  <h1 class="sr-only">Search results for "react hooks"</h1>

  <!-- Search input -->
  <search role="search" aria-label="Search">
    <input
      type="search"
      aria-label="Search query"
      aria-expanded="true"           <!-- suggestions visible -->
      aria-controls="suggestions-list"
      aria-activedescendant="suggestion-2"  <!-- keyboard highlighted -->
      aria-autocomplete="list"
      autocomplete="off"
    />
    <ul id="suggestions-list" role="listbox" aria-label="Search suggestions">
      <li id="suggestion-0" role="option" aria-selected="false">...</li>
      <li id="suggestion-1" role="option" aria-selected="false">...</li>
      <li id="suggestion-2" role="option" aria-selected="true">...</li>
    </ul>
  </search>

  <!-- Filter tabs -->
  <nav aria-label="Result type filters">
    <ul role="tablist">
      <li role="tab" aria-selected="true" aria-controls="results-panel">All</li>
      <li role="tab" aria-selected="false">Images</li>
      ...
    </ul>
  </nav>

  <!-- Results -->
  <section id="results-panel" role="tabpanel" aria-label="Web results">
    <ol aria-label="Search results" role="list">
      <li class="result-card" role="listitem">
        <article>
          <h2><a href="...">Result Title</a></h2>
          <cite>example.com › path</cite>
          <p>Snippet text with <em>highlighted</em> terms...</p>
        </article>
      </li>
    </ol>
  </section>

  <!-- Pagination -->
  <nav aria-label="Search result pages">
    <a href="?p=2" aria-label="Page 2">2</a>
    <a href="?p=2" aria-label="Next page">Next</a>
  </nav>
</main>

// Announce result count after search
function announceResults(count: number, query: string): void {
  const announcer = document.getElementById("sr-announcer");
  announcer.textContent = `${count.toLocaleString()} results found for "${query}"`;
}

// Announce suggestion selection during keyboard nav
function announceSuggestion(text: string, index: number, total: number): void {
  const announcer = document.getElementById("sr-announcer");
  announcer.textContent = `${text}, suggestion ${index + 1} of ${total}`;
}

<div
  id="sr-announcer"
  aria-live="polite"
  aria-atomic="true"
  class="sr-only"
></div>

// Instrument critical path
performance.mark("search-submit");

// First result painted (via MutationObserver)
const observer = new MutationObserver((mutations) => {
  if (document.querySelector(".result-card")) {
    performance.mark("first-result-painted");
    performance.measure(
      "time-to-first-result",
      "search-submit",
      "first-result-painted",
    );
    observer.disconnect();
    reportMetric(
      "ttfr",
      performance.getEntriesByName("time-to-first-result")[0].duration,
    );
  }
});
observer.observe(document.getElementById("results-container"), {
  childList: true,
});

// Track suggestion latency
async function fetchSuggestions(query: string): Promise<Suggestion[]> {
  const start = performance.now();
  const response = await fetch(`/api/suggest?q=${encodeURIComponent(query)}`);
  const latency = performance.now() - start;
  reportMetric("suggestion_latency", latency, { prefix_length: query.length });
  return response.json();
}

// Track result clicks with position and dwell time
function trackResultClick(result: WebResult, queryId: string): void {
  const clickTime = Date.now();

  // Use Beacon API for reliable delivery (even on page unload)
  navigator.sendBeacon(
    "/api/track/click",
    JSON.stringify({
      queryId,
      resultId: result.trackingId,
      position: result.position,
      resultType: result.kind,
      action: "click",
      abCohort: getABCohort(), // Which layout variant
      timestamp: clickTime,
    }),
  );

  // Track dwell time when user returns (via Page Visibility API)
  document.addEventListener("visibilitychange", function handler() {
    if (document.visibilityState === "visible") {
      const dwellTime = Date.now() - clickTime;
      navigator.sendBeacon(
        "/api/track/click",
        JSON.stringify({
          queryId,
          resultId: result.trackingId,
          action: dwellTime > 30000 ? "long_click" : "return",
          dwellTimeMs: dwellTime,
        }),
      );
      document.removeEventListener("visibilitychange", handler);
    }
  });
}