DEV Community: ZeeshanAli-0704

Frontend System Design: Google Docs

ZeeshanAli-0704 — Sun, 19 Jul 2026 17:11:01 +0000

Frontend System Design: Google Docs (Collaborative Document Editor)

Frontend System Design: Google Docs (Collaborative Document Editor)
- 1. Concept, Idea, Product Overview
- 1.1 Product Description
- 1.2 Key User Personas
- 1.3 Core User Flows (High Level)
- 2. Requirements
- 2.1 Functional Requirements
- 2.2 Non Functional Requirements
- 3. Scope Clarification (Interview Scoping)
- 3.1 In Scope
- 3.2 Out of Scope
- 3.3 Assumptions
- 4. High Level Frontend Architecture
- 4.1 Overall Approach
- 4.2 Major Architectural Layers
- 4.3 External Integrations
- 5. Component Design and Modularization
- 5.1 Component Hierarchy
- 5.2 Rich Text Editor Engine (Deep Dive)
  - 5.2.1 Why ContentEditable vs Custom Rendering
  - 5.2.2 Document Model (Structured Data, Not HTML)
  - 5.2.3 Selection and Cursor Model
  - 5.2.4 Input Handling Pipeline
  - 5.2.5 Rendering Pipeline (Model to Canvas)
  - 5.2.6 Block and Inline Formatting
  - 5.2.7 Embedded Content (Images, Tables, Embeds)
- 5.3 Reusability Strategy
- 5.4 Module Organization
- 6. High Level Data Flow Explanation
- 6.1 Initial Load Flow
- 6.2 User Interaction Flow
- 6.3 Error and Retry Flow
- 7. Data Modelling (Frontend Perspective)
- 7.1 Core Data Entities
- 7.2 Data Shape
- 7.3 Entity Relationships
- 7.4 UI Specific Data Models
- 8. State Management Strategy
- 8.1 State Classification
- 8.2 State Ownership
- 8.3 Persistence Strategy
- 9. Real Time Collaboration Deep Dive
- 9.1 The Fundamental Problem of Concurrent Editing
- 9.2 Operational Transformation (OT)
  - 9.2.1 What is an Operation
  - 9.2.2 The Transform Function
  - 9.2.3 OT with a Central Server
  - 9.2.4 Complete OT Client Implementation
  - 9.2.5 Server Side OT Orchestration
- 9.3 CRDTs (Conflict Free Replicated Data Types)
  - 9.3.1 How CRDTs Differ from OT
  - 9.3.2 Sequence CRDTs for Text (Yjs Example)
  - 9.3.3 CRDT Integration with Editor
- 9.4 OT vs CRDT Comparison
- 9.5 Cursor and Selection Presence
- 9.6 WebSocket Transport Layer
- 9.7 Offline Editing and Reconnection
- 10. Undo Redo in Collaborative Context
- 11. High Level API Design (Frontend POV)
- 11.1 Required APIs
- 11.2 Request and Response Structure
- 11.3 Error Handling and Status Codes
- 12. Caching Strategy
- 13. CDN and Asset Optimization
- 14. Rendering Strategy
- 15. Cross Cutting Non Functional Concerns
- 15.1 Security
- 15.2 Accessibility
- 15.3 Performance Optimization
- 15.4 Observability and Reliability
- 16. Edge Cases and Tradeoffs
- 17. Summary and Future Improvements

1. Concept, Idea, Product Overview

1.1 Product Description

Google Docs is a web-based collaborative document editor that allows multiple users to create, edit, and format rich-text documents simultaneously in real time.
It is the defining example of real-time collaboration on the web — every keystroke from every user is reflected in all other users' views within milliseconds.
Target users: anyone who writes — students, professionals, writers, teams, enterprises. Over 1 billion users.
Primary use case: authoring and co-editing rich-text documents (reports, articles, meeting notes, proposals) with real-time multi-user collaboration, commenting, and version history.

1.2 Key User Personas

Solo Writer: Creates and edits documents alone. Expects fast, responsive typing, rich formatting (headings, lists, tables, images), and auto-save. May work across devices.
Collaborative Team Member: Edits documents simultaneously with 2-20 team members. Expects real-time cursor visibility, conflict-free concurrent editing, commenting/suggesting workflow, and version history.
Reviewer / Commenter: Opens shared documents in "Suggesting" or "Viewing" mode. Reads content, leaves comments, suggests edits (tracked changes), and resolves comment threads.

1.3 Core User Flows (High Level)

Editing a Document (Primary Flow):
1. User opens a document URL → document loads with the latest content.
2. User types text → characters appear instantly at the cursor position.
3. Every edit is auto-saved to the server (no save button).
4. If other users are present, their cursors are visible in real time with names and colors.
5. User applies formatting (bold, heading, list) → formatting is applied immediately.
6. All changes from all users are merged in real time without conflicts.
Commenting and Suggesting (Secondary Flow):
1. User selects text → clicks "Add comment" or switches to "Suggesting" mode.
2. Comment appears in the right margin, linked to the highlighted text.
3. Other users see the comment/suggestion in real time and can reply or resolve it.
Version History (Secondary Flow):
1. User opens "Version history" panel.
2. Sees a timeline of all changes grouped by author and time.
3. Can preview any past version and restore it.

2. Requirements

2.1 Functional Requirements

Rich Text Editing:
- Type, delete, copy, paste, cut text with full Unicode support.
- Inline formatting: bold, italic, underline, strikethrough, code, links, text color, highlight.
- Block formatting: headings (H1–H6), paragraphs, ordered/unordered lists, blockquotes, code blocks.
- Embedded content: images, tables, horizontal rules, page breaks.
Real Time Collaboration:
- Multiple users editing the same document simultaneously.
- Each user sees all others' changes in real time (sub-second latency).
- Cursor/selection presence: see where each collaborator's cursor is and what they've selected, with a color-coded name label.
- Conflict-free concurrent edits: two users typing at the same position must not lose either's work.
Comments and Suggestions:
- Add comments on selected text ranges.
- Threaded comment replies.
- "Suggesting" mode: edits appear as tracked changes that can be accepted or rejected.
Auto Save and Version History:
- All changes are automatically saved — no save button.
- Full version history with timestamps and author attribution.
- Ability to name versions and restore any previous state.
Sharing and Permissions:
- Share via link with permission levels: Viewer, Commenter, Editor.
- Real-time permission enforcement (viewer cannot edit).
Export and Import:
- Export as PDF, DOCX, plain text, HTML.
- Import from DOCX, plain text, HTML.

2.2 Non Functional Requirements

Performance: Typing must feel instantaneous (< 16ms input-to-screen latency for local edits). Document load < 2s for a 50-page document. Support documents with 100+ pages without sluggish scrolling.
Scalability: Support documents with 100+ pages, 50+ simultaneous editors, and 10,000+ revision history entries. Handle paste operations of 10,000+ characters seamlessly.
Availability: Offline editing support with sync on reconnect. Graceful degradation when the collaboration server is down — user can continue editing locally.
Security: Access control enforced at API level (viewer cannot send edit operations). All data in transit is TLS encrypted. Content is not stored in the frontend beyond the active session.
Accessibility: Full keyboard navigation. Screen reader support for document content (semantic DOM). WCAG AA contrast. Focus management in toolbars and dialogs.
Device Support: Desktop web (primary), tablet web, mobile web (basic editing). Chrome, Firefox, Safari, Edge.
i18n: Full RTL support (Arabic, Hebrew) including bidirectional text within documents. IME (Input Method Editor) support for CJK languages. Localized UI in 100+ languages.

3. Scope Clarification (Interview Scoping)

3.1 In Scope

Rich text editor architecture (document model, rendering, input handling).
Real-time collaboration deep dive (Operational Transformation, CRDTs, conflict resolution).
Cursor and selection presence across collaborators.
Auto-save and sync pipeline.
Document data model and state management.
Performance optimization for large documents.
Undo/redo in a multi-user context.

3.2 Out of Scope

Backend database and storage (we assume APIs exist).
Detailed permission system / sharing dialog.
Rich inline features (smart chips, @mentions autocomplete, spell check).
Add-ons and extensions marketplace.
Native mobile app.
Print/PDF rendering pipeline.

3.3 Assumptions

User is authenticated; auth token is available.
A WebSocket-based collaboration server exists (we design the frontend interaction).
Server provides an OT/CRDT-compatible API for document operations.
Documents are fetched as structured JSON (not raw HTML).
Media (images) are uploaded to a separate service and referenced by URL.

4. High Level Frontend Architecture

4.1 Overall Approach

SPA (Single Page Application) with client-side routing.
CSR (client-side rendering) only. A minimal static HTML app shell (index.html + JS/CSS bundles) is served from the CDN; everything — editor chrome, document metadata, and document content — is rendered on the client. We deliberately skip SSR because: the document content changes constantly (any collaborator edit invalidates server-rendered content instantly), it's auth-gated so there's no SEO benefit, the canvas rendering engine owns painting on the client (there is no server-paintable HTML to hydrate), and the editor needs the structured model JSON client-side anyway to type/undo/apply OT — once that's fetched, painting the visible viewport is single-digit milliseconds.
Hybrid canvas rendering engine (the approach real Google Docs uses since 2021). The document content area is painted onto a <canvas> rather than built as DOM nodes. Around that canvas we keep a parallel DOM layer the browser must still drive: a hidden input proxy for keystrokes/IME, an offscreen mirrored DOM for accessibility, and native selection/clipboard integration. contentEditable is NOT used for the visible content — only a hidden input element captures input. The chrome (menus, toolbar, sidebars, dialogs) is ordinary DOM.
Monolith frontend — the editor is highly integrated; micro-frontends add unnecessary complexity for a deeply coupled editing experience.

4.2 Major Architectural Layers

┌──────────────────────────────────────────────────────────────┐
│  UI Layer                                                    │
│  ┌───────────────────────┐  ┌─────────────────────────────┐  │
│  │ Toolbar / Menu Bar    │  │ Editor Surface              │  │
│  │ (formatting, actions) │  │  ┌──────────────────────┐   │  │
│  ├───────────────────────┤  │  │ <canvas> content     │   │  │
│  │ Comment Sidebar       │  │  │ (PAINTED from model) │   │  │
│  │ (threads, replies)    │  │  ├──────────────────────┤   │  │
│  ├───────────────────────┤  │  │ Cursor Overlays      │   │  │
│  │ Version History Panel │  │  │ (remote cursors)     │   │  │
│  │ (timeline, preview)   │  │  ├──────────────────────┤   │  │
│  ├───────────────────────┤  │  │ Selection Highlights │   │  │
│  │ Permissions Banner    │  │  │ (remote selections)  │   │  │
│  │ (viewer / editor)     │  │  └──────────────────────┘   │  │
│  └───────────────────────┘  └─────────────────────────────┘  │
├──────────────────────────────────────────────────────────────┤
│  Document Model Layer                                        │
│  (Tree / flat structure of nodes: paragraphs, text runs,     │
│   inline marks, block types, embedded objects)               │
├──────────────────────────────────────────────────────────────┤
│  Editor Core (Command / Transaction Layer)                   │
│  (Operations: insert, delete, format, split, merge.          │
│   Selection model, Schema validation, Input handling)        │
├──────────────────────────────────────────────────────────────┤
│  Collaboration Layer                                         │
│  (OT / CRDT engine, WebSocket transport,                     │
│   Presence manager, Conflict resolution)                     │
├──────────────────────────────────────────────────────────────┤
│  Persistence Layer                                           │
│  (Auto-save manager, Version history client,                 │
│   Offline buffer, Export/Import)                             │
├──────────────────────────────────────────────────────────────┤
│  Shared / Utility Layer                                      │
│  (Keyboard manager, Clipboard handler, IME handler,          │
│   Selection utilities, Analytics tracker)                    │
└──────────────────────────────────────────────────────────────┘

Rendering note (hybrid canvas): the Editor Surface box is a <canvas> painted from the document model — not DOM nodes. Between the UI Layer and the Document Model Layer sits a Rendering Layer (Canvas): a layout engine (line breaking, pagination, BiDi), a text shaper, a canvas painter that repaints only dirty regions, and a geometry map (model position ↔ pixel coordinates) used for hit-testing clicks and positioning the caret. Alongside the canvas, a parallel DOM provides the hidden input proxy (keystrokes/IME), native selection/clipboard, and an offscreen mirror DOM for accessibility. All chrome (menus, toolbar, sidebars) is ordinary DOM.

4.3 External Integrations

Collaboration Server: WebSocket-based server that receives operations from all clients, transforms them (OT), and broadcasts the transformed operations to all other clients.
Document Storage API: REST API for loading/saving document snapshots, version history, and metadata.
Media Upload Service: Separate endpoint for image/file uploads; returns a URL for embedding.
Comment Service: REST + real-time API for comments and suggestion threads.
Analytics SDK: Track editing session duration, collaboration metrics, feature usage.
Spell Check / Grammar Service: Server-side NLP service called asynchronously with document text.

5. Component Design and Modularization

5.1 Component Hierarchy

DocumentPage
 ├── MenuBar
 │    ├── FileMenu (new, open, import, export, share)
 │    ├── EditMenu (undo, redo, cut, copy, paste, find/replace)
 │    ├── ViewMenu (zoom, page break, ruler)
 │    └── InsertMenu (image, table, link, heading, page break)
 │
 ├── Toolbar
 │    ├── UndoRedoButtons
 │    ├── FontSelector
 │    ├── FontSizeSelector
 │    ├── InlineFormatButtons (bold, italic, underline, strikethrough, code)
 │    ├── TextColorPicker
 │    ├── HighlightColorPicker
 │    ├── AlignmentButtons (left, center, right, justify)
 │    ├── ListButtons (ordered, unordered, checklist)
 │    ├── IndentButtons (indent, outdent)
 │    └── InsertButtons (link, image, table, comment)
 │
 ├── EditorSurface (main editing area)
 │    ├── CanvasContent (<canvas> — the document is PAINTED here from the model,
 │    │     not built as DOM nodes; simulates paper pages, handles pagination)
 │    │     └── (logical, painted per frame) BlockNode[] → ParagraphBlock / HeadingBlock /
 │    │         ListBlock / CodeBlock / BlockquoteBlock / TableBlock / ImageBlock
 │    │         (these are MODEL nodes the painter draws — there is no DOM per block)
 │    ├── CursorOverlay (local caret + remote cursors with name labels)
 │    ├── SelectionOverlay (colored highlights for local + remote selections)
 │    ├── HiddenInputProxy (invisible focusable element — captures keystrokes,
 │    │     beforeinput, paste, and IME composition; visible caret is painted, not native)
 │    ├── AccessibilityMirror (offscreen semantic DOM: <h1>/<p>/<ul>/<table>…,
 │    │     kept in sync with the model so screen readers can read/navigate)
 │    └── FloatingToolbar (appears on text selection — quick format options)
 │
 ├── CommentSidebar
 │    └── CommentThread[]
 │         ├── CommentBody
 │         ├── CommentReplies
 │         └── ResolveButton
 │
 ├── VersionHistoryPanel (slide-in from right)
 │    ├── VersionTimeline
 │    └── VersionPreview
 │
 └── CollaboratorAvatars (top-right — shows who's online)

5.2 Rich Text Editor Engine (Deep Dive)

Building a collaborative rich text editor is one of the most complex frontend engineering challenges. The editor must:

Capture user input reliably across all browsers, IME systems, and operating systems.
Maintain a structured document model that is independent of the DOM.
Paint the document model to a <canvas> efficiently, while keeping a parallel offscreen DOM for accessibility.
Support concurrent editing from multiple users without conflicts.
Handle undo/redo correctly in a multi-user context.

5.2.1 Why ContentEditable vs Custom Rendering

Every rich text editor on the web must decide how to capture user input and render content. There are three fundamental approaches:

Approach	How it works	Used by	Pros	Cons
Full `contentEditable`	Set `contentEditable="true"` on a div. Let the browser handle all input, rendering, selection, and formatting.	Simple WYSIWYG editors (Quill v1, Medium's first editor)	Zero effort for basic editing; browser handles IME, spell check, autocomplete natively	Wildly inconsistent across browsers; DOM is the model (fragile); very hard to add custom behavior; nightmare for collaboration
ContentEditable for input, custom model for data	Use `contentEditable` to capture keystrokes and IME input. But maintain a separate structured data model. On input, translate the DOM mutation into a model operation, then re-render the model back to DOM.	Slate.js, ProseMirror, TipTap, pre-2021 Google Docs	Input capture is reliable (leverages browser's IME/spell check); model is clean and structured; collaboration-friendly	Must keep DOM and model in sync; complex input pipeline; occasional browser quirks in contentEditable
Custom input (Canvas + parallel DOM)	Paint the document on a `<canvas>` element. Capture input via a hidden editable/`<textarea>` element and drive selection, clipboard, and the accessibility tree through a parallel (often off-screen) DOM. Bypass `contentEditable` for rendering only.	Google Docs (2021+ hybrid canvas renderer), Figma (for text editing)	Full control over rendering and layout; pixel-perfect consistency; no browser DOM rendering quirks	Must implement ALL text rendering (line breaking, BiDi, ligatures, caret blinking, selection rectangles) AND maintain a mirror DOM for a11y/IME/clipboard; massive engineering effort

Strategy for this design: hybrid canvas rendering + custom document model + parallel DOM for input/a11y.
This is the architecture real Google Docs uses today (since 2021), and the one we adopt here. The document content is painted onto a <canvas> from the structured model, giving us pixel-perfect, browser-consistent rendering and full control over pagination and layout. Everything the browser must still natively drive is handled by a parallel DOM layer that sits with the canvas:

Input capture — a hidden, focusable input element (a tiny contentEditable/<textarea> proxy) receives keystrokes, beforeinput, and paste events. It is visually invisible; the visible caret is painted on the canvas.
IME / composition — CJK and dead-key composition run through that same hidden input element and the browser's composition APIs, then commit a single operation to the model.
Selection & clipboard — copy/cut/paste and OS-level selection integrate through the DOM; the visible selection rectangles are painted on the canvas from the layout geometry.
Accessibility — an offscreen, semantically-structured mirror DOM (<h1>, <p>, <ul>, <table>…) is kept in sync with the model so screen readers can read and navigate the document (a bare <canvas> is opaque to assistive tech).

So the one-line framing for an interview: "Canvas paints the content for consistency and performance; a parallel DOM layer provides input, IME, selection, clipboard, and accessibility." This directly answers the classic follow-up — "if it's all canvas, how do screen readers work?" — with the offscreen mirror DOM.

Cost of this choice (be honest in an interview): we must implement our own layout engine (line breaking, pagination, BiDi, ligatures), our own caret/selection painting, and keep the mirror DOM in sync — a large engineering investment. The alternative (contentEditable for input + DOM rendering, used by ProseMirror/Slate/TipTap and pre-2021 Google Docs) is far less work and gets native IME/spell-check/selection "for free," at the cost of browser rendering inconsistencies. We choose canvas here to match modern Google Docs and to control large-document performance; §17 notes the DOM approach as a lighter-weight fallback.

5.2.2 Document Model (Structured Data, Not HTML)

The editor does NOT use HTML as its data model. Instead, it maintains a structured tree of typed nodes that represents the document content independently of how it's displayed.

Why not use the DOM as the model?

Aspect	DOM as model	Custom structured model
Data shape	Inconsistent HTML — the DOM a browser produces for the same user action varies across browsers and editing scenarios (stray wrapper `<span>`s, `<br>`s, legacy `<font>`/`<b>` nodes)	Clean, typed, predictable JSON tree
Serialization	Must parse/sanitize HTML	`JSON.stringify()` — trivial
Collaboration	How do you diff arbitrary HTML? Very hard	Operations on typed nodes are well-defined
Undo/redo	Browser's built-in undo is unreliable across browsers	Custom command stack with full control
Validation	Can the DOM contain a heading inside a list item? No easy way to enforce	Schema defines allowed structures; invalid changes are rejected
Cross-platform	Different browsers produce different HTML for the same user action	Model is browser-agnostic

Document Tree Structure

Document
 └── Block[]
      ├── Paragraph
      │    └── TextRun[]
      │         ├── { text: "Hello ", marks: [] }
      │         ├── { text: "world", marks: ["bold"] }
      │         └── { text: "!", marks: [] }
      │
      ├── Heading (level: 2)
      │    └── TextRun[]
      │         └── { text: "Introduction", marks: [] }
      │
      ├── BulletList
      │    └── ListItem[]
      │         ├── ListItem
      │         │    └── Paragraph → TextRun[]
      │         └── ListItem
      │              └── Paragraph → TextRun[]
      │
      ├── CodeBlock
      │    └── { text: "const x = 1;", language: "javascript" }
      │
      ├── Table
      │    └── TableRow[]
      │         └── TableCell[]
      │              └── Block[] (paragraphs inside cells)
      │
      └── Image
           └── { src: "...", alt: "...", width: 400, height: 300 }

JSON Representation

{
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Hello ", "marks": [] },
        { "type": "text", "text": "world", "marks": [{ "type": "bold" }] },
        { "type": "text", "text": "!", "marks": [] }
      ]
    },
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [
        { "type": "text", "text": "Introduction", "marks": [] }
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [
                { "type": "text", "text": "First item", "marks": [] }
              ]
            }
          ]
        }
      ]
    }
  ]
}

This model is:

Framework-agnostic — just data; can be rendered by React, vanilla JS, or even Canvas.
Serializable — JSON.stringify() for saving; JSON.parse() for loading.
Diffable — operations transform this model, and diffs can be computed for collaboration.
Validatable — a schema defines what node types exist and where they can appear.

5.2.3 Selection and Cursor Model

The browser's native Selection API is DOM-based (anchored to DOM nodes + offsets) — but our content is painted on a <canvas> and has no per-character DOM to anchor to. So the editor uses a model-based selection: positions that reference the document model, independent of any rendering. (The hidden input proxy and offscreen a11y mirror have their own DOM selections, but those are derived from the model selection, not the source of truth.)

Model Position

A position in the document model is a numerical offset counting from the start of the document. Every "step" into or out of a node counts as one position:

Content:  "Hello world"
Position: 0     1     2     3     4     5     6     7     8     9     10    11

If the model is two paragraph blocks:  Paragraph["Hello"]  Paragraph["World"]

Model positions (counting steps into/out of MODEL nodes — no DOM involved):
  0: before Paragraph #1
  1: before 'H'
  2: before 'e'
  3: before 'l'
  4: before 'l'
  5: before 'o'
  6: after 'o' / after Paragraph #1
  7: before Paragraph #2
  8: before 'W'
  ...

A selection is: { anchor: 2, head: 5 }  →  selects "ello"
A cursor is:    { anchor: 5, head: 5 }  →  cursor after "Hello"

This model-based selection is:

Independent of the DOM — if the canvas repaints, the model position is still valid.
Shareable — we can send { anchor: 5, head: 5 } to other collaborators to show our cursor.
Transformable — when a remote user inserts text before position 5, we can adjust our position to 5 + insertLength.

With canvas rendering, there is no native browser caret in the content. We convert a model position to pixel coordinates using the layout geometry map, then paint the caret (a blinking vertical bar) on the canvas ourselves. Conversely, a mouse click is hit-tested against the geometry map to find the nearest model position. The hidden input proxy holds focus so the OS keeps sending key events, but its native caret is not shown.

type EditorSelection = {
  anchor: number;  // where the selection started (user pressed mouse down)
  head: number;    // where the selection ended (user released mouse)
};

// Cursor is a collapsed selection
type Cursor = EditorSelection; // where anchor === head

anchor is the fixed end (where you pressed down); head is the moving end (where the caret currently is). Dragging left-to-right vs right-to-left just swaps which is larger — the selected range is always between them.
A collapsed selection (anchor === head) has zero width: it is simply the blinking cursor, with no text selected. Every cursor is just a selection where both ends coincide, so the editor only needs one concept to represent both.
Because a selection is two integers, the whole editor speaks one language: input, formatting, comments, and presence all describe ranges as { from, to } model positions.

5.2.4 Input Handling Pipeline

The input pipeline converts raw browser events into document model operations. This is the most challenging part of editor development because of IME (Input Method Editor), autocorrect, speech-to-text, and browser inconsistencies.

Browser event on the HIDDEN INPUT PROXY
(keydown, beforeinput, input, compositionstart/end, paste, drop)
     ↓
Input Handler (intercepts and classifies)
     ↓
┌─────────────────────────────────────────────────────────┐
│  Classification:                                         │
│  - Regular character input → create InsertText op        │
│  - Backspace/Delete → create DeleteText op               │
│  - Enter → create SplitBlock op                          │
│  - Tab in list → create IndentListItem op                │
│  - Ctrl+B → create ToggleMark("bold") op                 │
│  - Paste → parse clipboard → create InsertSlice op       │
│  - IME composition → buffer until compositionend         │
│  - Drop → parse drag data → create InsertSlice op        │
└─────────────────────────────────────────────────────────┘
     ↓
Create Transaction (one or more operations)
     ↓
Apply Transaction to Document Model
     ↓
Emit to Collaboration Layer (send operation to server)
     ↓
Re-layout affected lines → REPAINT the dirty canvas region (view update)
     ↓
Sync the offscreen accessibility mirror DOM + update the painted caret position

Where does input come from with a canvas? A <canvas> can receive focus and keyboard events — but it is not a native text-editing control. It provides none of the browser-managed editing machinery: no text insertion, no IME composition, no selection model, no clipboard behavior, no accessibility tree. So we place a hidden, focusable input proxy (a tiny contentEditable or <textarea>) over the canvas to get all of that. It holds focus, receives all keystrokes / beforeinput / paste / IME events, and we translate those into model operations — then repaint. The real caret is painted on the canvas; the proxy's own caret is hidden.

Why `beforeinput` Event is Critical

Modern editors lean on the beforeinput event (InputEvent Level 2) as the primary signal — but not the only one. Browser support and fidelity vary (Safari has historically had beforeinput quirks, Firefox support lagged for years), so production editors combine several events: beforeinput (intercept intent), compositionstart/update/end (IME), keydown (shortcuts and keys beforeinput doesn't cleanly expose), input (a fallback to reconcile DOM the browser mutated anyway), and selectionchange (track caret/selection). The mental model is "beforeinput-first, with composition/keydown/input/selectionchange as complements," not "beforeinput alone."

Event	What it tells you	Why it matters
`keydown`	Which physical key was pressed	Doesn't tell you what character will be produced (IME, dead keys, compose)
`input`	The DOM was already mutated	Too late — the DOM changed before you could intercept
`beforeinput`	What the browser intends to do AND you can prevent it	You can intercept, create your own model operation, and cancel the default mutation

What does preventDefault() actually prevent? It stops the browser from mutating the hidden input proxy's DOM — not the visible document (the visible document is a canvas the browser can't touch anyway). The mental model: the browser does mutate the hidden proxy on input, but we cancel that and instead apply a clean operation to our model, then repaint. So the invariant is "the browser never mutates the editor's visible document," not "the browser never runs."

// `inputProxy` is the hidden, focusable element overlaid on the canvas.
inputProxy.addEventListener('beforeinput', (event: InputEvent) => {
  // Prevent the proxy from mutating its own DOM directly
  event.preventDefault();

  switch (event.inputType) {
    case 'insertText':
      // User typed a character
      applyOperation(insertText(selection, event.data!));
      break;

    case 'insertParagraph':
      // User pressed Enter
      applyOperation(splitBlock(selection));
      break;

    case 'deleteContentBackward':
      // User pressed Backspace
      applyOperation(deleteBackward(selection));
      break;

    case 'deleteContentForward':
      // User pressed Delete
      applyOperation(deleteForward(selection));
      break;

    case 'insertFromPaste':
      // User pasted content
      const html = event.dataTransfer?.getData('text/html');
      const text = event.dataTransfer?.getData('text/plain');
      applyOperation(insertSlice(selection, parseClipboard(html, text)));
      break;

    case 'formatBold':
      applyOperation(toggleMark('bold', selection));
      break;

    // ... other inputTypes
  }
});

IME (Input Method Editor) Handling

For CJK (Chinese, Japanese, Korean) languages, users type in a composition mode where multiple keystrokes produce a single character. (Those Latin letters aren't English — "ni" is romaji/pinyin, the phonetic spelling typed on a normal QWERTY keyboard, which the IME converts into the target character: Japanese に, Chinese 你, etc. CJK users don't have per-character keys, so they type the pronunciation and the IME assembles/picks the character.)

Who starts composition — and how the editor detects it. The editor never starts composition; the OS + IME + browser do. When an IME is active at the OS level and the user types into a focusable editable element, the OS routes keystrokes into the IME engine, which tells the browser to fire compositionstart. The editor is purely reactive: it listens for the composition events and buffers.

⚠️ Why the input proxy must be truly editable: browsers only fire compositionstart/update/end on an editable element (contentEditable or <textarea>). A plain <div> or a <canvas> receives no composition events. This is a core reason the design uses a real hidden editable proxy — it's the only way to receive IME input at all.

How you decide "this is composition" — the isComposing flag. You don't guess by language. Two unambiguous signals:

The compositionstart/compositionend pair — set a boolean flag between them.
Every event fired mid-composition also carries event.isComposing === true (on beforeinput, keydown, input). So if (event.isComposing) return; is the decision — "stay out of the way until composition ends." (Historically, a keydown with keyCode === 229 was the "IME is handling this key" signal, used before isComposing existed.)

The exact event sequence for romaji ni → に:

compositionstart                         ← IME began; set isComposing = true
   ↓
keydown (keyCode 229 = "IME handling")
beforeinput (inputType: "insertCompositionText", isComposing: true)   ← SKIP
compositionupdate (data: "n")            ← preview; browser paints "n" in the proxy
   ↓
keydown (229)
beforeinput (insertCompositionText, isComposing: true)                ← SKIP
compositionupdate (data: "に")           ← preview now shows "に"
   ↓
compositionend (data: "に")              ← FINAL; isComposing = false → commit "に" ONCE

Key rule: everything between start and end is a preview the browser renders inside the hidden proxy — we do NOT touch the document model. Only on compositionend do we apply the final composed text as a single operation and repaint the canvas.

Where does the preview show with a canvas? During composition, the IME candidate popup and the underlined composing text are rendered natively by the browser inside the hidden input proxy, not on the canvas. Most editors briefly position the proxy at the caret (via the geometry map) and let it be visible during composition so the browser handles the IME UI for free — then hide it and paint the committed text on the canvas at compositionend.

let isComposing = false;

inputProxy.addEventListener('compositionstart', () => {
  isComposing = true;
  // Let the browser handle composition rendering natively (in the proxy)
});

inputProxy.addEventListener('compositionend', (event) => {
  isComposing = false;
  // Now apply the final composed text as a single operation, then repaint
  applyOperation(insertText(selection, event.data));
});

// In beforeinput handler, skip input during composition
inputProxy.addEventListener('beforeinput', (event) => {
  if (event.isComposing || isComposing) return; // the decision: don't touch the model mid-composition
  event.preventDefault();
  // ... handle normally
});

5.2.5 Rendering Pipeline (Model to Canvas)

After every edit, the document model changes and the <canvas> must be repainted to reflect it. This is NOT a full repaint of the whole document — it's a layout + dirty-region repaint that re-lays-out only the affected lines and repaints only the pixels that changed.

Document Model (after edit)
     ↓
Layout pass (only the affected block/lines):
  - break text into lines (wrapping, BiDi, tabs)
  - shape runs into glyphs (font, size, marks)
  - compute geometry: x/y/width/height per line, per run, per glyph cluster
  - update the geometry map (model position ↔ pixel coordinates)
     ↓
Paint pass (dirty region only):
  - clearRect() the changed region of the canvas
  - draw text runs with their marks (bold/italic/color/highlight/link)
  - draw block decorations (list bullets, blockquote bar, table grid)
  - draw the caret + selection rectangles from the geometry map
     ↓
Sync the offscreen accessibility mirror DOM for the changed blocks

Because the content is pixels (not DOM), there is no live browser selection inside the content to disturb — repainting a line cannot make the caret "jump," and IME composition (handled in the hidden proxy) is unaffected. Repaints are scheduled on requestAnimationFrame so multiple model changes in one frame coalesce into a single paint.

Why Canvas Instead of DOM (or React) for the Content?

Approach	How it works	Assessment
React-rendered content	Each paragraph / text run is a React component	Rejected. The core problem is DOM ownership: the browser (editing/IME/selection), the OS, and React's reconciler all fight over the same editable DOM subtree → caret loss, IME corruption, reconciler clobbering native mutations. Typing latency is only one symptom.
Custom DOM patching	Editor kernel patches text nodes directly (`textNode.data = ...`)	Viable, lighter-weight (ProseMirror / Slate / pre-2021 Google Docs). Native IME/selection/spell-check for free, but you inherit browser rendering inconsistencies and still fight `contentEditable` quirks. Good fallback (see §17).
Canvas painting	Paint glyphs onto `<canvas>` from the model; parallel DOM for input/a11y	Chosen (modern Google Docs). Pixel-perfect, browser-consistent rendering; full control over line breaking, pagination, and large-document performance. Cost: build your own layout/paint engine and keep a mirror DOM for accessibility.

Modern Google Docs paints content on canvas; ProseMirror / Slate patch the DOM directly. Neither uses a framework's virtual DOM for the editable content.

The paint routine for a paragraph (conceptual):

// ctx is the 2D canvas context; layout is the pre-computed geometry for this block.
function paintParagraph(ctx: CanvasRenderingContext2D, block: ParagraphNode, layout: BlockLayout) {
  // Repaint only this block's rectangle
  ctx.clearRect(layout.x, layout.y, layout.width, layout.height);

  for (const line of layout.lines) {
    for (const runBox of line.runs) {
      const run = runBox.run;

      // Build the font string from the run's marks
      let fontStyle = '';
      let fontWeight = 'normal';
      let fillStyle = '#202124';
      for (const mark of run.marks) {
        if (mark.type === 'bold') fontWeight = 'bold';
        if (mark.type === 'italic') fontStyle = 'italic';
        if (mark.type === 'textColor') fillStyle = mark.attrs.color;
        if (mark.type === 'highlight') {
          ctx.fillStyle = mark.attrs.color;
          ctx.fillRect(runBox.x, runBox.y, runBox.width, runBox.height); // paint highlight behind
        }
      }

      ctx.font = `${fontStyle} ${fontWeight} ${block.fontSize}px ${block.fontFamily}`;
      ctx.fillStyle = fillStyle;
      ctx.fillText(run.text, runBox.x, runBox.baselineY);

      // Underline for links / underline mark
      if (run.marks.some(m => m.type === 'underline' || m.type === 'link')) {
        ctx.fillRect(runBox.x, runBox.baselineY + 2, runBox.width, 1);
      }
    }
  }
}

The geometry map is the crux of a canvas editor. Because the content has no DOM, you must maintain a position ↔ pixel map produced by the layout pass. It powers three things: (1) hit-testing clicks/drag-selection back to model positions, (2) painting the caret and selection rectangles, and (3) positioning remote collaborators' cursors. It's cached per block (e.g. in a WeakMap keyed by block) and recomputed incrementally only for blocks whose content or width changed — this is what keeps repaint cheap on a 100+ page document.

The Pipeline in Plain Terms

The document model is the source of truth (the words and their styles); the <canvas> is only a view of it. Rendering is the act of turning the model into pixels, and the whole design is optimized around one goal: make typing feel instant. Five ideas carry the section:

Repaint only what changed, never the whole document. Typing one character marks a single line "dirty." The pipeline erases only that line's rectangle (clearRect) and repaints only it; the other lines — potentially hundreds of pages — are left untouched. A full-document repaint on every keystroke would be prohibitively slow.
Layout comes before paint — measure, then draw. The layout pass decides where everything goes: it breaks text into lines (wrapping, BiDi, tabs), shapes runs into glyphs for the chosen font, and records the x/y/width/height of every line, run, and glyph cluster. Only then does the paint pass actually draw those glyphs and their marks. Layout is the pencil guidelines; paint is the ink.
Pixels can't be fought over. In the DOM approach every character is a live node that the browser, the OS, and the framework's reconciler all contend for — the root cause of caret loss and IME corruption. Canvas content is just pixels, so repainting a line can never dislodge the caret, and IME composition (which lives in the hidden proxy) is never touched.
Batch paints to the frame. Several model changes in one frame (e.g. a fast burst of keystrokes) coalesce into a single paint scheduled on requestAnimationFrame (~60 fps), rather than painting once per change.
The geometry map makes an image editable. Because the content is pixels with nothing to point at, the position ↔ pixel map is what lets a click resolve to a model position (hit-testing), lets the caret and selection rectangles be painted at the right place, and lets remote collaborators' cursors be positioned. Without it, a canvas is unusable for editing.

In one sentence: on each edit the engine re-lays-out and repaints only the affected line, draws its glyphs with their marks onto the canvas, keeps a position ↔ pixel map so clicks and carets work, and batches paints to the animation frame — so editing stays instant even on a 100+ page document.

Hit-Testing (Pixel → Model Position)

Hit-testing answers: "the user clicked at pixel (x, y) — what model position is that?" With DOM, the browser does this for free — a click lands on a specific <span> node. With canvas the content is just pixels, so the browser can only report a coordinate, not a character. The editor must translate that coordinate back to a model position itself, using the same geometry map the layout pass produced.

The lookup walks the geometry map from coarse to fine:

Click at (310, 88)
  1. Which line's vertical band contains y = 88?            → line 4
  2. Within line 4, which run's x-range contains x = 310?   → run "world"
  3. Within that run, which glyph edge is x = 310 nearest?  → between 'r' and 'l'
  4. Return the model position                             → position 42

The editor now knows the click means model position 42 and can place the caret, start a drag-selection, extend a selection, or resolve a word boundary from there.

Interaction	What hit-testing resolves
Single click	one pixel → caret position
Click-drag	two pixels → selection range (anchor + head)
Double-click	pixel → surrounding word boundaries
Hover / click a link	pixel → is a `link` mark present at this position?

Hit-testing is the pixel → position direction; painting the caret and remote cursors is the reverse position → pixel direction. Both query the same geometry map — which is exactly why §5.2.5 calls it the crux of a canvas editor.

5.2.6 Block and Inline Formatting

Inline Marks (Applied to Text Runs)

Marks are formatting attributes attached to text ranges. A single character can have multiple marks (bold + italic + link).

Text: "Hello bold world"
Marks: [
  { type: "text", text: "Hello ", marks: [] },
  { type: "text", text: "bold", marks: [{ type: "bold" }] },
  { type: "text", text: " world", marks: [] },
]

When the user selects "bold" and presses Ctrl+I (italic):

Before: { text: "bold", marks: [{ type: "bold" }] }
After:  { text: "bold", marks: [{ type: "bold" }, { type: "italic" }] }

Block Types (Applied to Structural Nodes)

Block operations change the type of a node in the document tree:

Before: { type: "paragraph", content: [{ text: "My Title" }] }
  ↓ User applies "Heading 1"
After:  { type: "heading", attrs: { level: 1 }, content: [{ text: "My Title" }] }

Formatting as Operations

Every formatting change is an operation in the collaboration sense:

type FormatOperation = {
  type: 'addMark' | 'removeMark' | 'setBlockType';
  from: number;      // start position in document
  to: number;        // end position
  mark?: Mark;       // for inline marks
  blockType?: string; // for block type changes
  attrs?: Record<string, any>;
};

This operation can be:

Applied locally and rendered immediately.
Sent to the collaboration server for transformation and broadcast.
Stored in the undo/redo history.

5.2.7 Embedded Content (Images, Tables, Embeds)

Images

Images are "atom" nodes — they are leaf nodes in the document tree that represent a single object, not a container of text.

type ImageNode = {
  type: 'image';
  attrs: {
    src: string;
    alt: string;
    width: number;
    height: number;
    alignment: 'left' | 'center' | 'right' | 'inline';
  };
};

Image upload flow:

User pastes/drops an image.
Generate a temporary local blob URL → insert an ImageNode with src = blob:....
Upload the image to the media service in the background.
On upload success, replace src with the permanent CDN URL.
If upload fails, show an error overlay on the image with a retry button.

Tables

Tables are complex nested structures:

type TableNode = {
  type: 'table';
  content: TableRowNode[];
};

type TableRowNode = {
  type: 'tableRow';
  content: TableCellNode[];
};

type TableCellNode = {
  type: 'tableCell';
  attrs: {
    colspan: number;
    rowspan: number;
    backgroundColor?: string;
  };
  content: BlockNode[];  // Each cell contains paragraphs
};

Tables are particularly challenging for collaboration because operations can affect multiple cells (merge cells, add row, resize columns) and must be correctly transformed.

5.3 Reusability Strategy

EditorCore: Headless editor engine (document model, operations, schema) — reusable across different UI surfaces (full editor, comment editor, inline text fields).
FormatButton: Generic toolbar button component that reads the current selection's state and dispatches format operations.
BlockPainter: Polymorphic painter that delegates to a type-specific paint routine based on the block's type property (paragraph, heading, list, table, image).
CollaborationProvider: React context that provides the WebSocket connection and OT/CRDT engine to any component that needs it.
PresenceCursor: Renders a colored cursor with a name label; reused for each remote collaborator.
Design tokens for editor chrome (toolbar colors, spacing, font stacks).

5.4 Module Organization

src/
 ├── editor/
 │    ├── model/
 │    │    ├── documentModel.ts    (tree structure, node types)
 │    │    ├── schema.ts           (allowed node/mark types and relationships)
 │    │    ├── selection.ts        (model-based selection)
 │    │    └── position.ts         (position mapping, resolve)
 │    ├── operations/
 │    │    ├── insertText.ts
 │    │    ├── deleteText.ts
 │    │    ├── splitBlock.ts
 │    │    ├── joinBlocks.ts
 │    │    ├── setBlockType.ts
 │    │    ├── toggleMark.ts
 │    │    ├── insertSlice.ts      (paste/drop)
 │    │    └── tableOps.ts         (add row, merge cell, etc.)
 │    ├── render/
 │    │    ├── canvasView.ts       (canvas setup, rAF repaint loop, dirty-region tracking)
 │    │    ├── layoutEngine.ts      (line breaking, wrapping, pagination, BiDi)
 │    │    ├── textShaper.ts        (font metrics, glyph shaping, measure cache)
 │    │    ├── blockPainter.ts      (paint paragraph, heading, list, table, image)
 │    │    ├── markPainter.ts       (bold, italic, underline, link, highlight)
 │    │    ├── geometryMap.ts       (model position ↔ pixel coords; hit-testing)
 │    │    ├── caretSelectionPaint.ts (paint local/remote carets + selection rects)
 │    │    ├── a11yMirror.ts        (offscreen semantic DOM synced from model)
 │    │    └── decorations.ts       (comment highlights, find/replace highlights)
 │    ├── input/
 │    │    ├── inputProxy.ts       (hidden focusable element over the canvas)
 │    │    ├── inputHandler.ts     (beforeinput, keydown)
 │    │    ├── imeHandler.ts       (composition events)
 │    │    ├── clipboardHandler.ts (paste, copy, cut)
 │    │    └── dropHandler.ts      (drag and drop)
 │    └── history/
 │         ├── undoManager.ts
 │         └── historyEntry.ts
 ├── collaboration/
 │    ├── otClient.ts              (OT client state machine)
 │    ├── otTransform.ts           (transform functions)
 │    ├── wsTransport.ts           (WebSocket connection)
 │    ├── presenceManager.ts       (cursor/selection sharing)
 │    └── offlineBuffer.ts         (queue ops when offline)
 ├── components/
 │    ├── DocumentPage.tsx
 │    ├── EditorSurface.tsx
 │    ├── Toolbar.tsx
 │    ├── FormatButton.tsx
 │    ├── CommentSidebar.tsx
 │    ├── VersionHistoryPanel.tsx
 │    ├── CollaboratorAvatars.tsx
 │    ├── CursorOverlay.tsx
 │    └── ImageUploadOverlay.tsx
 ├── api/
 │    ├── documentApi.ts
 │    ├── commentApi.ts
 │    └── mediaApi.ts
 ├── shared/
 │    ├── keyboard.ts
 │    ├── clipboard.ts
 │    ├── debounce.ts
 │    └── analytics.ts
 └── types/
      └── types.ts

6. High Level Data Flow Explanation

6.1 Initial Load Flow

1. User navigates to /doc/:docId
     ↓
2. CDN serves the static app shell (index.html + JS/CSS bundles) — no server-side rendering
     ↓
3. App boots on the client → DocumentPage mounts (renders editor chrome immediately)
     ↓
4. Fetch full document: GET /api/docs/:docId
     ↓
5. Initialize document model from response JSON
     ↓
6. Paint document model onto the content canvas (editor surface); build the a11y mirror DOM
     ↓
7. Establish WebSocket connection for collaboration: wss://collab.example.com/:docId
     ↓
8. Receive any pending operations from other users since the snapshot was taken
     ↓
9. Apply pending operations → document is now in sync
     ↓
10. Editor is ready — user can type

6.2 User Interaction Flow

Typing a character:

User types "a"
     ↓
1. beforeinput fires on the hidden input proxy (inputType: "insertText", data: "a")
     ↓
2. event.preventDefault() — prevent the proxy from mutating its own DOM
     ↓
3. Create operation: insert("a", position=42)
     ↓
4. Apply operation to document model → model updated
     ↓
5. Re-layout the affected line → repaint that dirty canvas region → user sees "a" instantly
     ↓
6. Update model selection (move caret right by 1) → repaint caret; sync a11y mirror
     ↓
7. Record in undo history
     ↓
8. Send operation to collaboration server via WebSocket
     ↓
9. Server transforms + broadcasts to other clients
     ↓
10. Other clients apply the transformed operation → they repaint and see "a" appear

Applying formatting:

User selects "world" → presses Ctrl+B
     ↓
1. Create operation: addMark("bold", from=6, to=11)
     ↓
2. Apply to model → text run splits:
   ["Hello ", "world" (bold), "!"]
     ↓
3. Repaint the affected line → "world" is painted with bold glyphs
     ↓
4. Toolbar "Bold" button updates to show active/pressed state
     ↓
5. Send operation to server → broadcast to collaborators

6.3 Error and Retry Flow

WebSocket disconnects: Show "Reconnecting..." banner. Buffer local operations in an offline queue. On reconnect, resync with server (fetch missed operations, rebase local operations on top).
Operation rejected by server: If the server rejects an operation (schema violation, permission issue), rollback the local model to the last confirmed state. Show error toast.
Document save fails: Show "Unable to save — retrying..." banner. Auto-retry with exponential backoff. Keep buffer of unsaved operations.
Image upload fails: Show error overlay on the image with retry button. Don't block editing — user can continue typing.
Conflict during reconnect: If the user edited extensively offline and reconnects, the OT/CRDT engine rebases all local operations against the server's current state. If this produces unexpected content, the user can use undo or version history to recover.

7. Data Modelling (Frontend Perspective)

7.1 Core Data Entities

Document — the top-level entity: metadata + content tree.
Node — a single element in the document tree (paragraph, heading, text, image, table, etc.).
Mark — an inline formatting annotation on a text node (bold, italic, link, etc.).
Operation — a single atomic change to the document (insert, delete, format).
Comment — a comment anchored to a text range, with replies.
Collaborator — a remote user with cursor position, selection, and presence.

7.2 Data Shape

// Document metadata
type DocumentMeta = {
  id: string;
  title: string;
  ownerId: string;
  createdAt: string;
  updatedAt: string;
  permission: 'viewer' | 'commenter' | 'editor';
  collaborators: CollaboratorInfo[];
};

// Document content (the tree model)
type DocumentContent = {
  type: 'doc';
  content: BlockNode[];
};

// Block node types
type BlockNode =
  | ParagraphNode
  | HeadingNode
  | BulletListNode
  | OrderedListNode
  | ListItemNode
  | CodeBlockNode
  | BlockquoteNode
  | TableNode
  | ImageNode
  | HorizontalRuleNode;

type ParagraphNode = {
  type: 'paragraph';
  content: InlineNode[];
};

type HeadingNode = {
  type: 'heading';
  attrs: { level: 1 | 2 | 3 | 4 | 5 | 6 };
  content: InlineNode[];
};

// Inline node types
type InlineNode = TextNode | HardBreakNode;

type TextNode = {
  type: 'text';
  text: string;
  marks: Mark[];
};

// Marks (inline formatting)
type Mark =
  | { type: 'bold' }
  | { type: 'italic' }
  | { type: 'underline' }
  | { type: 'strikethrough' }
  | { type: 'code' }
  | { type: 'link'; attrs: { href: string; title?: string } }
  | { type: 'textColor'; attrs: { color: string } }
  | { type: 'highlight'; attrs: { color: string } }
  | { type: 'comment'; attrs: { commentId: string } };

// Operations (for OT)
type Operation =
  | { type: 'retain'; count: number }
  | { type: 'insert'; text: string; marks?: Mark[] }
  | { type: 'delete'; count: number }
  | { type: 'insertNode'; node: BlockNode }
  | { type: 'deleteNode'; count: number }
  | { type: 'addMark'; from: number; to: number; mark: Mark }
  | { type: 'removeMark'; from: number; to: number; mark: Mark }
  | { type: 'setBlockType'; pos: number; type: string; attrs?: Record<string, any> };

// Collaborator presence
type CollaboratorPresence = {
  userId: string;
  name: string;
  color: string;         // unique color per user
  avatar: string;        // avatar URL for the presence chip / cursor label
  cursor: number | null; // model position
  selection: { anchor: number; head: number } | null;
  status: 'active' | 'idle' | 'away';
  isTyping: boolean;     // show a "typing…" indicator on the cursor label
  lastActive: number;    // timestamp
};

// Comment
type Comment = {
  id: string;
  author: { id: string; name: string; avatar: string };
  text: string;
  anchor: { from: number; to: number }; // position in document model
  createdAt: string;
  resolved: boolean;
  replies: CommentReply[];
};

type CommentReply = {
  id: string;
  author: { id: string; name: string; avatar: string };
  text: string;
  createdAt: string;
};

7.3 Entity Relationships

One-to-Many: One Document → many BlockNode items (content tree).
One-to-Many: One TextNode → many Mark items (inline formatting).
One-to-Many: One Document → many Comment items.
One-to-Many: One Comment → many CommentReply items.
Many-to-Many: Comment.anchor references a range of document positions — as the document changes, these anchors must be remapped.
Nested: Table → TableRow → TableCell → Block[] (cells contain sub-documents).

Normalized vs Denormalized:
The document content is a denormalized tree (each node contains its children inline). This is necessary because the tree structure IS the content — you need the full tree to render the document. There's no benefit to normalizing it.

Collaborator presence is stored in a flat Map keyed by userId — it's ephemeral and frequently updated.

7.4 UI Specific Data Models

// Toolbar state (derived from current selection)
type ToolbarState = {
  isBold: boolean;
  isItalic: boolean;
  isUnderline: boolean;
  isStrikethrough: boolean;
  isCode: boolean;
  currentBlockType: string;     // "paragraph", "heading", etc.
  headingLevel: number | null;
  textAlign: string;
  fontFamily: string;
  fontSize: number;
  textColor: string;
  highlightColor: string;
  isLink: boolean;
  linkHref: string | null;
  canUndo: boolean;
  canRedo: boolean;
  listType: 'bullet' | 'ordered' | 'checklist' | null;
};

// Derived from the document model + current selection, recomputed on every selection change.

// Editor viewport state (for large document optimization)
type ViewportState = {
  scrollTop: number;
  visibleBlockRange: { start: number; end: number }; // which blocks are in the viewport
};

8. State Management Strategy

8.1 State Classification

State Type	Examples	Storage
Document State	Content tree (all nodes, marks)	Editor core (in-memory); synced via OT/CRDT
Collaboration State	Connected users, their cursors/selections	In-memory Map; updated via WebSocket
Editor UI State	Active tool, toolbar state, open dialog	Derived from selection + local `useState`
Comment State	Comment threads linked to document ranges	Server-fetched; React Query cache
Component Local State	Dropdown open, search input value	`useState` / `useReducer`
Derived State	Toolbar active states, word count, outline	Computed from document model + selection

8.2 State Ownership

EditorCore (custom class, not React) owns the document model, selection, and undo history. It is the single source of truth for document content. React components read from it but never directly mutate it.
CollaborationProvider (React context) owns the WebSocket connection, OT client, and presence state. It listens for remote operations and feeds them into the EditorCore.
Toolbar derives its state from the EditorCore's current selection. When the user clicks a format button, Toolbar dispatches a formatting operation to the EditorCore.
CommentSidebar manages comment data via React Query (server-fetched). Comment anchors are stored as document positions and remapped when the document changes.

Data flow:

Input event → EditorCore.applyOperation() → Model updated
     ↓
EditorCore emits "change" event
     ↓
Content canvas repaints the dirty region; React chrome (toolbar, overlays)
re-renders via subscription (useEditorState hook); a11y mirror synced
     ↓
CollaborationProvider sends operation to server
     ↓
Server transforms + broadcasts
     ↓
CollaborationProvider receives remote op → EditorCore.applyRemoteOperation()
     ↓
Model updated → canvas repaints dirty region + a11y mirror synced; React chrome updates

8.3 Persistence Strategy

Data	Persistence	Reason
Document content	Server-synced via OT/CRDT + periodic snapshots	Authoritative server state; collaboration requires it
Pending operations (offline)	In-memory buffer; IndexedDB for crash recovery	Preserve user work if tab closes before sync
User cursor/selection	WebSocket (ephemeral)	Only relevant while connected
Comments	Server via REST API	Persistent, shared across sessions
Document metadata	Server via REST API	Title, permissions, last modified
Editor preferences (font zoom, spell check)	localStorage	Per-user, per-device
Version history	Server	Complete change history

9. Real Time Collaboration Deep Dive

This is the most technically distinctive aspect of Google Docs. The problem: how do N users edit the same document simultaneously without losing anyone's work, without locking any region, and with sub-second propagation of every edit?

9.1 The Fundamental Problem of Concurrent Editing

Initial document: "ABCD"   (indices: A=0, B=1, C=2, D=3)

User A (New York) inserts "X" at index 1.
User B (London)   deletes the character at index 2  (the "C").

Neither has seen the other's edit, so BOTH ops are based on "ABCD".

Naively applying the RAW operations (no transformation) in different orders
DIVERGES — the same raw index means different things after a concurrent edit:

  Order 1 — A then B (B's raw op = "delete index 2"):
    "ABCD"  → apply A (insert X at 1) → "AXBCD"
    "AXBCD" → delete index 2          → deletes "B" → "AXCD"   ✗ (B meant to delete "C")

  Order 2 — B then A (A's raw op = "insert X at index 1"):
    "ABCD"  → apply B (delete index 2) → "ABD"
    "ABD"   → insert X at index 1      → "AXBD"

  Result: "AXCD" ≠ "AXBD"  →  DIVERGENCE. The two clients no longer agree.

A second flavor of divergence: two inserts at the SAME position.
  User A inserts "X" at index 2, User B inserts "Y" at index 2.
  Without a deterministic tie-break rule, one client yields "...XY..." and the
  other "...YX...". → DIVERGENCE again.

The fundamental requirement: all clients must converge to the same document state, regardless of the order operations are received.

Two algorithms solve this: Operational Transformation (OT) and CRDTs (Conflict-free Replicated Data Types).

9.2 Operational Transformation (OT)

OT is the algorithm used by the original Google Docs (and Google Wave before it). The core idea: when you receive a remote operation, transform it against any local operations that the remote user hasn't seen yet, so that the transformed operation produces the correct result in your local context.

9.2.1 What is an Operation

An operation is a sequence of components that walk through the document from start to end:

type OTOperation = OTComponent[];

type OTComponent =
  | { type: 'retain'; count: number }    // skip N characters (no change)
  | { type: 'insert'; text: string }     // insert text at current position
  | { type: 'delete'; count: number };   // delete N characters at current position

In classic text OT (the model used here), every operation must exactly span the entire document length. This "total span" invariant is specific to the flat retain/insert/delete representation — other OT formulations (e.g. tree/JSON OT, or index-addressed operations) drop it and address positions directly. We use the total-span form because it makes the transform function clean to reason about.

Example: Document is "HELLO" (length 5). User inserts "X" at position 2:

Operation: [
  { type: 'retain', count: 2 },   // skip "HE"
  { type: 'insert', text: 'X' },  // insert "X" → now "HEXLLO"
  { type: 'retain', count: 3 },   // skip "LLO"
]
// Input length: 5 (2 + 3 retained)
// Output length: 6 (2 retained + 1 inserted + 3 retained)

Example: Delete character at position 3 from "HELLO":

Operation: [
  { type: 'retain', count: 3 },   // skip "HEL"
  { type: 'delete', count: 1 },   // delete "L"
  { type: 'retain', count: 1 },   // skip "O"
]
// Input length: 5 (3 + 1 + 1)
// Output length: 4 (3 retained + 1 retained, 1 deleted)

9.2.2 The Transform Function

The transform function is the heart of OT. Given two concurrent operations A and B (both based on the same document state), transform produces A' and B' such that:

apply(apply(doc, A), B') === apply(apply(doc, B), A')

This is the convergence property — no matter what order the operations are applied, the result is the same.

        doc
       /   \
      A     B
     /       \
  docA      docB
     \       /
      B'   A'
       \   /
       docAB  ===  docBA

Transform(Insert, Insert)

Document: "AB"
User A: insert "X" at position 1 → [retain(1), insert("X"), retain(1)]
User B: insert "Y" at position 1 → [retain(1), insert("Y"), retain(1)]

Both are concurrent (based on "AB").

Transform result:
  A' = [retain(1), insert("X"), retain(2)]  // retain 2 because Y was inserted
  B' = [retain(2), insert("Y"), retain(1)]  // retain 2 because X was inserted

Apply A then B':
  "AB" → "AXAB" ... wait, that's wrong.

Let's trace more carefully:
  "AB" → apply A → "AXB" (insert X at 1)
  "AXB" → apply B' → B' needs to account for X being inserted before Y's position
  B' = [retain(2), insert("Y"), retain(1)]
  "AXB" → retain 2 ("AX") → insert "Y" → retain 1 ("B") → "AXYB"

Apply B then A':
  "AB" → apply B → "AYB" (insert Y at 1)
  "AYB" → apply A' → A' = [retain(1), insert("X"), retain(2)]
  "AYB" → retain 1 ("A") → insert "X" → retain 2 ("YB") → "AXYB"

Both paths → "AXYB" ✅ CONVERGED!

Tie-breaking rule: when two inserts happen at the same position, the server decides who goes first (usually by user ID or timestamp). This ensures deterministic ordering.

Transform(Insert, Delete)

Document: "ABCD"
User A: insert "X" at position 1 → [retain(1), insert("X"), retain(3)]
User B: delete at position 2       → [retain(2), delete(1), retain(1)]

Transform:
  A' against B: B deleted at position 2. A inserts at position 1 (before the delete).
    A's position is unaffected. But the document is now shorter (3 chars).
    A' = [retain(1), insert("X"), retain(2)]  // retain 2 instead of 3 (one char deleted)

  B' against A: A inserted at position 1. B deletes at position 2, but since A's insert
    shifted everything after position 1 to the right by 1, B's delete position becomes 3.
    B' = [retain(3), delete(1), retain(1)]

Apply A then B':
  "ABCD" → A → "AXBCD" → B' → retain 3 ("AXB"), delete 1 ("C"), retain 1 ("D") → "AXBD"

Apply B then A':
  "ABCD" → B → "ABD" → A' → retain 1 ("A"), insert "X", retain 2 ("BD") → "AXBD"

Both → "AXBD" ✅ CONVERGED!

Transform Implementation

function transform(
  opA: OTComponent[],
  opB: OTComponent[],
  priority: 'left' | 'right' = 'left' // tie-breaker for same-position inserts
): [OTComponent[], OTComponent[]] {
  const aPrime: OTComponent[] = [];
  const bPrime: OTComponent[] = [];

  let indexA = 0;
  let indexB = 0;
  let compA = opA[indexA];
  let compB = opB[indexB];

  while (indexA < opA.length || indexB < opB.length) {
    // Case 1: A is inserting (inserts don't consume input, so B must account for them)
    if (compA && compA.type === 'insert') {
      aPrime.push(compA);
      bPrime.push({ type: 'retain', count: compA.text.length });
      compA = opA[++indexA];
      continue;
    }

    // Case 2: B is inserting
    if (compB && compB.type === 'insert') {
      bPrime.push(compB);
      aPrime.push({ type: 'retain', count: compB.text.length });
      compB = opB[++indexB];
      continue;
    }

    // Case 3: Both retain
    if (compA?.type === 'retain' && compB?.type === 'retain') {
      const len = Math.min(compA.count, compB.count);
      aPrime.push({ type: 'retain', count: len });
      bPrime.push({ type: 'retain', count: len });
      // Consume min length from both
      compA = consumeComponent(compA, len, opA, indexA);
      compB = consumeComponent(compB, len, opB, indexB);
      if (compA?.count === 0) compA = opA[++indexA];
      if (compB?.count === 0) compB = opB[++indexB];
      continue;
    }

    // Case 4: A retains, B deletes
    if (compA?.type === 'retain' && compB?.type === 'delete') {
      const len = Math.min(compA.count, compB.count);
      bPrime.push({ type: 'delete', count: len });
      // A's retain is consumed by B's delete — nothing added to aPrime for this range
      compA = { ...compA, count: compA.count - len };
      compB = { ...compB, count: compB.count - len };
      if (compA.count === 0) compA = opA[++indexA];
      if (compB.count === 0) compB = opB[++indexB];
      continue;
    }

    // Case 5: A deletes, B retains (symmetric to case 4)
    if (compA?.type === 'delete' && compB?.type === 'retain') {
      const len = Math.min(compA.count, compB.count);
      aPrime.push({ type: 'delete', count: len });
      compA = { ...compA, count: compA.count - len };
      compB = { ...compB, count: compB.count - len };
      if (compA.count === 0) compA = opA[++indexA];
      if (compB.count === 0) compB = opB[++indexB];
      continue;
    }

    // Case 6: Both delete at the same position — they cancel each other
    if (compA?.type === 'delete' && compB?.type === 'delete') {
      const len = Math.min(compA.count, compB.count);
      compA = { ...compA, count: compA.count - len };
      compB = { ...compB, count: compB.count - len };
      if (compA.count === 0) compA = opA[++indexA];
      if (compB.count === 0) compB = opB[++indexB];
      continue;
    }

    break; // shouldn't reach here if operations are valid
  }

  return [aPrime, bPrime];
}

9.2.3 OT with a Central Server

Google Docs uses a central server model for OT. The server is the single source of truth and assigns a linear order to all operations (a revision number):

┌────────────┐                ┌────────────────┐                ┌────────────┐
│  Client A   │                │  Server         │                │  Client B   │
│  (rev 5)    │                │  (rev 5)        │                │  (rev 5)    │
└─────┬──────┘                └───────┬────────┘                └─────┬──────┘
      │                                │                                │
      │  op_A (based on rev 5)         │                                │
      │─────────────────────────────►│                                │
      │                                │  op_B (based on rev 5)         │
      │                                │◄──────────────────────────────│
      │                                │                                │
      │                    Server receives op_A first:                  │
      │                    1. Apply op_A → rev 6                        │
      │                    2. Broadcast op_A to Client B                │
      │                                │                                │
      │                    Server receives op_B (based on rev 5):       │
      │                    3. Transform op_B against op_A               │
      │                       → op_B' (now based on rev 6)             │
      │                    4. Apply op_B' → rev 7                       │
      │                    5. Broadcast op_B' to Client A               │
      │                                │                                │
      │  ack(rev 6) ← confirm op_A    │                                │
      │◄─────────────────────────────│                                │
      │                                │  op_A (broadcast to B)         │
      │                                │──────────────────────────────►│
      │  op_B' (transformed)           │                                │
      │◄─────────────────────────────│                                │
      │                                │  ack(rev 7) ← confirm op_B'   │
      │                                │──────────────────────────────►│

Key properties of server-based OT:

The server always has the authoritative document state.
Each operation is assigned a monotonically increasing revision number.
Operations from clients carry the revision they're based on. If it's not the latest, the server transforms them.
Clients receive either acknowledgments (for their own ops) or remote operations (from others).

9.2.4 Complete OT Client Implementation

The OT client is a state machine with three states:

┌──────────────────────┐
│   SYNCHRONIZED       │  Client is in sync with server.
│   (no pending ops)   │  Local revision === server revision.
└──────────┬───────────┘
           │ User edits locally
           ▼
┌──────────────────────┐
│   AWAITING_CONFIRM   │  Client has sent an operation to server.
│   (op in flight)     │  Waiting for acknowledgment.
└──────────┬───────────┘
           │ User edits again before ack arrives
           ▼
┌──────────────────────┐
│   AWAITING_WITH_     │  Client has sent one op AND has a
│   BUFFER             │  second op buffered locally.
│   (op in flight +    │  When ack arrives, buffer is sent.
│    buffered op)      │
└──────────────────────┘

type ClientState =
  | { type: 'synchronized' }
  | { type: 'awaitingConfirm'; outstanding: OTOperation }
  | { type: 'awaitingWithBuffer'; outstanding: OTOperation; buffer: OTOperation };

class OTClient {
  private state: ClientState = { type: 'synchronized' };
  private revision: number;
  private doc: string; // simplified — real system uses document model

  constructor(
    private transport: WebSocketTransport,
    initialDoc: string,
    initialRevision: number
  ) {
    this.doc = initialDoc;
    this.revision = initialRevision;

    // Listen for server messages
    transport.on('ack', () => this.handleAck());
    transport.on('operation', (op: OTOperation) => this.handleRemoteOp(op));
  }

  // User made a local edit — apply it and send/buffer
  applyLocal(operation: OTOperation) {
    // Apply to local document immediately (instant feedback)
    this.doc = applyOperation(this.doc, operation);

    switch (this.state.type) {
      case 'synchronized':
        // No pending ops — send directly
        this.transport.send({ op: operation, revision: this.revision });
        this.state = { type: 'awaitingConfirm', outstanding: operation };
        break;

      case 'awaitingConfirm':
        // Already have one op in flight — buffer this one
        this.state = {
          type: 'awaitingWithBuffer',
          outstanding: this.state.outstanding,
          buffer: operation,
        };
        break;

      case 'awaitingWithBuffer':
        // Already buffering — compose the new op with the buffer
        this.state = {
          ...this.state,
          buffer: compose(this.state.buffer, operation),
        };
        break;
    }
  }

  // Server acknowledged our operation
  private handleAck() {
    this.revision++;

    switch (this.state.type) {
      case 'awaitingConfirm':
        // Our op is confirmed — back to synchronized
        this.state = { type: 'synchronized' };
        break;

      case 'awaitingWithBuffer':
        // Our outstanding op is confirmed — send the buffer
        this.transport.send({ op: this.state.buffer, revision: this.revision });
        this.state = {
          type: 'awaitingConfirm',
          outstanding: this.state.buffer,
        };
        break;

      default:
        throw new Error('Received ack in unexpected state');
    }
  }

  // Received a remote operation from another user
  private handleRemoteOp(serverOp: OTOperation) {
    this.revision++;

    switch (this.state.type) {
      case 'synchronized':
        // No local pending ops — apply server op directly
        this.doc = applyOperation(this.doc, serverOp);
        this.emitChange();
        break;

      case 'awaitingConfirm': {
        // Transform server op against our outstanding op
        const [outstandingPrime, serverOpPrime] = transform(
          this.state.outstanding,
          serverOp
        );
        this.state = { type: 'awaitingConfirm', outstanding: outstandingPrime };
        this.doc = applyOperation(this.doc, serverOpPrime);
        this.emitChange();
        break;
      }

      case 'awaitingWithBuffer': {
        // Transform against outstanding, then against buffer
        const [outstandingPrime, serverOp1] = transform(
          this.state.outstanding,
          serverOp
        );
        const [bufferPrime, serverOp2] = transform(this.state.buffer, serverOp1);

        this.state = {
          type: 'awaitingWithBuffer',
          outstanding: outstandingPrime,
          buffer: bufferPrime,
        };
        this.doc = applyOperation(this.doc, serverOp2);
        this.emitChange();
        break;
      }
    }
  }
}

Why Three States?

Q: Why not just send every operation immediately?

A: If we send op1 and then immediately send op2 (before op1 is acknowledged),
   the server might process op2 before op1 (network reordering), or transform
   op2 against a different base than expected. The three-state design ensures:

   1. Only ONE operation is in flight at a time.
   2. Additional edits are buffered and composed.
   3. After ack, the buffer is sent as the next operation.

   This guarantees correct ordering and transformation.

State Machine Visualization

                    ┌──────────────┐
               ┌───►│ SYNCHRONIZED │◄──────┐
               │    └──────┬───────┘       │
               │           │ local edit    │ ack (no buffer)
               │           ▼               │
               │    ┌──────────────────┐   │
               │    │ AWAITING_CONFIRM │───┘
               │    └──────┬───────────┘
               │           │ local edit
               │           ▼
               │    ┌──────────────────────┐
               │    │ AWAITING_WITH_BUFFER │◄─┐
               │    └──────┬───────────────┘  │
               │           │ ack              │ local edit
               │           │ (send buffer)    │ (compose into buffer)
               │           ▼                  │
               │    ┌──────────────────┐      │
               └────│ AWAITING_CONFIRM │──────┘
                    └──────────────────┘

9.2.5 Server Side OT Orchestration

The server maintains the canonical operation log — an ordered list of all operations, each with a revision number:

// Simplified server-side OT handler
class OTServer {
  private operations: OTOperation[] = [];  // canonical operation log
  private document: string;                // current document state

  handleClientOperation(clientOp: OTOperation, clientRevision: number, clientId: string) {
    // Client's operation is based on revision `clientRevision`.
    // Server's current revision is `this.operations.length`.
    // Transform the client's op against all ops it has missed.

    let transformedOp = clientOp;

    for (let i = clientRevision; i < this.operations.length; i++) {
      const [, serverOpTransformed] = transform(this.operations[i], transformedOp);
      transformedOp = serverOpTransformed;
      // Note: we need the second output (transformedOp adjusted for the server op)
    }

    // Apply the fully transformed operation
    this.document = applyOperation(this.document, transformedOp);
    this.operations.push(transformedOp);

    // Send ack to the author
    this.send(clientId, { type: 'ack' });

    // Broadcast to all other clients
    this.broadcast(clientId, { type: 'operation', op: transformedOp });
  }
}

9.3 CRDTs (Conflict Free Replicated Data Types)

CRDTs are an alternative to OT that is gaining popularity for real-time collaboration. Unlike OT (which transforms operations), CRDTs design the data structure itself so that concurrent edits automatically converge without transformation.

9.3.1 How CRDTs Differ from OT

Aspect	OT	CRDT
Core idea	Transform operations against each other to account for concurrency	Design data types that mathematically guarantee convergence
Server requirement	Central server is needed to order operations	No central server needed (peer-to-peer works)
Operation complexity	Operations are simple (insert, delete). Transform function is complex.	Operations are simple. Data structure carries unique IDs and metadata.
Metadata overhead	Minimal — operations are lightweight	Each character may carry a unique ID (increased memory)
Deletion	Physical deletion (character is removed)	Tombstoning (deleted characters are marked, not removed)
Used by	Google Docs, Google Wave	Yjs, Automerge, Apple Notes, Figma (for some features)
Undo complexity	Complex (must invert and transform against concurrent ops)	Complex (must track causal history)
Offline support	Limited (requires server for transformation)	Excellent (edits can be merged peer-to-peer on reconnect)

9.3.2 Sequence CRDTs for Text (Yjs Example)

For text editing, we need a sequence CRDT — a data structure where elements (characters) can be inserted and deleted at any position, and concurrent operations always produce the same result on all replicas.

There is a whole family of sequence-CRDT algorithms; naming a couple signals depth in an interview:

Algorithm	Positioning idea	Notes
RGA (Replicated Growable Array)	Each element points to the id it was inserted after; concurrent inserts at the same spot are ordered by id	Used inside Yjs/Automerge-style engines; tombstones on delete
YATA (Yjs)	Like RGA but tracks both left/right origins; conflict resolution by client id	The algorithm Yjs implements; very fast in practice
Logoot / LSEQ	Each element gets a dense, unbounded fractional position identifier between its neighbors	No tombstones for ordering, but identifiers can grow; LSEQ adaptively allocates to bound growth
Treedoc	Positions are paths in a binary tree	Elegant, but rebalancing is tricky
Automerge	Columnar RGA-based document CRDT	Great for local-first/offline; higher memory overhead

The rest of this section uses Yjs (YATA) as the concrete example. The key insight across all of them: instead of using index positions (which shift when characters are inserted/deleted by others), each character gets a globally unique ID that never changes.

How Yjs Represents Text

Traditional text: "HELLO"
  index:           0 1 2 3 4
  Problem: if User B inserts at index 2, all indices after 2 change.

CRDT text (Yjs): "HELLO"
  Each character has a unique, stable identifier:
    'H' → { id: (clientA, clock=0) }
    'E' → { id: (clientA, clock=1) }
    'L' → { id: (clientA, clock=2) }
    'L' → { id: (clientA, clock=3) }
    'O' → { id: (clientA, clock=4) }

  Insert "X" between "E" and "L":
    New item: { id: (clientB, clock=0), content: 'X', origin: (clientA, clock=1) }
    Result: H E X L L O
    No index shifting — X is positioned by its relationship to "E" (its origin).

Concurrent Insert Resolution

Document: "AB"
User A inserts "X" between A and B:
  { id: (A, 0), content: 'X', originLeft: idOfA, originRight: idOfB }

User B inserts "Y" between A and B:
  { id: (B, 0), content: 'Y', originLeft: idOfA, originRight: idOfB }

Both X and Y are between A and B. Which goes first?

CRDT resolution rule: compare client IDs.
  If clientA < clientB → X comes before Y: "AXYB"
  This is deterministic — all clients produce the same result.

No transformation needed. Just insert both items and let the CRDT's ordering rules sort them.

9.3.3 CRDT Integration with Editor

Using Yjs with a ProseMirror-based editor:

import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';
import { ySyncPlugin, yCursorPlugin, yUndoPlugin } from 'y-prosemirror';

function setupCollaborativeEditor(docId: string) {
  // Create a Yjs document
  const ydoc = new Y.Doc();

  // The document content is a Yjs XML Fragment (maps to ProseMirror's document model)
  const yxml = ydoc.getXmlFragment('prosemirror');

  // WebSocket provider for real-time sync
  const provider = new WebsocketProvider(
    'wss://collab.example.com',
    docId,
    ydoc
  );

  // Set user awareness (cursor, selection, name, color)
  provider.awareness.setLocalStateField('user', {
    name: currentUser.name,
    color: currentUser.color,
    cursor: null,
  });

  // Create ProseMirror editor with Yjs plugins
  const editor = new EditorView(document.getElementById('editor'), {
    state: EditorState.create({
      schema: editorSchema,
      plugins: [
        // Syncs ProseMirror's document model with the Yjs CRDT
        ySyncPlugin(yxml),
        // Shows remote cursors and selections
        yCursorPlugin(provider.awareness),
        // Wires undo/redo to Yjs's undo manager (not ProseMirror's default)
        yUndoPlugin(),
        // ... other plugins (keymap, input rules, etc.)
      ],
    }),
  });

  return { editor, ydoc, provider };
}

How the sync plugin works:

User types in ProseMirror → ProseMirror creates a transaction.
ySyncPlugin intercepts the transaction and converts it to Yjs operations on yxml.
Yjs propagates the changes to the WebsocketProvider.
Provider sends the changes to the server → server relays to other clients.
Other clients' Yjs instances receive changes → ySyncPlugin converts them to ProseMirror transactions → editor updates.

9.4 OT vs CRDT Comparison

Criterion	OT (Google Docs approach)	CRDT (Yjs / Automerge approach)
Convergence guarantee	Requires correct transform function (hard to prove, easy to have bugs)	Mathematically guaranteed by the data type design
Central server	Required (assigns operation order)	Optional (works peer-to-peer)
Offline support	Weak — must sync through server	Strong — merge locally, sync when online
Memory overhead	Low — operations are lightweight	Higher — each character carries metadata (unique ID, tombstones)
Large documents	Efficient (operations on a flat string)	Can be slower (tree traversal for large CRDT structures)
Undo/redo	Complex but well-understood	Very complex (must track causal dependencies)
Maturity	20+ years (Google Wave in 2009)	10+ years (academic); Yjs mature since ~2019
Implementation effort	High (correct transform functions are subtle)	Moderate (use a library like Yjs)
Best for	Centralized apps (Google Docs, Notion)	Decentralized/local-first apps (Excalidraw, linear, some Figma features)

For Google Docs specifically, OT is the right choice:

Google already has robust server infrastructure.
OT has lower memory overhead (important for 100-page documents).
Server-authoritative model enables features like version history, permission enforcement, and server-side spell check.

For a startup building a collaborative editor, CRDT (via Yjs) is often the practical choice:

Much easier to implement correctly (just use the library).
Better offline support out of the box.
No need for a complex OT server.

9.5 Cursor and Selection Presence

Each collaborator's cursor position and selection must be visible to all other users in real time.

How Cursor Positions Are Shared

User A types → cursor at model position 42
     ↓
Client A sends presence update via WebSocket:
  { userId: "A", cursor: 42, selection: null, name: "Alice", color: "#e06666" }
     ↓
Server relays to all other clients
     ↓
Client B receives → renders Alice's cursor at position 42 with a colored flag

How Cursor Positions Survive Edits

When a remote operation changes the document, all cursor positions might shift. We must map cursor positions through the operation:

User B's cursor is at position 10.
User A inserts 5 characters at position 3.

User B's cursor should now be at position 15 (shifted right by 5).

Mapping function:
  newPosition = mapPositionThroughOperation(oldPosition, operation)

function mapPosition(pos: number, operation: OTComponent[]): number {
  let currentPos = 0;
  let newPos = pos;

  for (const comp of operation) {
    if (currentPos >= pos) break;

    switch (comp.type) {
      case 'retain':
        currentPos += comp.count;
        break;

      case 'insert':
        // Insert happened before our position — shift right
        if (currentPos <= pos) {
          newPos += comp.text.length;
        }
        break;

      case 'delete':
        // Delete happened before our position — shift left
        const deleteEnd = currentPos + comp.count;
        if (deleteEnd <= pos) {
          newPos -= comp.count;
        } else if (currentPos <= pos && deleteEnd > pos) {
          // Our cursor was inside the deleted range — move to start of deletion
          newPos = currentPos;
        }
        currentPos += comp.count;
        break;
    }
  }

  return Math.max(0, newPos);
}

Rendering Remote Cursors

Remote cursors and selections are drawn on a transparent overlay that sits on top of the content canvas. Two common implementations: (a) paint them directly onto a second overlay <canvas> layered above the content canvas, or (b) render lightweight absolutely-positioned DOM chips (shown below — easy to add hover tooltips / name labels). Either way, the pixel position comes from the layout geometry map (positionToPixel), not from the DOM — because the content itself has no DOM nodes to anchor to.

// DOM-overlay variant (chips positioned from the geometry map)
function CursorOverlay({ collaborators }: { collaborators: CollaboratorPresence[] }) {
  return (
    <>
      {collaborators.map((collab) => {
        if (collab.cursor == null) return null;

        // Convert model position to pixel coordinates via the layout geometry map
        const coords = geometryMap.positionToPixel(collab.cursor);
        if (!coords) return null; // off-screen (outside painted viewport)

        return (
          <div key={collab.userId} className="remote-cursor" style={{
            position: 'absolute',
            left: coords.left,
            top: coords.top,
            pointerEvents: 'none',
          }}>
            {/* Blinking cursor line */}
            <div style={{
              width: 2,
              height: coords.lineHeight,
              backgroundColor: collab.color,
            }} />

            {/* Name label */}
            <div style={{
              backgroundColor: collab.color,
              color: 'white',
              fontSize: 11,
              padding: '1px 4px',
              borderRadius: 3,
              whiteSpace: 'nowrap',
              transform: 'translateY(-100%)',
            }}>
              {collab.name}
            </div>
          </div>
        );
      })}
    </>
  );
}

Remote Selection Highlighting

When a collaborator selects a range of text, the selection is painted as a set of semi-transparent colored rectangles behind the glyphs. With canvas rendering we compute those rectangles from the layout geometry map (there is no DOM Range to query):

// Convert a model range (anchor, head) to visual rectangles using the geometry map.
// A multi-line selection produces one rect per line it spans.
function getSelectionRects(from: number, to: number): Rect[] {
  const rects: Rect[] = [];
  // The layout engine knows, per line, the pixel box for any sub-range on that line.
  for (const line of geometryMap.linesInRange(from, to)) {
    const start = Math.max(from, line.from);
    const end = Math.min(to, line.to);
    rects.push(geometryMap.rangeToRect(start, end)); // { x, y, width, height }
  }
  return rects;
}

// Painted on the overlay canvas:
for (const rect of getSelectionRects(anchor, head)) {
  ctx.fillStyle = withAlpha(collab.color, 0.25);
  ctx.fillRect(rect.x, rect.y, rect.width, rect.height);
}

9.6 WebSocket Transport Layer

A production collaboration socket is more than "connect and send." Interviewers expect these connection-management concerns:

Heartbeat (ping/pong) — send a periodic ping (e.g. every 20–30s); if no pong arrives within a timeout, treat the connection as dead and reconnect. This detects half-open connections that onclose never fires for.
Reconnect with backoff — exponential backoff with jitter (capped), as implemented below.
Session resume — on reconnect, the client sends its last acknowledged revision number so the server can replay only the operations the client missed, instead of resending the whole document.
Message sequence ids — each message carries a monotonically increasing sequence id so the client can detect gaps/reordering and request a resync, and the server can deduplicate operations replayed after a flaky reconnect (idempotency).

class CollaborationTransport {
  private ws: WebSocket;
  private reconnectAttempts = 0;
  private maxReconnectAttempts = 10;
  private offlineBuffer: OTOperation[] = [];

  connect(docId: string) {
    this.ws = new WebSocket(`wss://collab.example.com/doc/${docId}`);

    this.ws.onopen = () => {
      this.reconnectAttempts = 0;
      // Flush offline buffer
      this.flushOfflineBuffer();
    };

    this.ws.onmessage = (event) => {
      const message = JSON.parse(event.data);
      switch (message.type) {
        case 'ack':
          this.emit('ack');
          break;
        case 'operation':
          this.emit('operation', message.op);
          break;
        case 'presence':
          this.emit('presence', message.data);
          break;
        case 'error':
          this.handleServerError(message);
          break;
      }
    };

    this.ws.onclose = (event) => {
      if (!event.wasClean) {
        this.scheduleReconnect();
      }
    };
  }

  send(operation: OTOperation, revision: number) {
    if (this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify({
        type: 'operation',
        op: operation,
        revision,
      }));
    } else {
      // Offline — buffer the operation
      this.offlineBuffer.push(operation);
    }
  }

  private scheduleReconnect() {
    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
      this.emit('disconnected');
      return;
    }

    const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);
    this.reconnectAttempts++;

    setTimeout(() => {
      this.connect(this.docId);
    }, delay);
  }

  private flushOfflineBuffer() {
    // On reconnect, we need to resync with the server first,
    // then rebase our buffered operations on the latest server state.
    // This is handled by the OT client's state machine.
    for (const op of this.offlineBuffer) {
      this.emit('localBuffered', op);
    }
    this.offlineBuffer = [];
  }
}

9.7 Offline Editing and Reconnection

When the network drops, the user should continue editing seamlessly:

Network drops
     ↓
1. OT client switches to "offline" mode
2. User continues typing — all operations are applied locally and buffered
3. UI shows "Offline — changes will be saved when you reconnect"
     ↓
Network returns
     ↓
4. WebSocket reconnects
5. Client sends: "I'm at revision 42. What have I missed?"
6. Server responds with operations 43, 44, 45, ... (all ops since rev 42)
7. Client transforms its buffered operations against the missed server ops
8. Client sends its rebased operations to the server
9. Server acknowledges → client is back in sync
10. UI shows "All changes saved"

Offline Operation Buffer with IndexedDB

For crash safety, buffered operations are periodically written to IndexedDB:

async function persistOfflineBuffer(buffer: OTOperation[]) {
  const db = await openDB('doc-offline', 1, {
    upgrade(db) {
      db.createObjectStore('operations', { keyPath: 'id', autoIncrement: true });
    }
  });

  const tx = db.transaction('operations', 'readwrite');
  for (const op of buffer) {
    tx.store.put({ op, timestamp: Date.now() });
  }
  await tx.done;
}

If the user closes the tab and reopens later, the buffered operations are loaded from IndexedDB and resynced with the server.

10. Undo Redo in Collaborative Context

Undo/redo in a collaborative editor is much harder than in a single-user editor. The key question: what does "undo" mean when other users have edited the document since your last action?

The Problem

User A types "Hello" at the beginning.
User B types "World" at the end.
User A presses Ctrl+Z (undo).

What should happen?
  Option 1: Undo A's "Hello" → "World" remains. ✅ This is correct.
  Option 2: Undo the LAST operation (B's "World") → wrong! That's B's work.

Undo should only undo YOUR OWN operations, even if other users have since edited the document.

Implementation

class CollaborativeUndoManager {
  private undoStack: OTOperation[] = [];  // inverse of user's own operations
  private redoStack: OTOperation[] = [];

  // When the local user performs an edit
  record(operation: OTOperation) {
    this.undoStack.push(invertOperation(operation));
    this.redoStack = []; // clear redo on new edit
  }

  // When a remote operation arrives, transform undo/redo stacks
  transformStacks(remoteOp: OTOperation) {
    // Transform every entry in the undo stack against the remote op
    this.undoStack = this.undoStack.map((undoOp) => {
      const [transformedUndo] = transform(undoOp, remoteOp);
      return transformedUndo;
    });

    this.redoStack = this.redoStack.map((redoOp) => {
      const [transformedRedo] = transform(redoOp, remoteOp);
      return transformedRedo;
    });
  }

  undo(): OTOperation | null {
    const undoOp = this.undoStack.pop();
    if (!undoOp) return null;

    // Push the inverse (redo version) onto the redo stack
    this.redoStack.push(invertOperation(undoOp));

    // Return the operation to be applied and sent to the server
    return undoOp;
  }

  redo(): OTOperation | null {
    const redoOp = this.redoStack.pop();
    if (!redoOp) return null;

    this.undoStack.push(invertOperation(redoOp));
    return redoOp;
  }
}

Why transform the undo stack?
When User B inserts 5 characters at position 3, all positions in User A's undo stack that are >= 3 must shift right by 5. Without transforming, undoing would delete the wrong characters.

11. High Level API Design (Frontend POV)

11.1 Required APIs

API	Method	Description
`/api/docs/:id`	GET	Fetch document content + metadata
`/api/docs/:id`	PUT	Save document snapshot (periodic, not per-keystroke)
`/api/docs`	POST	Create new document
`/api/docs/:id`	DELETE	Delete document
`wss://collab.example.com/doc/:id`	WebSocket	Real-time operation sync and presence
`/api/docs/:id/comments`	GET	Fetch all comments for a document
`/api/docs/:id/comments`	POST	Add a new comment
`/api/docs/:id/comments/:cid`	PUT	Edit or resolve a comment
`/api/docs/:id/comments/:cid/replies`	POST	Add a reply to a comment thread
`/api/docs/:id/versions`	GET	Fetch version history list
`/api/docs/:id/versions/:vid`	GET	Fetch a specific version snapshot
`/api/docs/:id/media`	POST	Upload an image or file
`/api/docs/:id/export`	POST	Export to PDF, DOCX, HTML

11.2 Request and Response Structure

GET /api/docs/:id

// Response
{
  "id": "doc_abc123",
  "title": "Q4 Project Plan",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": { "level": 1 },
        "content": [{ "type": "text", "text": "Q4 Project Plan" }]
      },
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "This document outlines..." }
        ]
      }
    ]
  },
  "revision": 42,
  "collaborators": [
    { "userId": "u_1", "name": "Zeeshan Ali", "avatar": "...", "color": "#e06666" }
  ],
  "permission": "editor",
  "updatedAt": "2026-03-17T08:00:00Z"
}

WebSocket Messages

// Client → Server: Send operation
{
  "type": "operation",
  "op": [
    { "type": "retain", "count": 42 },
    { "type": "insert", "text": "Hello" },
    { "type": "retain", "count": 100 }
  ],
  "revision": 42
}

// Server → Client: Acknowledge
{
  "type": "ack"
}

// Server → Client: Remote operation
{
  "type": "operation",
  "op": [
    { "type": "retain", "count": 10 },
    { "type": "delete", "count": 5 },
    { "type": "retain", "count": 137 }
  ],
  "userId": "u_2",
  "revision": 43
}

// Client → Server: Presence update
{
  "type": "presence",
  "cursor": 42,
  "selection": { "anchor": 42, "head": 50 }
}

// Server → Client: Remote presence
{
  "type": "presence",
  "userId": "u_2",
  "name": "Ali",
  "color": "#6aa84f",
  "cursor": 78,
  "selection": null
}

11.3 Error Handling and Status Codes

Status	Scenario	Frontend Handling
`200`	Success	Render document
`304`	Not Modified	Use cached version
`400`	Malformed operation	Log error; this indicates a client bug
`401`	Unauthorized	Redirect to sign-in
`403`	No permission (viewer trying to edit)	Show "View only" banner; disable editing
`404`	Document not found	Show "Document not found" error page
`409`	Revision conflict (rare in OT)	Refetch document and resync
`413`	Document/media too large	Show "File too large" error
`429`	Rate limit	Throttle operations; show "Saving paused"
`500`	Server error	Show "Unable to save — retrying" banner
WS `1006`	Abnormal WebSocket close	Auto-reconnect with exponential backoff

12. Caching Strategy

12.1 What to Cache

Document content: The source of truth is the collaboration server. Local state is the "cache" — always in sync via OT/CRDT.
Document metadata (title, permissions): React Query cache, short TTL (1 min).
Comments: React Query cache keyed by document ID. Refetch on focus.
User profiles / avatars: Browser HTTP cache + CDN (long TTL).
Fonts: Service Worker cache (critical for consistent text rendering).
Application bundle: Service Worker cache for offline access.

12.2 Where to Cache

Data	Cache Location	TTL
Document content (active)	In-memory (editor model)	Ephemeral — synced in real time
Offline operation buffer	IndexedDB	Until synced
Comments	React Query in-memory	1 min; refetch on focus
User avatars	Browser HTTP cache + CDN	24h
Fonts	Service Worker cache	Indefinite (immutable filenames)
App shell	Service Worker	Until new version
Editor preferences	localStorage	Indefinite

12.3 Cache Invalidation

Document content: Not cached traditionally — the OT/CRDT system keeps it in sync. On reconnect, the client fetches missed operations.
Comments: Invalidated when a new comment is added (optimistic update + background refetch).
User avatars: Immutable with content-hashed URLs.
App bundle: Service Worker checks for updates; stale-while-revalidate.

13. CDN and Asset Optimization

App delivery: Static HTML + JS + CSS served from CDN. The editor is a heavy bundle (~500KB gzipped), so code splitting is critical.
Font delivery: Custom editor fonts (serif, sans-serif, monospace options) served from CDN with font-display: swap. Preloaded in <head> since they're critical for text rendering.
Image delivery: Uploaded images are stored in a blob service and served via CDN with signed URLs. Responsive sizes via srcset.
Cache headers:
- JS/CSS: Cache-Control: public, max-age=31536000, immutable (content-hashed).
- HTML: Cache-Control: no-cache.
- Fonts: Cache-Control: public, max-age=31536000, immutable.
- API responses: Cache-Control: private, no-cache.
Compression: Brotli for all text-based assets. Document content over WebSocket is also compressed (permessage-deflate).

14. Rendering Strategy

CSR (client-side rendering) only. A minimal static app shell (HTML + JS + CSS) is served from the CDN and boots on the client; the editor chrome renders immediately, then the document model is initialized client-side from the fetched JSON and painted onto the content <canvas>. There's no SSR because:
1. The content changes constantly (collaboration invalidates any server-rendered content instantly).
2. The content is painted on canvas from the model on the client — there is no server-paintable HTML to hydrate.
3. Docs are auth-gated, so there's no SEO benefit to server-rendering content.
4. The editor fetches the structured model JSON regardless (needed to type/undo/apply OT); once it has that, painting the visible viewport is single-digit milliseconds.
Code splitting:
- Core editor + toolbar: main chunk.
- Collaboration module: lazy-loaded on WebSocket connect.
- Comments sidebar: lazy-loaded when user opens comments.
- Export module: lazy-loaded when user opens File → Export.
- Version history: lazy-loaded when user opens the panel.
Viewport painting for large documents: For 100+ page documents, the canvas only paints the blocks intersecting the viewport (+ a buffer above and below). The layout engine still computes total document height (so the scrollbar is correct), but off-screen blocks are laid out lazily/coarsely and never painted until scrolled into view. Because content is pixels, there are no off-screen DOM nodes to manage at all — the DOM stays tiny regardless of document size.

15. Cross Cutting Non Functional Concerns

15.1 Security

Access control: Permission level (viewer/commenter/editor) is enforced on both client and server. The editor UI disables editing for viewers. The server rejects operations from non-editors.
XSS prevention: User-generated content is rendered from the typed document model (not arbitrary HTML). Pasted HTML is sanitized and converted to the model's schema — any script tags, event handlers, or dangerous elements are stripped.
CSRF: All API calls include a CSRF token. WebSocket connection is authenticated via the same session.
Token storage: Auth tokens in HTTP-only cookies. No storage of sensitive data in localStorage.
Content isolation: Documents from different users/orgs are isolated at the API level. The frontend has no access to data outside the current document.
Clipboard sanitization: When pasting from external sources, parse HTML through a whitelist of allowed tags and attributes. Disallow <script>, <iframe>, <form>, on* attributes.

15.2 Accessibility

Because the visible content is a <canvas>, it is opaque to assistive technology — a screen reader sees a single image, not text. Accessibility is therefore driven by a parallel, offscreen "mirror" DOM kept in sync with the document model. This is exactly how real Google Docs supports screen readers with a canvas renderer.

Offscreen accessibility mirror DOM: For the region around the caret (and on demand as the user navigates), the editor generates real semantic HTML from the model — <h1>–<h6>, <p>, <ul>/<ol>/<li>, <a>, <table>/<tr>/<td> — inside an offscreen container marked up as role="document"/role="textbox". The screen reader reads this tree; edits to the model update it. It is visually hidden (not display:none, which would hide it from AT) but exposed to the accessibility tree.
Caret ↔ AT sync: as the painted caret moves, the corresponding node/offset in the mirror DOM is focused/selected so the screen reader announces the right context.
Keyboard navigation:
- Standard keyboard shortcuts: Ctrl+B (bold), Ctrl+I (italic), Ctrl+Z (undo), etc.
- Tab/Shift+Tab in lists for indent/outdent.
- Caret-browsing / arrow-key navigation is fully handled by the editor (the hidden input proxy holds focus).
- Toolbar navigation via Tab + arrow keys (roving tabindex) — the toolbar is ordinary DOM, so it's natively accessible.
Screen reader support:
- Live announcements for collaborator actions: "Alice started editing" (via aria-live="polite").
- Format state announced when the caret moves: "Bold, Heading 2."
- Comment/suggestion markers surfaced through the mirror DOM.
Focus management: When dialogs open (Insert Image, Share), focus is trapped. On close, focus returns to the hidden input proxy so typing resumes.
Color contrast: Toolbar icons, comment text, and status messages meet WCAG AA. Collaborator colors are chosen from an accessible palette. (Note: canvas text bypasses browser high-contrast/forced-colors modes, so the editor must detect forced-colors and repaint with system colors.)

15.3 Performance Optimization

Typing Latency

The most critical performance metric for an editor is input latency — the time from keypress to the character appearing on screen. Target: < 16ms (one frame).

Keypress → beforeinput on hidden input proxy (~0ms)
     ↓
Create operation (~0.1ms)
     ↓
Apply to model (~0.1ms for a single character insert)
     ↓
Re-layout affected line + repaint dirty canvas region (~0.5-1ms)
     ↓
Repaint caret (~0.1ms)
     ↓
Browser composites the canvas (~1-2ms)
     ↓
Total: ~3ms — WELL within 16ms budget ✅

The collaboration layer (send to server, transform, receive) does NOT block the input pipeline. The operation is sent asynchronously after the local repaint completes. The accessibility mirror DOM is also updated off the critical path.

Large Document Optimization

Technique	How it helps
Viewport-only painting	Paint only blocks intersecting the viewport + buffer; off-screen blocks are laid out lazily and never painted. Content is pixels, so there are zero off-screen DOM nodes to manage.
Dirty-region repaint	On a keystroke, `clearRect` + repaint only the affected line's rectangle, not the whole canvas.
Deferred formatting updates	When applying a format change to 100 paragraphs (select all → bold), batch the re-layout + repaint across `requestAnimationFrame` frames.
Incremental layout	After a paste of 10,000 characters, lay out + paint the first viewport immediately, then lay out remaining blocks in subsequent frames.
Debounced toolbar updates	Toolbar state (bold active, heading level) is derived from selection. Debounce derivation to 50ms — fast enough to feel instant, but avoids recomputing on every arrow key press in rapid navigation.
Layout / glyph-measure caches	Cache per-block layout geometry and text-measurement results (font metrics, glyph widths) in a `WeakMap`; invalidate only the blocks that changed. Avoids re-shaping unchanged text.
OffscreenCanvas / layer separation	Keep content on one canvas and the fast-changing caret/selection/remote-cursors on a lightweight overlay canvas, so caret blink and presence updates don't repaint content.

Code Splitting Impact

Chunk	Size (Gzipped)	Load trigger
Core editor + toolbar	~250KB	Initial page load
Collaboration module	~80KB	On WebSocket connect
Export (PDF/DOCX)	~120KB	File → Export click
Comments sidebar	~40KB	Open comments panel
Version history	~50KB	Open version history
Image upload + resize	~30KB	Insert → Image click

15.4 Observability and Reliability

Error Boundaries: Wrap the editor surface, toolbar, and comment sidebar in separate error boundaries. If comments crash, editing continues.
Logging:
- Track keypress-to-screen latency for P95 monitoring.
- Track OT/CRDT operation round-trip time.
- Log WebSocket disconnects, reconnects, and their durations.
- Track "operation rejected" events (indicates client bugs).
Performance monitoring:
- FCP, TTI, and LCP for document page.
- Editor first-interactive time (time from page load to first keystroke accepted).
- Frame rate during continuous typing (should be 60fps).
Feature flags: Gate new editor features:
- New block types (toggleable sections, callout boxes).
- Alternative collaboration engines (OT vs CRDT A/B test).
Graceful degradation:
- If WebSocket fails → switch to periodic HTTP polling (long-poll) for operations.
- If collaboration fails entirely → single-user mode with auto-save via REST.
- If custom rendering fails → fall back to a simplified DOM/contentEditable rendering mode (the lighter-weight approach from §5.2.1) so the user can keep editing without the canvas engine.

16. Edge Cases and Tradeoffs

Edge Case	Handling
Two users type at the exact same position	OT transform function deterministically orders inserts by user ID. Both characters appear, but in a consistent order across all clients.
User pastes 50,000 characters	Parse and insert as a single operation. Render in batches (first viewport immediately, rest deferred). Large pastes may cause a brief freeze — show a progress indicator for pastes > 5,000 chars.
User edits offline for 2 hours	All operations buffered in memory + IndexedDB. On reconnect, rebase buffered ops against server's current state. If the document has diverged significantly, warn the user and let them review the merge.
100+ page document scrolling	Only the blocks intersecting the viewport (+ buffer) are painted to the canvas; the layout engine tracks total height so the scrollbar stays accurate. Off-screen blocks are laid out lazily and never painted. No off-screen DOM exists at all.
Collaborator's cursor is in a deleted paragraph	When User A deletes a paragraph that User B's cursor is in, map B's cursor to the start of the nearest surviving block.
Comment anchor on deleted text	Comments anchored to deleted text become "orphaned." Show them in the sidebar with a note: "The text this comment refers to was deleted." Allow the comment to be resolved or re-anchored.
Browser crash during editing	The last synced revision is on the server. Unsaved local operations (up to debounce interval) may be lost. IndexedDB buffer mitigates this for offline edits.
IME input during collaboration	While composing (e.g., Japanese IME), do not send intermediate states to the server. Only send the final committed text. Remote operations received during composition are queued and applied after composition ends.
Table with 1000s of cells	Virtualize table rendering (only cells in the viewport). Prohibit operations that would create tables larger than a limit (e.g., 500 cells).
Very large number of collaborators (50+)	Throttle presence broadcasts (every 100ms instead of every mouse move). Group cursors that are close together. Cap cursor rendering at 20 visible cursors.
Concurrent undo from different users	Each user's undo stack is independent. User A's undo only reverses A's operations. Remote operations transform the undo stack so it remains valid.

Key Tradeoffs

Decision	Tradeoff
OT over CRDT	Lower memory overhead, server-authoritative (good for permissions/versioning). But requires a central server and complex transform functions. CRDTs would be better for offline-first scenarios.
Custom document model over raw HTML	Clean data, collaboration-friendly, validatable. But requires building a full rendering pipeline and input handler from scratch.
Canvas rendering + parallel DOM (hybrid)	Pixel-perfect, browser-consistent rendering; full control over line breaking, pagination, and large-document performance; no `contentEditable` rendering quirks. But you must build your own layout/paint engine (line breaking, BiDi, ligatures, caret), a hidden input proxy for IME, and an offscreen mirror DOM for accessibility — a large investment. The lighter alternative (DOM + `contentEditable`) gets native IME/selection/spell-check for free but inherits browser inconsistencies.
CSR-only (no SSR)	Simpler architecture, static shell cached on CDN, no hydration/DOM-ownership conflicts with the custom editor engine, and content stays authoritative (fetched live). But slower first meaningful paint of content than SSR, and no SEO — acceptable since docs are auth-gated.
Viewport-only canvas painting	Handles 100+ page documents with stable performance and a tiny DOM. But adds complexity: you own scroll position management, total-height estimation for un-laid-out blocks, and dirty-region tracking.
WebSocket for collaboration	Low-latency bidirectional communication. But requires persistent connections (server resource cost) and reconnection handling. SSE would be simpler but only server→client.
Per-user undo	Correct behavior in collaborative context (undo YOUR changes, not others'). But complex to implement — undo stack must be transformed against every remote operation.
Debounced auto-save (server snapshots)	Reduces server write load. But periodic snapshots mean version history is coarser than operation-level history. Actual operation log is the true history; snapshots are for fast loading.

17. Summary and Future Improvements

Key Architectural Decisions

Custom document model — a typed tree of nodes with inline marks, independent of the DOM. Enables clean serialization, validation, collaboration, and cross-platform rendering.
Operational Transformation (OT) for real-time collaboration — a central server assigns operation order; clients transform concurrent operations. Three-state client machine (synchronized, awaiting confirm, awaiting with buffer) ensures correct ordering.
Hybrid canvas rendering — the document content is painted onto a <canvas> from the model (pixel-perfect, browser-consistent, pagination-friendly), with a parallel DOM layer: a hidden input proxy for keystrokes/IME, native selection/clipboard, and an offscreen mirror DOM so screen readers can read the document. This matches modern Google Docs.
Viewport-only painting for large documents — only the blocks intersecting the viewport are painted; there are no off-screen DOM nodes regardless of document size.
Per-user undo with stack transformation — each user's undo stack is independent and transformed against remote operations.
Auto-save via operation stream — every operation is synced in real time via WebSocket; periodic snapshots provide fast document loading.

Possible Future Enhancements

OffscreenCanvas + Web Worker painting: Move layout and canvas painting into a Web Worker via OffscreenCanvas, keeping the main thread free for input and never dropping a frame during heavy repaints. (Building on the current canvas renderer.)
WebGL / WebGPU text rendering: GPU-accelerated glyph atlases for even faster painting of very large or graphically rich documents.
CRDT migration: Migrate from OT to a CRDT-based system (like Yjs) for better offline support and peer-to-peer collaboration without a central server.
AI-powered features: Real-time grammar suggestions, auto-complete sentences, summarize document, generate content from prompts.
Branching and merging: Git-like document branches where users can make changes in a "branch" and merge them back into the main document with conflict resolution.
Real-time voice/video: Embedded video chat within the document editing session for tighter collaboration.
Plugin / extension system: Allow third-party developers to add custom block types, toolbar actions, and integrations (e.g., embed Figma frames, Jira issues).
Cross-document linking: Reference and embed content from other documents with live updates.
Advanced table operations: Spreadsheet-like formulas within tables, charts generated from table data.
Web Worker for OT computation: Offload operation transformation and document model computation to a Web Worker, keeping the main thread free for rendering.

Endpoint Summary

Endpoint	Method	Description
`/api/docs/:id`	GET	Fetch document content and metadata
`/api/docs/:id`	PUT	Save document snapshot
`/api/docs`	POST	Create new document
`/api/docs/:id`	DELETE	Delete document
`wss://collab.example.com/doc/:id`	WebSocket	Real-time sync and presence
`/api/docs/:id/comments`	GET / POST	Fetch or add comments
`/api/docs/:id/comments/:cid`	PUT	Edit or resolve comment
`/api/docs/:id/comments/:cid/replies`	POST	Add reply to comment thread
`/api/docs/:id/versions`	GET	List version history
`/api/docs/:id/versions/:vid`	GET	Fetch specific version
`/api/docs/:id/media`	POST	Upload media
`/api/docs/:id/export`	POST	Export to PDF/DOCX/HTML

Complete Data Flow Summary

Direction	Mechanism	Trigger	Target	Action
Initial Load	REST (CSR)	Page open	`GET /api/docs/:id` → Model → Render	Load and display document
User Types	Local (synchronous)	Keystroke	BeforeInput → Model → DOM	Instant local update
Sync to Server	WebSocket (async)	After local apply	OT Client → WebSocket → Server	Send operation for transformation
Receive Remote Edit	WebSocket (push)	Server broadcast	WebSocket → OT Transform → Model → DOM	Apply remote changes
Cursor Presence	WebSocket (throttled)	Cursor move	Presence → WebSocket → All Clients	Show remote cursors
Format Text	Local + Sync	Toolbar click or shortcut	Model operation → DOM → WebSocket	Apply and broadcast formatting
Add Comment	REST + RT	User comments	`POST /api/docs/:id/comments` + WS broadcast	Comment appears for all users
Auto Save	Implicit (OT stream)	Every operation	OT ops → Server → persist	Every edit is saved server-side
Version Restore	REST	User selects version	`GET /api/docs/:id/versions/:vid` → Model → Render	Reload document at version
Offline Edit	Local buffer	Network drops	Model → IndexedDB buffer → Sync on reconnect	Preserve and sync later

More Details:

Get all articles related to system design
Hashtag: SystemDesignWithZeeshanAli

systemdesignwithzeeshanali

Git: https://github.com/ZeeshanAli-0704/front-end-system-design

Frontend JavaScript Utilities — From Scratch

ZeeshanAli-0704 — Wed, 08 Jul 2026 01:20:54 +0000

Frontend JavaScript Utilities — From Scratch

A complete, interview-ready reference. Every utility is implemented from scratch, with:

Theory — what it does and why it matters
Implementation — heavily commented code
Complexity — time & space
Edge cases — the ones interviewers probe
Variations — the follow-ups you'll be asked

Interview mindset: don't just make it work. State assumptions, name edge cases out loud,
reason about time/space, and write tests. That is what separates a "hire" from a "no-hire".

Level 1 — Language Fundamentals
Level 2 — Objects
Level 3 — Function Utilities
Level 4 — Promise Exercises
Level 5 — Async JavaScript
Level 6 — Event System
Level 7 — Data Structures
Level 8 — Object Manipulation
Level 9 — Parsing
Level 10 — Tree / DOM Problems
Level 11 — Rate Limiting
Level 12 — Advanced Utilities
Level 13 — Google Frontend Machine Coding
30-Day Practice Plan

Level 1 — Language Fundamentals

Key this insight: array methods are called as arr.myMap(cb), so inside the method
this is the array. Also honor the optional second thisArg argument the natives accept.
Native methods skip holes in sparse arrays ([1, , 3]) — we can note that but a simple
index loop is acceptable in interviews.

1. `Array.prototype.map`

Theory: Returns a new array where each element is the result of callback(element, index, array).
It never mutates the original and always returns an array of the same length.

Array.prototype.myMap = function (callback, thisArg) {
  // Guard: callback must be callable.
  if (typeof callback !== "function") {
    throw new TypeError(callback + " is not a function");
  }

  const result = new Array(this.length); // preallocate for perf

  for (let i = 0; i < this.length; i++) {
    // `i in this` skips holes in sparse arrays, mirroring native behavior.
    if (i in this) {
      // thisArg lets callers control `this` inside the callback.
      result[i] = callback.call(thisArg, this[i], i, this);
    }
  }
  return result;
};

// Example
console.log([1, 2, 3].myMap((x) => x * 2)); // [2, 4, 6]

Breaking down the pieces

What is this?
When you call a method with dot notation, this is the object to the left of the dot. Because
myMap is attached to Array.prototype, every array inherits it, so in [10, 20, 30].myMap(cb),
this is the array [10, 20, 30] — the same array native .map() would operate on.

What is this.length?
Since this is the array, this.length is just the array's length (3 above). It drives the
loop bounds and pre-sizes the result:

new Array(this.length) → pre-creates a same-size array so the engine avoids repeated resizing.
for (let i = 0; i < this.length; i++) → visits every index; this[i] reads each element.

What is thisArg?
thisArg is an optional second argument (the native map supports it too) that controls what
this refers to inside the callback. That's why we use callback.call(thisArg, ...) instead of
callback(...) — Function.prototype.call runs the callback with its this set to thisArg.

const multiplier = {
  factor: 3,
  scale(x) {
    return x * this.factor; // `this` must be the multiplier object
  },
};

// Pass `multiplier` as thisArg so `this.factor` works inside scale().
console.log([1, 2, 3].myMap(multiplier.scale, multiplier)); // [3, 6, 9]

thisArg only matters for regular functions. Arrow functions ignore it because they capture
this from where they were defined — so [1,2,3].myMap((x) => x * 2) never needs it.

What is i in this?
The if (i in this) check handles sparse arrays (arrays with holes). In [1, , 3], index 1
was never assigned, so 1 in arr is false. Native .map() skips holes rather than calling the
callback on them, and this check mirrors that. For dense (normal) arrays it's always true.

The three callback arguments — callback.call(thisArg, this[i], i, this) passes exactly what
native map gives you: the current element (this[i]), the index (i), and the whole
array (this). That's why arr.map((element, index, array) => ...) works.

Deep dive: `callback.call(thisArg, this[i], i, this)`

Every function has a built-in .call() method. It invokes the function immediately, but lets
you explicitly set (1) what this will be inside it (the first argument) and (2) the arguments
it receives (everything after the first, passed individually):

someFunction.call(whatThisShouldBe, arg1, arg2, arg3);
// ≡ someFunction(arg1, arg2, arg3) but with `this` forced to whatThisShouldBe

Mapping that onto our line:

callback.call(thisArg, this[i], i, this);
//            └──┬───┘  └─┬──┘  │  └─┬─┘
//          this inside  elem  idx  whole
//          the callback              array

Piece	Role	What it is
`thisArg`	sets `this` in callback	the optional 2nd arg the caller passed to `myMap`
`this[i]`	1st callback argument	the current element (`this` is the array, `i` the index)
`i`	2nd callback argument	the current index
`this`	3rd callback argument	the whole array

Why .call() and not just callback(this[i], i, this)? The elements would still pass fine — but
you'd lose control of this inside the callback. .call(thisArg, ...) is exactly what makes the
optional thisArg feature work.

Related trio: .call(fn, a, b, c) passes args individually; .apply(fn, [a, b, c]) passes
them as an array; .bind(...) returns a new function instead of calling now. See #24–26.

Why pass the whole array as the 3rd argument?

The element and index tell the callback what and where. But some callbacks need to see other
elements or the array as a whole to decide — the third argument gives them that access
without relying on an outside variable.

// Mark each element as a local peak (bigger than both neighbors).
[3, 7, 2, 8, 5].map((value, index, array) => {
  const left = array[index - 1] ?? -Infinity;   // needs the array!
  const right = array[index + 1] ?? -Infinity;  // needs the array!
  return value > left && value > right;
});
// [false, true, false, true, false]

You can often close over the array variable instead (nums.map(v => v / nums.length)), but the
third argument matters when:

The array has no name — getData().map((v, i, arr) => ...); arr is your only handle.
The callback is reusable — a named function defined elsewhere can't close over a local array:

function isLocalMax(value, index, array) {
  return value > (array[index - 1] ?? -Infinity) &&
         value > (array[index + 1] ?? -Infinity);
}

[3, 7, 2].map(isLocalMax); // reused on any array — no closure needed

Our myMap passes this as the third argument purely to mirror the native contract
(element, index, array). If it didn't, callbacks like isLocalMax would work with native .map()
but break under myMap — so it wouldn't be a faithful replacement. Most callbacks ignore this
argument (hence the common arr.map(x => ...)); it costs nothing and helps the minority that need it.

Arrow-function variation

You can write the whole thing as an arrow function — but note the catch: arrow functions have no
own this, so we can't attach one to Array.prototype and rely on this being the array.
Instead, pass the array in explicitly:

// Arrow-function style: array is an explicit parameter, no `this` involved.
const myMap = (arr, callback, thisArg) => {
  if (typeof callback !== "function") {
    throw new TypeError(callback + " is not a function");
  }
  const result = new Array(arr.length);
  for (let i = 0; i < arr.length; i++) {
    if (i in arr) result[i] = callback.call(thisArg, arr[i], i, arr);
  }
  return result;
};

console.log(myMap([1, 2, 3], (x) => x * 2)); // [2, 4, 6]

Why not Array.prototype.myMap = (callback) => {...}? An arrow function's this would be
whatever surrounded its definition (often module.exports/window), not the array it's
called on — so this.length would be wrong. Prototype methods must be regular functions.
Time: O(n) · Space: O(n)
Edge cases: empty array → []; callback not a function → throw; sparse arrays.
Variation: implement without preallocation using push.

2. `Array.prototype.filter`

Theory: Returns a new array containing only elements for which callback returns truthy.

Array.prototype.myFilter = function (callback, thisArg) {
  if (typeof callback !== "function") {
    throw new TypeError(callback + " is not a function");
  }

  const result = [];
  for (let i = 0; i < this.length; i++) {
    if (i in this && callback.call(thisArg, this[i], i, this)) {
      result.push(this[i]); // keep only truthy matches
    }
  }
  return result;
};

// Example
console.log([1, 2, 3, 4].myFilter((x) => x % 2 === 0)); // [2, 4]

Time: O(n) · Space: O(k) where k = matches.
Edge case: predicate returning a truthy/falsy non-boolean (e.g. 0, "", NaN).

3. `Array.prototype.reduce`

Theory: Folds an array into a single accumulated value. If no initialValue is provided,
the first element becomes the accumulator and iteration starts at index 1.

Array.prototype.myReduce = function (callback, initialValue) {
  if (typeof callback !== "function") {
    throw new TypeError(callback + " is not a function");
  }

  let acc = initialValue;
  let startIndex = 0;
  const hasInitial = arguments.length >= 2; // distinguishes `undefined` from "missing"

  if (!hasInitial) {
    // Find first real element to seed the accumulator (skip holes).
    while (startIndex < this.length && !(startIndex in this)) startIndex++;
    if (startIndex >= this.length) {
      throw new TypeError("Reduce of empty array with no initial value");
    }
    acc = this[startIndex++];
  }

  for (let i = startIndex; i < this.length; i++) {
    if (i in this) acc = callback(acc, this[i], i, this);
  }
  return acc;
};

// Example
console.log([1, 2, 3, 4].myReduce((sum, x) => sum + x, 0)); // 10
console.log([1, 2, 3].myReduce((a, b) => a + b));           // 6 (no initial)

Time: O(n) · Space: O(1)
Classic bug: using initialValue !== undefined instead of arguments.length >= 2. reduce(cb, undefined) MUST treat undefined as a provided seed.
Variation: myReduceRight iterates from the end.

`arguments` vs `this` (and why `arguments.length >= 2`)

this and arguments are two different automatic bindings that exist inside every regular
function — they answer different questions.

this = who the function was called on (the object left of the dot).
arguments = what arguments were actually passed (an array-like list, in order).

[1, 2, 3].myReduce(cb, 0);
// this      → [1, 2, 3]   (the receiver / array)
// arguments → [cb, 0]     arguments.length === 2

	`this`	`arguments`
Answers	who it's called on	what was passed in
In the call above	`[1,2,3]` (the array)	`[cb, 0]` (the params)
Type	the receiver object	array-like list of args

Why arguments.length >= 2 matters. reduce must distinguish these two calls:

arr.myReduce(cb);            // NO initial value → seed with first element
arr.myReduce(cb, undefined); // initial value IS undefined → seed with undefined

Checking initialValue !== undefined can't tell them apart — a missing 2nd parameter is also
undefined. But arguments.length counts how many arguments were actually passed, regardless
of their values:

arr.myReduce(cb);            // arguments.length === 1  → no initial
arr.myReduce(cb, undefined); // arguments.length === 2  → initial IS undefined

// Proof:
[].myReduce((a, b) => a + b);             // throws "Reduce of empty array..." (no seed)
[].myReduce((a, b) => a + b, 0);          // 0 (seed provided)
[5].myReduce((a, b) => a + b, undefined); // undefined (undefined WAS the seed)

Gotcha: arguments only exists in regular functions — arrow functions have no own
arguments (or this). In an arrow you'd use rest params instead: (...args) => args.length.

4. `Array.prototype.find`

Theory: Returns the first element for which the predicate is truthy, else undefined.
(findIndex returns the index or -1.)

Array.prototype.myFind = function (callback, thisArg) {
  if (typeof callback !== "function") throw new TypeError("callback is not a function");
  for (let i = 0; i < this.length; i++) {
    // Note: find does NOT skip holes; it visits every index (unlike map/filter).
    if (callback.call(thisArg, this[i], i, this)) return this[i];
  }
  return undefined;
};

console.log([5, 12, 8, 130].myFind((x) => x > 10)); // 12

Time: O(n) worst case, early exit on match · Space: O(1)

5. `Array.prototype.some`

Theory: Returns true if at least one element passes the predicate. Short-circuits.
Empty array → false.

Array.prototype.mySome = function (callback, thisArg) {
  if (typeof callback !== "function") throw new TypeError("callback is not a function");
  for (let i = 0; i < this.length; i++) {
    if (i in this && callback.call(thisArg, this[i], i, this)) return true;
  }
  return false;
};

console.log([1, 2, 3].mySome((x) => x > 2)); // true

Time: O(n), early exit · Space: O(1)

6. `Array.prototype.every`

Theory: Returns true if all elements pass. Short-circuits on first failure.
Empty array → true (vacuous truth).

Array.prototype.myEvery = function (callback, thisArg) {
  if (typeof callback !== "function") throw new TypeError("callback is not a function");
  for (let i = 0; i < this.length; i++) {
    if (i in this && !callback.call(thisArg, this[i], i, this)) return false;
  }
  return true;
};

console.log([2, 4, 6].myEvery((x) => x % 2 === 0)); // true

Note: some and every are duals: every(p) === !some(!p).

7. `Array.prototype.flat(depth)`

Theory: Flattens nested arrays up to depth levels (default 1). Infinity fully flattens.

// Recursive version — clean and readable.
Array.prototype.myFlat = function (depth = 1) {
  const result = [];
  for (const item of this) {
    if (Array.isArray(item) && depth > 0) {
      // Spread the recursively-flattened sub-array one level shallower.
      result.push(...item.myFlat(depth - 1));
    } else {
      result.push(item);
    }
  }
  return result;
};

console.log([1, [2, [3, [4]]]].myFlat(Infinity)); // [1, 2, 3, 4]
console.log([1, [2, [3]]].myFlat(1));             // [1, 2, [3]]

Iterative version (no recursion — common follow-up):

function flattenIterative(arr) {
  const stack = [...arr];
  const result = [];
  while (stack.length) {
    const next = stack.pop();
    if (Array.isArray(next)) stack.push(...next); // push children back
    else result.push(next);
  }
  return result.reverse(); // pop reverses order, so restore it
}

Time: O(n) total elements · Space: O(n)
Follow-up: "flatten without recursion" → use the explicit stack version.

8. `Array.prototype.flatMap`

Theory: map then flat(1). Useful for expanding each element into 0..n items.

Array.prototype.myFlatMap = function (callback, thisArg) {
  return this.myMap((v, i, arr) => callback.call(thisArg, v, i, arr)).myFlat(1);
};

console.log([1, 2, 3].myFlatMap((x) => [x, x * 2])); // [1, 2, 2, 4, 3, 6]

Only flattens one level — a frequent gotcha.

9. `Array.prototype.includes`

Theory: Returns true if the array contains value, using SameValueZero equality
(so NaN matches NaN, unlike indexOf).

Array.prototype.myIncludes = function (value, fromIndex = 0) {
  const len = this.length;
  // Handle negative fromIndex (counts from the end).
  let start = fromIndex < 0 ? Math.max(len + fromIndex, 0) : fromIndex;

  for (let i = start; i < len; i++) {
    const el = this[i];
    // SameValueZero: equal, OR both NaN.
    if (el === value || (el !== el && value !== value)) return true;
  }
  return false;
};

console.log([1, NaN, 3].myIncludes(NaN)); // true  (indexOf would fail here)

Key difference vs indexOf: NaN handling via the el !== el trick.

10. Deep Clone (Objects, Arrays, Date, RegExp, circular refs)

Theory: Recursively copy so that mutating the clone never affects the original. We'll build it
up in 4 steps, each fixing a weakness of the previous one.

Step 1 — the naive one-liner (know its limits)

const clone = JSON.parse(JSON.stringify(obj));

Works for plain JSON data, but breaks on: Date (becomes a string), RegExp/Map/Set
(become {}), undefined/functions (dropped), and throws on circular references. Interviewers
mention this only to then ask you to do better.

Step 2 — recursion for objects & arrays

Handle the core case: recurse into every key, preserving array-vs-object shape.

function deepClone(value) {
  // Primitives (string, number, boolean, null, undefined) copy by value already.
  if (value === null || typeof value !== "object") return value;

  // Preserve the shape: array stays array, object stays object.
  const clone = Array.isArray(value) ? [] : {};

  for (const key of Object.keys(value)) {
    clone[key] = deepClone(value[key]); // recurse into each property
  }
  return clone;
}

const a = { n: 1, nested: { m: 2 }, list: [3, 4] };
const b = deepClone(a);
b.nested.m = 99;
console.log(a.nested.m); // 2 — original untouched

Still missing: special built-ins (Date, RegExp…) and cycles (would infinite-loop).

Step 3 — add special built-in types

Each built-in needs its own copy logic, checked before the generic object branch.

function deepClone(value) {
  if (value === null || typeof value !== "object") return value;

  // --- special built-ins ---
  if (value instanceof Date) return new Date(value.getTime());
  if (value instanceof RegExp) return new RegExp(value.source, value.flags);
  if (value instanceof Map) {
    const out = new Map();
    value.forEach((v, k) => out.set(deepClone(k), deepClone(v)));
    return out;
  }
  if (value instanceof Set) {
    const out = new Set();
    value.forEach((v) => out.add(deepClone(v)));
    return out;
  }

  // --- generic object / array ---
  const clone = Array.isArray(value) ? [] : {};
  for (const key of Object.keys(value)) {
    clone[key] = deepClone(value[key]);
  }
  return clone;
}

Still missing: circular references (a.self = a → infinite recursion → stack overflow).

Step 4 — handle cycles with a `WeakMap` (the full answer)

A WeakMap remembers "original → its clone". Before recursing into an object, register its clone
first; if we meet the same object again, return the clone we already started instead of looping.

function deepClone(value, seen = new WeakMap()) {
  // Primitives (and functions) are returned as-is.
  if (value === null || typeof value !== "object") return value;

  // Special built-in objects.
  if (value instanceof Date) return new Date(value.getTime());
  if (value instanceof RegExp) return new RegExp(value.source, value.flags);
  if (value instanceof Map) {
    const out = new Map();
    seen.set(value, out);
    value.forEach((v, k) => out.set(deepClone(k, seen), deepClone(v, seen)));
    return out;
  }
  if (value instanceof Set) {
    const out = new Set();
    seen.set(value, out);
    value.forEach((v) => out.add(deepClone(v, seen)));
    return out;
  }

  // Circular reference: return the copy we already started.
  if (seen.has(value)) return seen.get(value);

  // Preserve array vs plain object shape.
  const clone = Array.isArray(value) ? [] : {};
  seen.set(value, clone); // register BEFORE recursing to break cycles

  // Reflect.ownKeys also copies Symbol keys (Object.keys skips them).
  for (const key of Reflect.ownKeys(value)) {
    clone[key] = deepClone(value[key], seen);
  }
  return clone;
}

// Example — circular reference
const a = { name: "x" };
a.self = a;
const b = deepClone(a);
console.log(b.self === b);  // true (cycle preserved, not infinite loop)
console.log(b !== a);       // true

Time: O(n) nodes · Space: O(n)
What each step added: (1) baseline → (2) recursion → (3) built-ins → (4) cycles + symbol keys.
Why WeakMap? keys are held weakly, so cloned originals can still be garbage-collected.
Note: structuredClone() is the built-in modern answer, but interviewers want the manual one.

Level 2 — Objects

11. `Object.assign`

Theory: Copies own enumerable properties from sources into the target (shallow), mutating and returning the target. Triggers setters and copies symbols.

function objectAssign(target, ...sources) {
  if (target == null) throw new TypeError("Cannot convert null/undefined to object");
  const to = Object(target); // boxes primitives

  for (const source of sources) {
    if (source == null) continue; // null/undefined sources are skipped
    for (const key of Reflect.ownKeys(source)) {
      // Only own ENUMERABLE properties are copied.
      const desc = Object.getOwnPropertyDescriptor(source, key);
      if (desc && desc.enumerable) to[key] = source[key];
    }
  }
  return to;
}

console.log(objectAssign({ a: 1 }, { b: 2 }, { a: 9 })); // { a: 9, b: 2 }

Shallow only — nested objects are shared by reference.

12. `Object.entries`

Theory: Returns an array of [key, value] pairs for own enumerable string-keyed props.

function objectEntries(obj) {
  if (obj == null) throw new TypeError("Cannot convert null/undefined to object");
  const result = [];
  for (const key of Object.keys(obj)) {
    result.push([key, obj[key]]);
  }
  return result;
}

console.log(objectEntries({ a: 1, b: 2 })); // [["a",1],["b",2]]

13. `Object.fromEntries`

Theory: Inverse of entries — builds an object from [key, value] pairs. Accepts any iterable.

function objectFromEntries(iterable) {
  const obj = {};
  for (const [key, value] of iterable) {
    obj[key] = value;
  }
  return obj;
}

console.log(objectFromEntries([["a", 1], ["b", 2]])); // { a: 1, b: 2 }
// Bonus: works with a Map directly since Map is iterable of entries.

14. Deep Freeze

Theory: Object.freeze is shallow. Deep freeze recurses so nested objects are also immutable.
Guard against cycles.

function deepFreeze(obj, seen = new WeakSet()) {
  if (obj === null || typeof obj !== "object" || seen.has(obj)) return obj;
  seen.add(obj);

  // Freeze children first, then the object itself.
  for (const key of Reflect.ownKeys(obj)) {
    deepFreeze(obj[key], seen);
  }
  return Object.freeze(obj);
}

const cfg = deepFreeze({ a: { b: 1 } });
cfg.a.b = 99; // silently ignored (throws in strict mode)
console.log(cfg.a.b); // 1

15. Deep Merge

Theory: Recursively merge sources into a target. Plain objects merge key-by-key; arrays and
primitives typically overwrite (define your policy explicitly in the interview).

function isPlainObject(v) {
  return v !== null && typeof v === "object" && !Array.isArray(v);
}

function deepMerge(target, ...sources) {
  for (const source of sources) {
    if (!isPlainObject(source)) continue;
    for (const key of Object.keys(source)) {
      if (isPlainObject(source[key]) && isPlainObject(target[key])) {
        deepMerge(target[key], source[key]); // recurse into nested objects
      } else {
        target[key] = source[key]; // overwrite (arrays/primitives)
      }
    }
  }
  return target;
}

console.log(deepMerge({ a: { x: 1 } }, { a: { y: 2 } })); // { a: { x: 1, y: 2 } }

Design decision to state: how do you merge arrays? (concat vs replace vs index-merge).

Level 3 — Function Utilities

These are the most common Google frontend warm-ups. Know them cold.

16. Debounce

Theory: Delays invoking fn until delay ms have passed without a new call.
Great for search-as-you-type, resize, autosave.

function debounce(fn, delay) {
  let timerId;
  function debounced(...args) {
    clearTimeout(timerId); // cancel the pending call
    timerId = setTimeout(() => fn.apply(this, args), delay); // preserve `this`
  }
  debounced.cancel = () => clearTimeout(timerId);
  return debounced;
}

const log = debounce(() => console.log("fired"), 300);
log(); log(); log(); // only the last one fires, 300ms after the final call

Production version (leading, trailing, maxWait): see #82 in Level 13.

Edge cases: preserve this and args; provide cancel.

17. Throttle

Theory: Ensures fn runs at most once per interval. Good for scroll, mousemove.

function throttle(fn, interval) {
  let lastTime = 0;
  let timerId = null;

  return function throttled(...args) {
    const now = Date.now();
    const remaining = interval - (now - lastTime);

    if (remaining <= 0) {
      // Enough time passed — run immediately (leading edge).
      lastTime = now;
      fn.apply(this, args);
    } else if (!timerId) {
      // Schedule a trailing call for the leftover window.
      timerId = setTimeout(() => {
        lastTime = Date.now();
        timerId = null;
        fn.apply(this, args);
      }, remaining);
    }
  };
}

Debounce vs throttle: debounce waits for silence; throttle guarantees a steady cadence.

18. `once()`

Theory: Wraps fn so it runs only the first time; later calls return the cached result.

function once(fn) {
  let called = false;
  let result;
  return function (...args) {
    if (!called) {
      called = true;
      result = fn.apply(this, args);
    }
    return result;
  };
}

const init = once(() => console.log("init") || 42);
init(); // "init" -> 42
init(); // 42 (no log)

19. `memoize()`

Theory: Caches results by arguments so repeated calls with the same inputs are O(1).

function memoize(fn, resolver) {
  const cache = new Map();
  return function (...args) {
    // Default key = JSON of args. `resolver` lets callers customize the key.
    const key = resolver ? resolver(...args) : JSON.stringify(args);
    if (cache.has(key)) return cache.get(key);
    const result = fn.apply(this, args);
    cache.set(key, result);
    return result;
  };
}

const slowSquare = memoize((n) => n * n);
console.log(slowSquare(4)); // computes -> 16
console.log(slowSquare(4)); // cached  -> 16

Caveat: JSON.stringify fails on functions/circular args → allow a custom resolver.

20. `curry()`

Theory: Transforms f(a, b, c) into f(a)(b)(c). Collect args until arity is met, then call.

function curry(fn) {
  return function curried(...args) {
    if (args.length >= fn.length) {
      // Enough args collected — invoke the original.
      return fn.apply(this, args);
    }
    // Otherwise return a function that gathers more args.
    return (...next) => curried.apply(this, [...args, ...next]);
  };
}

const sum = curry((a, b, c) => a + b + c);
console.log(sum(1)(2)(3)); // 6
console.log(sum(1, 2)(3)); // 6
console.log(sum(1)(2, 3)); // 6

Note: relies on fn.length (declared parameter count) — rest params break it.

21. `compose()`

Theory: Right-to-left function composition: compose(f, g)(x) === f(g(x)).

function compose(...fns) {
  return function (initial) {
    return fns.reduceRight((acc, fn) => fn(acc), initial);
  };
}

const add1 = (x) => x + 1;
const double = (x) => x * 2;
console.log(compose(add1, double)(5)); // add1(double(5)) = 11

22. `pipe()`

Theory: Left-to-right composition (the reading order): pipe(f, g)(x) === g(f(x)).

function pipe(...fns) {
  return function (initial) {
    return fns.reduce((acc, fn) => fn(acc), initial);
  };
}

console.log(pipe(add1, double)(5)); // double(add1(5)) = 12

23. `partial()`

Theory: Pre-fills leading arguments, returning a function that takes the rest.

function partial(fn, ...preset) {
  return function (...rest) {
    return fn.apply(this, [...preset, ...rest]);
  };
}

const greet = (greeting, name) => `${greeting}, ${name}!`;
const hello = partial(greet, "Hello");
console.log(hello("Ada")); // "Hello, Ada!"

Variation: support placeholders (_) to skip positions.

24. `Function.prototype.myBind`

Theory: Returns a new function bound to a given this and optional preset args. Must also
support being used as a constructor with new (then this binding is ignored).

Function.prototype.myBind = function (thisArg, ...boundArgs) {
  const targetFn = this;
  if (typeof targetFn !== "function") throw new TypeError("Bind must be called on a function");

  function bound(...callArgs) {
    // If called with `new`, `this` is a fresh instance → ignore thisArg.
    const isNew = this instanceof bound;
    return targetFn.apply(isNew ? this : thisArg, [...boundArgs, ...callArgs]);
  }

  // Maintain the prototype chain for `new boundFn()`.
  if (targetFn.prototype) {
    bound.prototype = Object.create(targetFn.prototype);
  }
  return bound;
};

function greet(greeting, name) { return `${greeting}, ${name}, I am ${this.role}`; }
const bound = greet.myBind({ role: "dev" }, "Hi");
console.log(bound("Sam")); // "Hi, Sam, I am dev"

25. `Function.prototype.myCall`

Theory: Invokes the function immediately with a given this and individual arguments.

Function.prototype.myCall = function (thisArg, ...args) {
  // Box primitives; default to globalThis when null/undefined.
  thisArg = thisArg == null ? globalThis : Object(thisArg);

  const fnKey = Symbol("fn"); // unique key avoids clobbering existing props
  thisArg[fnKey] = this;      // temporarily attach the function
  const result = thisArg[fnKey](...args); // `this` inside now = thisArg
  delete thisArg[fnKey];      // clean up
  return result;
};

function whoAmI() { return this.name; }
console.log(whoAmI.myCall({ name: "Neo" })); // "Neo"

26. `Function.prototype.myApply`

Theory: Like call, but arguments are passed as a single array.

Function.prototype.myApply = function (thisArg, argsArray) {
  thisArg = thisArg == null ? globalThis : Object(thisArg);
  const args = argsArray || [];

  const fnKey = Symbol("fn");
  thisArg[fnKey] = this;
  const result = thisArg[fnKey](...args);
  delete thisArg[fnKey];
  return result;
};

function sum(a, b) { return a + b + this.base; }
console.log(sum.myApply({ base: 10 }, [1, 2])); // 13

call vs apply: "call = Comma-separated, apply = Array" — handy mnemonic.

Level 4 — Promise Exercises

27. `Promise.all`

Theory: Resolves when all promises resolve, preserving input order. Rejects immediately if
any rejects (fail-fast).

function promiseAll(promises) {
  return new Promise((resolve, reject) => {
    const results = [];
    let completed = 0;
    const items = Array.from(promises);
    if (items.length === 0) return resolve([]); // empty → resolve immediately

    items.forEach((p, index) => {
      // Wrap non-promises so `.then` always works.
      Promise.resolve(p).then((value) => {
        results[index] = value;       // keep original order via index
        if (++completed === items.length) resolve(results);
      }, reject);                     // first rejection rejects the whole thing
    });
  });
}

promiseAll([Promise.resolve(1), Promise.resolve(2)]).then(console.log); // [1, 2]

Edge cases: empty array → []; non-promise values are allowed.

28. `Promise.allSettled`

Theory: Waits for all to settle and never rejects. Each result is
{status:"fulfilled", value} or {status:"rejected", reason}.

function promiseAllSettled(promises) {
  return new Promise((resolve) => {
    const results = [];
    let completed = 0;
    const items = Array.from(promises);
    if (items.length === 0) return resolve([]);

    items.forEach((p, index) => {
      Promise.resolve(p).then(
        (value) => { results[index] = { status: "fulfilled", value }; },
        (reason) => { results[index] = { status: "rejected", reason }; }
      ).finally(() => {
        if (++completed === items.length) resolve(results);
      });
    });
  });
}

29. `Promise.any`

Theory: Resolves with the first fulfilled value. Rejects only if all reject, with an
AggregateError collecting every reason.

function promiseAny(promises) {
  return new Promise((resolve, reject) => {
    const errors = [];
    let rejectedCount = 0;
    const items = Array.from(promises);
    if (items.length === 0) {
      return reject(new AggregateError([], "All promises were rejected"));
    }

    items.forEach((p, index) => {
      Promise.resolve(p).then(resolve, (err) => {
        errors[index] = err;
        if (++rejectedCount === items.length) {
          reject(new AggregateError(errors, "All promises were rejected"));
        }
      });
    });
  });
}

30. `Promise.race`

Theory: Settles as soon as the first promise settles (fulfilled OR rejected).

function promiseRace(promises) {
  return new Promise((resolve, reject) => {
    for (const p of promises) {
      // Whichever settles first wins; the rest are ignored.
      Promise.resolve(p).then(resolve, reject);
    }
  });
}

race vs any: race settles on first settle (incl. reject); any needs first fulfill.

31. Retry Promise

Theory: Retry an async operation up to retries times before giving up. Add backoff for
production (exponential backoff in Level 13).

function retry(fn, retries) {
  return new Promise((resolve, reject) => {
    function attempt(remaining) {
      fn()
        .then(resolve)
        .catch((err) => {
          if (remaining <= 0) reject(err);       // out of tries → propagate
          else attempt(remaining - 1);            // try again
        });
    }
    attempt(retries);
  });
}

let n = 0;
const flaky = () => (++n < 3 ? Promise.reject("fail") : Promise.resolve("ok"));
retry(flaky, 5).then(console.log); // "ok" on the 3rd try

32. Timeout Promise

Theory: Reject if a promise doesn't settle within ms. Implemented by racing against a timer.

function timeout(promise, ms) {
  const timer = new Promise((_, reject) =>
    setTimeout(() => reject(new Error(`Timed out after ${ms}ms`)), ms)
  );
  return Promise.race([promise, timer]);
}

timeout(fetch("/data"), 5000).catch(console.error);

Note: the underlying work still runs; timeout only stops waiting. Use AbortController to actually cancel a real fetch.

33. Promise Queue (Concurrency = 3)

Theory: Run async tasks with a cap on how many run simultaneously. Each task is a
function returning a promise.

class PromiseQueue {
  constructor(concurrency = 3) {
    this.concurrency = concurrency;
    this.running = 0;
    this.queue = [];
  }

  add(taskFn) {
    return new Promise((resolve, reject) => {
      // Store the task plus its outer resolve/reject so we can settle later.
      this.queue.push({ taskFn, resolve, reject });
      this._next();
    });
  }

  _next() {
    // Fill available slots up to the concurrency limit.
    while (this.running < this.concurrency && this.queue.length) {
      const { taskFn, resolve, reject } = this.queue.shift();
      this.running++;
      Promise.resolve(taskFn())
        .then(resolve, reject)
        .finally(() => {
          this.running--;
          this._next(); // a slot freed up → pull the next task
        });
    }
  }
}

const q = new PromiseQueue(3);
for (let i = 0; i < 10; i++) {
  q.add(() => new Promise((r) => setTimeout(() => r(i), 100)));
}

Time to first task: O(1) · Steady-state parallelism = concurrency.

34. Task Scheduler (Max Parallel)

Theory: Same idea as the queue but exposed as a single runTask API — a common phrasing.

function createScheduler(maxParallel) {
  let active = 0;
  const waiting = [];

  function runTask(task) {
    return new Promise((resolve, reject) => {
      const run = () => {
        active++;
        Promise.resolve(task())
          .then(resolve, reject)
          .finally(() => {
            active--;
            if (waiting.length) waiting.shift()(); // wake next waiter
          });
      };
      if (active < maxParallel) run();
      else waiting.push(run); // park until a slot frees
    });
  }

  return { runTask };
}

Level 5 — Async JavaScript

35. `sleep(ms)`

Theory: Promisified delay — the building block for pacing async loops.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function demo() {
  console.log("start");
  await sleep(1000);
  console.log("1s later");
}

36. `asyncPool()` (Max Concurrent Requests)

Theory: Map over items with an async iteratorFn, keeping at most poolLimit in flight,
and return results in input order.

async function asyncPool(poolLimit, items, iteratorFn) {
  const results = [];
  const executing = new Set();

  for (const item of items) {
    // Kick off the task and remember its promise.
    const p = Promise.resolve().then(() => iteratorFn(item));
    results.push(p);
    executing.add(p);

    // When it finishes, remove it from the in-flight set.
    p.finally(() => executing.delete(p));

    // If we're at the limit, wait for ANY task to finish before continuing.
    if (executing.size >= poolLimit) {
      await Promise.race(executing);
    }
  }
  return Promise.all(results); // preserves order
}

// asyncPool(2, [1,2,3,4], (n) => fetch(`/x/${n}`));

37. Sequential Executor

Theory: Run tasks strictly one after another; each waits for the previous.

async function runSequential(tasks) {
  const results = [];
  for (const task of tasks) {
    results.push(await task()); // await forces order
  }
  return results;
}

Reduce version: tasks.reduce((p, t) => p.then((acc) => t().then((r) => [...acc, r])), Promise.resolve([])).

38. Parallel Executor

Theory: Start everything at once and wait for all.

async function runParallel(tasks) {
  return Promise.all(tasks.map((task) => task()));
}

Contrast: sequential = sum of durations; parallel = max duration.

39. Cancellation Token

Theory: A signal object callers can check/await to abort long work cooperatively.
Mirrors the standard AbortController.

function createCancelToken() {
  let cancelled = false;
  const listeners = [];
  return {
    cancel() {
      cancelled = true;
      listeners.forEach((fn) => fn());
    },
    get isCancelled() { return cancelled; },
    onCancel(fn) { listeners.push(fn); },
    throwIfCancelled() { if (cancelled) throw new Error("Cancelled"); },
  };
}

async function work(token) {
  for (let i = 0; i < 1000; i++) {
    token.throwIfCancelled(); // cooperative checkpoint
    await sleep(10);
  }
}

Real-world: prefer the native AbortController / signal passed to fetch.

Level 6 — Event System

40. EventEmitter (`on`, `off`, `once`, `emit`)

Theory: Pub/sub keyed by event name. on subscribes, off unsubscribes, once auto-removes
after one fire, emit calls all listeners with the payload.

class EventEmitter {
  constructor() {
    this.events = new Map(); // eventName -> Set of listeners
  }

  on(event, listener) {
    if (!this.events.has(event)) this.events.set(event, new Set());
    this.events.get(event).add(listener);
    return this; // chainable
  }

  off(event, listener) {
    this.events.get(event)?.delete(listener);
    return this;
  }

  once(event, listener) {
    // Wrapper removes itself after the first call.
    const wrapper = (...args) => {
      this.off(event, wrapper);
      listener.apply(this, args);
    };
    wrapper.original = listener; // allow off(once) by original ref
    return this.on(event, wrapper);
  }

  emit(event, ...args) {
    const listeners = this.events.get(event);
    if (!listeners) return false;
    // Copy to a snapshot so once()-removals mid-emit don't skip listeners.
    [...listeners].forEach((fn) => fn.apply(this, args));
    return true;
  }
}

const bus = new EventEmitter();
bus.on("hi", (name) => console.log("hi " + name));
bus.emit("hi", "Ada"); // "hi Ada"

41. Pub/Sub

Theory: Same pattern, framed as subscribe/publish, returning an unsubscribe handle —
the ergonomic modern API.

function createPubSub() {
  const topics = new Map();
  return {
    subscribe(topic, handler) {
      if (!topics.has(topic)) topics.set(topic, new Set());
      topics.get(topic).add(handler);
      return () => topics.get(topic).delete(handler); // unsubscribe fn
    },
    publish(topic, data) {
      topics.get(topic)?.forEach((h) => h(data));
    },
  };
}

42. Observable (basic)

Theory: A push-based stream: an Observable accepts a subscriber {next, error, complete}
and returns an unsubscribe function. This is the essence of RxJS.

class Observable {
  constructor(subscribeFn) {
    this._subscribe = subscribeFn; // producer function
  }

  subscribe(observer) {
    // Normalize a bare next-callback into an observer object.
    const safe = typeof observer === "function" ? { next: observer } : observer;
    const unsub = this._subscribe({
      next: (v) => safe.next?.(v),
      error: (e) => safe.error?.(e),
      complete: () => safe.complete?.(),
    });
    return { unsubscribe: typeof unsub === "function" ? unsub : () => {} };
  }
}

// Example: emit 1,2,3 then complete.
const obs = new Observable((o) => {
  o.next(1); o.next(2); o.next(3); o.complete();
});
obs.subscribe({ next: console.log, complete: () => console.log("done") });

Level 7 — Data Structures

43. Stack (LIFO)

class Stack {
  constructor() { this.items = []; }
  push(x) { this.items.push(x); }
  pop() { return this.items.pop(); }              // O(1)
  peek() { return this.items[this.items.length - 1]; }
  get size() { return this.items.length; }
  isEmpty() { return this.items.length === 0; }
}

All ops O(1). Uses: undo, DFS, expression parsing, browser history.

44. Queue (FIFO)

Theory: Array shift() is O(n). For O(1) dequeue, use two indices (head/tail) or a linked list.

class Queue {
  constructor() { this.items = {}; this.head = 0; this.tail = 0; }
  enqueue(x) { this.items[this.tail++] = x; }     // O(1)
  dequeue() {
    if (this.isEmpty()) return undefined;
    const val = this.items[this.head];
    delete this.items[this.head++];
    return val;                                    // O(1)
  }
  peek() { return this.items[this.head]; }
  get size() { return this.tail - this.head; }
  isEmpty() { return this.size === 0; }
}

45. Deque (Double-Ended Queue)

class Deque {
  constructor() { this.items = {}; this.head = 0; this.tail = 0; }
  pushBack(x)  { this.items[this.tail++] = x; }
  pushFront(x) { this.items[--this.head] = x; }
  popBack()  { if (this.isEmpty()) return; const v = this.items[--this.tail]; delete this.items[this.tail]; return v; }
  popFront() { if (this.isEmpty()) return; const v = this.items[this.head]; delete this.items[this.head++]; return v; }
  get size() { return this.tail - this.head; }
  isEmpty() { return this.size === 0; }
}

All ends O(1). Uses: sliding-window maximum, LRU internals.

46. Priority Queue

Theory: Elements dequeued by priority, not insertion order. Backed by a binary heap for
O(log n) insert/extract. (See Min Heap below — a priority queue is a heap with a comparator.)

class PriorityQueue {
  constructor(compare = (a, b) => a - b) {
    this.heap = [];
    this.compare = compare; // min-priority by default
  }
  get size() { return this.heap.length; }
  peek() { return this.heap[0]; }

  enqueue(val) {
    this.heap.push(val);
    this._bubbleUp(this.heap.length - 1);
  }

  dequeue() {
    const top = this.heap[0];
    const last = this.heap.pop();
    if (this.heap.length) { this.heap[0] = last; this._bubbleDown(0); }
    return top;
  }

  _bubbleUp(i) {
    while (i > 0) {
      const parent = (i - 1) >> 1;
      if (this.compare(this.heap[i], this.heap[parent]) >= 0) break;
      [this.heap[i], this.heap[parent]] = [this.heap[parent], this.heap[i]];
      i = parent;
    }
  }

  _bubbleDown(i) {
    const n = this.heap.length;
    while (true) {
      let smallest = i;
      const l = 2 * i + 1, r = 2 * i + 2;
      if (l < n && this.compare(this.heap[l], this.heap[smallest]) < 0) smallest = l;
      if (r < n && this.compare(this.heap[r], this.heap[smallest]) < 0) smallest = r;
      if (smallest === i) break;
      [this.heap[i], this.heap[smallest]] = [this.heap[smallest], this.heap[i]];
      i = smallest;
    }
  }
}

47. Min Heap

Theory: Complete binary tree in an array where each parent ≤ children. Parent of i is
(i-1)>>1; children are 2i+1, 2i+2. Insert/extract O(log n), peek O(1).

class MinHeap {
  constructor() { this.heap = []; }
  size() { return this.heap.length; }
  peek() { return this.heap[0]; }

  insert(val) {
    this.heap.push(val);
    let i = this.heap.length - 1;
    // Bubble up while smaller than parent.
    while (i > 0) {
      const p = (i - 1) >> 1;
      if (this.heap[p] <= this.heap[i]) break;
      [this.heap[p], this.heap[i]] = [this.heap[i], this.heap[p]];
      i = p;
    }
  }

  extractMin() {
    if (!this.heap.length) return undefined;
    const min = this.heap[0];
    const last = this.heap.pop();
    if (this.heap.length) {
      this.heap[0] = last;
      this._heapifyDown(0);
    }
    return min;
  }

  _heapifyDown(i) {
    const n = this.heap.length;
    while (true) {
      let smallest = i;
      const l = 2 * i + 1, r = 2 * i + 2;
      if (l < n && this.heap[l] < this.heap[smallest]) smallest = l;
      if (r < n && this.heap[r] < this.heap[smallest]) smallest = r;
      if (smallest === i) break;
      [this.heap[i], this.heap[smallest]] = [this.heap[smallest], this.heap[i]];
      i = smallest;
    }
  }
}

48. Max Heap

Theory: Identical to Min Heap with the comparisons flipped (parent ≥ children). A neat trick:
reuse MinHeap by inserting negated numbers, or pass a reversed comparator to PriorityQueue.

class MaxHeap {
  constructor() { this.heap = []; }
  peek() { return this.heap[0]; }
  size() { return this.heap.length; }

  insert(val) {
    this.heap.push(val);
    let i = this.heap.length - 1;
    while (i > 0) {
      const p = (i - 1) >> 1;
      if (this.heap[p] >= this.heap[i]) break; // parent must be LARGER
      [this.heap[p], this.heap[i]] = [this.heap[i], this.heap[p]];
      i = p;
    }
  }

  extractMax() {
    if (!this.heap.length) return undefined;
    const max = this.heap[0];
    const last = this.heap.pop();
    if (this.heap.length) { this.heap[0] = last; this._down(0); }
    return max;
  }

  _down(i) {
    const n = this.heap.length;
    while (true) {
      let largest = i;
      const l = 2 * i + 1, r = 2 * i + 2;
      if (l < n && this.heap[l] > this.heap[largest]) largest = l;
      if (r < n && this.heap[r] > this.heap[largest]) largest = r;
      if (largest === i) break;
      [this.heap[i], this.heap[largest]] = [this.heap[largest], this.heap[i]];
      i = largest;
    }
  }
}

49. Trie (Prefix Tree)

Theory: Tree keyed by characters for fast prefix queries. insert/search/startsWith
are O(L) where L = word length. Powers autocomplete and spell-check.

class TrieNode {
  constructor() {
    this.children = {};    // char -> TrieNode
    this.isEnd = false;    // marks a complete word
  }
}

class Trie {
  constructor() { this.root = new TrieNode(); }

  insert(word) {
    let node = this.root;
    for (const ch of word) {
      if (!node.children[ch]) node.children[ch] = new TrieNode();
      node = node.children[ch];
    }
    node.isEnd = true;
  }

  search(word) {
    const node = this._traverse(word);
    return node !== null && node.isEnd; // must be a full word
  }

  startsWith(prefix) {
    return this._traverse(prefix) !== null; // any node is enough
  }

  _traverse(str) {
    let node = this.root;
    for (const ch of str) {
      if (!node.children[ch]) return null;
      node = node.children[ch];
    }
    return node;
  }
}

50. LRU Cache

Theory: Fixed-capacity cache that evicts the Least Recently Used entry. A JS Map
preserves insertion order, so we can get O(1) get/put: on access, delete+reinsert to mark as
most-recent; evict the first (oldest) key when over capacity.

class LRUCache {
  constructor(capacity) {
    this.capacity = capacity;
    this.map = new Map(); // insertion order = usage order (oldest first)
  }

  get(key) {
    if (!this.map.has(key)) return -1;
    const value = this.map.get(key);
    this.map.delete(key);      // remove...
    this.map.set(key, value);  // ...and re-add to mark as most recent
    return value;
  }

  put(key, value) {
    if (this.map.has(key)) this.map.delete(key); // refresh position
    else if (this.map.size >= this.capacity) {
      // Evict least recently used = first key in the Map.
      this.map.delete(this.map.keys().next().value);
    }
    this.map.set(key, value);
  }
}

const lru = new LRUCache(2);
lru.put(1, 1); lru.put(2, 2);
lru.get(1);         // 1 (now 1 is most recent)
lru.put(3, 3);      // evicts key 2
console.log(lru.get(2)); // -1

All ops O(1). Follow-up: implement with a hash map + doubly linked list (no Map).

51. LFU Cache

Theory: Evicts the Least Frequently Used entry; ties broken by least-recently-used.
Maintain per-key frequency and, for each frequency, an ordered bucket of keys. O(1) get/put.

class LFUCache {
  constructor(capacity) {
    this.capacity = capacity;
    this.keyToVal = new Map();          // key -> value
    this.keyToFreq = new Map();         // key -> frequency
    this.freqToKeys = new Map();        // freq -> Map(key->true) preserving order
    this.minFreq = 0;
  }

  _touch(key) {
    // Move key from its current freq bucket to freq+1.
    const freq = this.keyToFreq.get(key);
    const bucket = this.freqToKeys.get(freq);
    bucket.delete(key);
    if (bucket.size === 0) {
      this.freqToKeys.delete(freq);
      if (this.minFreq === freq) this.minFreq++; // bumped the lowest bucket
    }
    const nextFreq = freq + 1;
    this.keyToFreq.set(key, nextFreq);
    if (!this.freqToKeys.has(nextFreq)) this.freqToKeys.set(nextFreq, new Map());
    this.freqToKeys.get(nextFreq).set(key, true);
  }

  get(key) {
    if (!this.keyToVal.has(key)) return -1;
    this._touch(key);
    return this.keyToVal.get(key);
  }

  put(key, value) {
    if (this.capacity === 0) return;
    if (this.keyToVal.has(key)) {
      this.keyToVal.set(key, value);
      this._touch(key);
      return;
    }
    if (this.keyToVal.size >= this.capacity) {
      // Evict least-frequent, oldest key (first in the minFreq bucket).
      const bucket = this.freqToKeys.get(this.minFreq);
      const evictKey = bucket.keys().next().value;
      bucket.delete(evictKey);
      this.keyToVal.delete(evictKey);
      this.keyToFreq.delete(evictKey);
    }
    // Insert new key with frequency 1.
    this.keyToVal.set(key, value);
    this.keyToFreq.set(key, 1);
    if (!this.freqToKeys.has(1)) this.freqToKeys.set(1, new Map());
    this.freqToKeys.get(1).set(key, true);
    this.minFreq = 1; // a brand new key always resets minFreq to 1
  }
}

Level 8 — Object Manipulation

52. Flatten Object

Theory: Convert nested objects to a single level using dot-path keys.

function flattenObject(obj, prefix = "", result = {}) {
  for (const key of Object.keys(obj)) {
    const path = prefix ? `${prefix}.${key}` : key;
    const value = obj[key];
    // Recurse into plain nested objects; leaves (incl. arrays) are stored directly.
    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
      flattenObject(value, path, result);
    } else {
      result[path] = value;
    }
  }
  return result;
}

console.log(flattenObject({ a: { b: 1, c: { d: 2 } } }));
// { "a.b": 1, "a.c.d": 2 }

Design choice: how to handle arrays (index paths a.0.b vs treat as leaf).

53. Unflatten Object

Theory: Inverse of flatten — rebuild nesting from dot-path keys.

function unflattenObject(flat) {
  const result = {};
  for (const flatKey of Object.keys(flat)) {
    const keys = flatKey.split(".");
    let node = result;
    keys.forEach((key, i) => {
      if (i === keys.length - 1) {
        node[key] = flat[flatKey];      // leaf
      } else {
        node[key] = node[key] || {};    // ensure the branch exists
        node = node[key];
      }
    });
  }
  return result;
}

console.log(unflattenObject({ "a.b": 1, "a.c.d": 2 }));
// { a: { b: 1, c: { d: 2 } } }

54. Deep Equal

Theory: Structural equality — same shape and values recursively (not reference equality).

function deepEqual(a, b) {
  if (a === b) return true; // fast path incl. same reference / same primitive

  // Handle NaN (NaN !== NaN but should be "equal" here).
  if (typeof a === "number" && typeof b === "number") return a !== a && b !== b;

  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
    return false;
  }

  // Compare Date and RegExp by their meaningful value.
  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
  if (a instanceof RegExp && b instanceof RegExp) return a.toString() === b.toString();

  if (Array.isArray(a) !== Array.isArray(b)) return false;

  const keysA = Reflect.ownKeys(a);
  const keysB = Reflect.ownKeys(b);
  if (keysA.length !== keysB.length) return false;

  // Every key in `a` must exist in `b` with a deeply-equal value.
  return keysA.every((k) => keysB.includes(k) && deepEqual(a[k], b[k]));
}

console.log(deepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] })); // true

Edge cases: NaN, Date, RegExp, arrays vs objects, key count mismatch, cycles (add a seen set).

55. Diff Objects

Theory: Report which keys were added, removed, or changed between two objects.

function diffObjects(oldObj, newObj) {
  const diff = { added: {}, removed: {}, changed: {} };

  for (const key of Object.keys(newObj)) {
    if (!(key in oldObj)) {
      diff.added[key] = newObj[key];
    } else if (!deepEqual(oldObj[key], newObj[key])) {
      diff.changed[key] = { from: oldObj[key], to: newObj[key] };
    }
  }
  for (const key of Object.keys(oldObj)) {
    if (!(key in newObj)) diff.removed[key] = oldObj[key];
  }
  return diff;
}

console.log(diffObjects({ a: 1, b: 2 }, { a: 1, b: 9, c: 3 }));
// { added: { c: 3 }, removed: {}, changed: { b: { from: 2, to: 9 } } }

56. `pick`

Theory: Return a new object with only the whitelisted keys.

function pick(obj, keys) {
  const result = {};
  for (const key of keys) {
    if (key in obj) result[key] = obj[key];
  }
  return result;
}

console.log(pick({ a: 1, b: 2, c: 3 }, ["a", "c"])); // { a: 1, c: 3 }

57. `omit`

Theory: Return a new object without the blacklisted keys.

function omit(obj, keys) {
  const exclude = new Set(keys);
  const result = {};
  for (const key of Object.keys(obj)) {
    if (!exclude.has(key)) result[key] = obj[key];
  }
  return result;
}

console.log(omit({ a: 1, b: 2, c: 3 }, ["b"])); // { a: 1, c: 3 }

Level 9 — Parsing

58. Query String Parser

Theory: Turn ?a=1&b=2 into { a: "1", b: "2" }. Handle URL-decoding and repeated keys.

function parseQuery(queryString) {
  const result = {};
  // Strip a leading "?" if present, then split into pairs.
  const query = queryString.replace(/^\?/, "");
  if (!query) return result;

  for (const pair of query.split("&")) {
    const [rawKey, rawValue = ""] = pair.split("=");
    const key = decodeURIComponent(rawKey);
    const value = decodeURIComponent(rawValue);

    if (key in result) {
      // Repeated key → collect into an array.
      result[key] = [].concat(result[key], value);
    } else {
      result[key] = value;
    }
  }
  return result;
}

console.log(parseQuery("?a=1&b=2&a=3"));
// { a: ["1", "3"], b: "2" }

59. Stringify Query

Theory: Inverse of the above. URL-encode keys/values and expand arrays into repeated keys.

function stringifyQuery(obj) {
  const parts = [];
  for (const key of Object.keys(obj)) {
    const value = obj[key];
    const enc = encodeURIComponent(key);
    if (Array.isArray(value)) {
      value.forEach((v) => parts.push(`${enc}=${encodeURIComponent(v)}`));
    } else {
      parts.push(`${enc}=${encodeURIComponent(value)}`);
    }
  }
  return parts.length ? "?" + parts.join("&") : "";
}

console.log(stringifyQuery({ a: [1, 3], b: 2 })); // "?a=1&a=3&b=2"

60. Parse CSV

Theory: Split rows/columns, but respect quoted fields that may contain commas, quotes
(escaped as ""), and newlines. A tiny state machine is the robust approach.

function parseCSV(text) {
  const rows = [];
  let row = [];
  let field = "";
  let inQuotes = false;

  for (let i = 0; i < text.length; i++) {
    const char = text[i];
    const next = text[i + 1];

    if (inQuotes) {
      if (char === '"' && next === '"') { field += '"'; i++; } // escaped quote
      else if (char === '"') { inQuotes = false; }             // closing quote
      else { field += char; }
    } else {
      if (char === '"') inQuotes = true;
      else if (char === ",") { row.push(field); field = ""; }
      else if (char === "\n" || char === "\r") {
        if (char === "\r" && next === "\n") i++; // consume CRLF pair
        row.push(field); rows.push(row); row = []; field = "";
      } else field += char;
    }
  }
  // Flush the trailing field/row if the file doesn't end with a newline.
  if (field !== "" || row.length) { row.push(field); rows.push(row); }
  return rows;
}

console.log(parseCSV('a,b\n"1,x",2')); // [["a","b"],["1,x","2"]]

61. Parse JSON (simplified)

Theory: A recursive-descent parser demonstrating tokenizing + parsing. Supports objects,
arrays, strings, numbers, booleans, null. (Real JSON.parse handles all escapes/edge cases.)

function parseJSON(str) {
  let i = 0;

  function skipWhitespace() { while (/\s/.test(str[i])) i++; }

  function parseValue() {
    skipWhitespace();
    const ch = str[i];
    if (ch === "{") return parseObject();
    if (ch === "[") return parseArray();
    if (ch === '"') return parseString();
    if (ch === "t" || ch === "f") return parseBool();
    if (ch === "n") { i += 4; return null; } // "null"
    return parseNumber();
  }

  function parseObject() {
    const obj = {};
    i++; // skip "{"
    skipWhitespace();
    if (str[i] === "}") { i++; return obj; }
    while (true) {
      skipWhitespace();
      const key = parseString();
      skipWhitespace();
      i++; // skip ":"
      obj[key] = parseValue();
      skipWhitespace();
      if (str[i] === ",") { i++; continue; }
      i++; // skip "}"
      break;
    }
    return obj;
  }

  function parseArray() {
    const arr = [];
    i++; // skip "["
    skipWhitespace();
    if (str[i] === "]") { i++; return arr; }
    while (true) {
      arr.push(parseValue());
      skipWhitespace();
      if (str[i] === ",") { i++; continue; }
      i++; // skip "]"
      break;
    }
    return arr;
  }

  function parseString() {
    let result = "";
    i++; // skip opening quote
    while (str[i] !== '"') {
      if (str[i] === "\\") { i++; result += str[i]; } // naive escape handling
      else result += str[i];
      i++;
    }
    i++; // skip closing quote
    return result;
  }

  function parseNumber() {
    let start = i;
    while (/[-+0-9.eE]/.test(str[i])) i++;
    return Number(str.slice(start, i));
  }

  function parseBool() {
    if (str[i] === "t") { i += 4; return true; }
    i += 5; return false;
  }

  return parseValue();
}

console.log(parseJSON('{"a":1,"b":[true,null]}')); // { a: 1, b: [true, null] }

Level 10 — Tree / DOM Problems

62. DOM Traversal (DFS)

Theory: Visit every node depth-first (node, then its children recursively).

function domDFS(root, visit) {
  visit(root);
  // childNodes includes text nodes; use `children` for elements only.
  for (const child of root.children) {
    domDFS(child, visit);
  }
}

// Iterative version using a stack (avoids deep recursion).
function domDFSIterative(root, visit) {
  const stack = [root];
  while (stack.length) {
    const node = stack.pop();
    visit(node);
    // Push in reverse so children are visited left-to-right.
    for (let i = node.children.length - 1; i >= 0; i--) {
      stack.push(node.children[i]);
    }
  }
}

63. BFS DOM

Theory: Visit level by level using a queue. Useful for "find nearest element" style problems.

function domBFS(root, visit) {
  const queue = [root];
  while (queue.length) {
    const node = queue.shift();
    visit(node);
    for (const child of node.children) queue.push(child);
  }
}

// Common application: get max nesting depth.
function maxDepth(root) {
  if (!root) return 0;
  let depth = 0;
  let queue = [root];
  while (queue.length) {
    depth++;
    const next = [];
    for (const node of queue) next.push(...node.children);
    queue = next;
  }
  return depth;
}

64. Virtual DOM Diff (basic)

Theory: Compare two virtual node trees and produce a list of patches. A vnode is
{ type, props, children }. This is the heart of React's reconciliation (simplified —
real diffing uses keys and heuristics).

// vnode: { type: 'div', props: {...}, children: [...] }

function diff(oldNode, newNode) {
  const patches = [];

  // 1. Node removed.
  if (newNode == null) {
    patches.push({ type: "REMOVE" });
    return patches;
  }
  // 2. Text or type changed → full replace.
  if (
    typeof oldNode !== typeof newNode ||
    (typeof newNode === "string" && oldNode !== newNode) ||
    oldNode.type !== newNode.type
  ) {
    patches.push({ type: "REPLACE", node: newNode });
    return patches;
  }
  // 3. Same element type → diff props and children.
  if (newNode.type) {
    const propPatches = diffProps(oldNode.props || {}, newNode.props || {});
    if (propPatches.length) patches.push({ type: "PROPS", patches: propPatches });

    const childPatches = diffChildren(oldNode.children || [], newNode.children || []);
    if (childPatches.length) patches.push({ type: "CHILDREN", patches: childPatches });
  }
  return patches;
}

function diffProps(oldProps, newProps) {
  const changes = [];
  // Changed or added props.
  for (const key of Object.keys(newProps)) {
    if (oldProps[key] !== newProps[key]) changes.push({ key, value: newProps[key] });
  }
  // Removed props.
  for (const key of Object.keys(oldProps)) {
    if (!(key in newProps)) changes.push({ key, value: undefined });
  }
  return changes;
}

function diffChildren(oldChildren, newChildren) {
  const patches = [];
  const max = Math.max(oldChildren.length, newChildren.length);
  for (let i = 0; i < max; i++) {
    patches.push({ index: i, patches: diff(oldChildren[i], newChildren[i]) });
  }
  return patches;
}

Follow-up: keyed diffing for lists (key prop) to minimize DOM moves.

65. Render JSON → DOM

Theory: Turn a vnode/JSON tree into real DOM nodes (the "mount" step).

function createElement(vnode) {
  // Text node.
  if (typeof vnode === "string" || typeof vnode === "number") {
    return document.createTextNode(String(vnode));
  }

  const el = document.createElement(vnode.type);

  // Apply props/attributes and event handlers.
  for (const [key, value] of Object.entries(vnode.props || {})) {
    if (key.startsWith("on") && typeof value === "function") {
      el.addEventListener(key.slice(2).toLowerCase(), value); // onClick -> click
    } else {
      el.setAttribute(key, value);
    }
  }

  // Recursively mount children.
  (vnode.children || []).forEach((child) => el.appendChild(createElement(child)));
  return el;
}

// const tree = { type: 'div', props: { id: 'app' }, children: ['Hello'] };
// document.body.appendChild(createElement(tree));

Level 11 — Rate Limiting

66. Token Bucket

Theory: A bucket holds up to capacity tokens, refilled at refillRate tokens/sec.
Each request consumes one token; if empty, the request is rejected. Allows bursts up to
capacity — the classic API rate limiter.

class TokenBucket {
  constructor(capacity, refillRatePerSec) {
    this.capacity = capacity;
    this.tokens = capacity;              // start full
    this.refillRate = refillRatePerSec;
    this.lastRefill = Date.now();
  }

  _refill() {
    const now = Date.now();
    const elapsedSec = (now - this.lastRefill) / 1000;
    // Add tokens proportional to elapsed time, capped at capacity.
    this.tokens = Math.min(this.capacity, this.tokens + elapsedSec * this.refillRate);
    this.lastRefill = now;
  }

  tryConsume(count = 1) {
    this._refill();
    if (this.tokens >= count) {
      this.tokens -= count;
      return true;  // allowed
    }
    return false;   // rate limited
  }
}

const bucket = new TokenBucket(10, 1); // 10 burst, refill 1/sec
console.log(bucket.tryConsume()); // true

67. Sliding Window (Rate Limiter)

Theory: Allow at most limit requests within the trailing windowMs. Track timestamps and
drop those older than the window — smoother than fixed windows (no burst at boundaries).

class SlidingWindowRateLimiter {
  constructor(limit, windowMs) {
    this.limit = limit;
    this.windowMs = windowMs;
    this.timestamps = []; // request times within the window
  }

  allow() {
    const now = Date.now();
    const cutoff = now - this.windowMs;
    // Drop expired timestamps from the front.
    while (this.timestamps.length && this.timestamps[0] <= cutoff) {
      this.timestamps.shift();
    }
    if (this.timestamps.length < this.limit) {
      this.timestamps.push(now);
      return true;
    }
    return false;
  }
}

const rl = new SlidingWindowRateLimiter(3, 1000); // 3 per second

68. Request Queue (rate-limited)

Theory: Queue requests and release them at a controlled rate so you never exceed the limit —
requests wait rather than fail.

class RequestQueue {
  constructor(maxPerInterval, intervalMs) {
    this.maxPerInterval = maxPerInterval;
    this.intervalMs = intervalMs;
    this.queue = [];
    this.timestamps = [];
  }

  add(taskFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ taskFn, resolve, reject });
      this._process();
    });
  }

  _process() {
    const now = Date.now();
    this.timestamps = this.timestamps.filter((t) => now - t < this.intervalMs);

    if (this.timestamps.length < this.maxPerInterval && this.queue.length) {
      this.timestamps.push(now);
      const { taskFn, resolve, reject } = this.queue.shift();
      Promise.resolve(taskFn()).then(resolve, reject);
      this._process(); // try to release more within budget
    } else if (this.queue.length) {
      // Budget exhausted — retry after the oldest timestamp expires.
      const wait = this.intervalMs - (now - this.timestamps[0]);
      setTimeout(() => this._process(), wait);
    }
  }
}

Level 12 — Advanced Utilities

69. `groupBy`

Theory: Group array items into buckets keyed by a function or property name.

function groupBy(array, keySelector) {
  const getKey = typeof keySelector === "function"
    ? keySelector
    : (item) => item[keySelector];

  return array.reduce((groups, item) => {
    const key = getKey(item);
    (groups[key] ||= []).push(item); // create bucket lazily
    return groups;
  }, {});
}

console.log(groupBy([6.1, 4.2, 6.3], Math.floor)); // { 4: [4.2], 6: [6.1, 6.3] }
console.log(groupBy([{ t: "a" }, { t: "b" }, { t: "a" }], "t"));
// { a: [{t:"a"},{t:"a"}], b: [{t:"b"}] }

70. `chunk()`

Theory: Split an array into groups of size n (last chunk may be smaller).

function chunk(array, size) {
  if (size <= 0) throw new RangeError("size must be > 0");
  const result = [];
  for (let i = 0; i < array.length; i += size) {
    result.push(array.slice(i, i + size)); // slice handles the tail gracefully
  }
  return result;
}

console.log(chunk([1, 2, 3, 4, 5], 2)); // [[1,2],[3,4],[5]]

71. `zip()`

Theory: Combine multiple arrays element-wise into tuples. Length = shortest input (or longest,
padded — state your choice).

function zip(...arrays) {
  const maxLen = Math.min(...arrays.map((a) => a.length));
  const result = [];
  for (let i = 0; i < maxLen; i++) {
    result.push(arrays.map((arr) => arr[i]));
  }
  return result;
}

console.log(zip([1, 2, 3], ["a", "b", "c"])); // [[1,"a"],[2,"b"],[3,"c"]]

72. `unzip()`

Theory: Inverse of zip — turn an array of tuples back into separate arrays.

function unzip(pairs) {
  const result = [];
  for (const tuple of pairs) {
    tuple.forEach((value, i) => {
      (result[i] ||= []).push(value);
    });
  }
  return result;
}

console.log(unzip([[1, "a"], [2, "b"], [3, "c"]])); // [[1,2,3],["a","b","c"]]

73. `shuffle()`

Theory: Fisher–Yates produces a uniformly random permutation in O(n). Naive sort(() => Math.random() - 0.5) is biased — avoid it.

function shuffle(array) {
  const arr = [...array]; // don't mutate the input
  for (let i = arr.length - 1; i > 0; i--) {
    // Pick a random index j in [0, i], then swap.
    const j = Math.floor(Math.random() * (i + 1));
    [arr[i], arr[j]] = [arr[j], arr[i]];
  }
  return arr;
}

74. `sample()`

Theory: Pick k random elements without replacement (partial Fisher–Yates is efficient).

function sample(array, k = 1) {
  const arr = [...array];
  const n = Math.min(k, arr.length);
  for (let i = 0; i < n; i++) {
    const j = i + Math.floor(Math.random() * (arr.length - i));
    [arr[i], arr[j]] = [arr[j], arr[i]];
  }
  return arr.slice(0, n);
}

console.log(sample([1, 2, 3, 4, 5], 2)); // e.g. [3, 1]

75. `binarySearch()`

Theory: Find a target in a sorted array in O(log n) by halving the search range.

function binarySearch(sortedArr, target) {
  let lo = 0, hi = sortedArr.length - 1;
  while (lo <= hi) {
    const mid = (lo + hi) >> 1; // avoids overflow, integer division
    if (sortedArr[mid] === target) return mid;
    if (sortedArr[mid] < target) lo = mid + 1; // search right half
    else hi = mid - 1;                          // search left half
  }
  return -1; // not found
}

console.log(binarySearch([1, 3, 5, 7, 9], 7)); // 3

Variations: find leftmost/rightmost occurrence, first element ≥ target (lower bound).

76. `quickSort()`

Theory: Divide & conquer: pick a pivot, partition into <, =, >, recurse. Average
O(n log n), worst O(n²) (mitigated by random pivot).

function quickSort(arr) {
  if (arr.length <= 1) return arr;

  const pivot = arr[Math.floor(Math.random() * arr.length)]; // random pivot
  const less = [], equal = [], greater = [];

  for (const x of arr) {
    if (x < pivot) less.push(x);
    else if (x > pivot) greater.push(x);
    else equal.push(x);
  }
  // Recurse on the partitions and concatenate.
  return [...quickSort(less), ...equal, ...quickSort(greater)];
}

console.log(quickSort([3, 1, 4, 1, 5, 9, 2, 6])); // [1,1,2,3,4,5,6,9]

Note: the above is not in-place. Mention the Lomuto/Hoare in-place partition as a follow-up.

77. `mergeSort()`

Theory: Divide the array in half, sort each recursively, then merge. Stable, guaranteed
O(n log n), O(n) extra space.

function mergeSort(arr) {
  if (arr.length <= 1) return arr;
  const mid = arr.length >> 1;
  const left = mergeSort(arr.slice(0, mid));
  const right = mergeSort(arr.slice(mid));
  return merge(left, right);
}

function merge(left, right) {
  const result = [];
  let i = 0, j = 0;
  // Merge two sorted arrays by always taking the smaller head.
  while (i < left.length && j < right.length) {
    if (left[i] <= right[j]) result.push(left[i++]); // <= keeps it stable
    else result.push(right[j++]);
  }
  // Append leftovers.
  while (i < left.length) result.push(left[i++]);
  while (j < right.length) result.push(right[j++]);
  return result;
}

console.log(mergeSort([5, 2, 8, 1, 9])); // [1,2,5,8,9]

78. `heapSort()`

Theory: Build a max-heap, then repeatedly swap the max to the end and sift down.
In-place, O(n log n), not stable.

function heapSort(arr) {
  const n = arr.length;

  // Build max-heap from the last parent down to the root.
  for (let i = (n >> 1) - 1; i >= 0; i--) siftDown(arr, i, n);

  // Repeatedly move current max to the end, then restore the heap.
  for (let end = n - 1; end > 0; end--) {
    [arr[0], arr[end]] = [arr[end], arr[0]];
    siftDown(arr, 0, end); // heap size shrinks to `end`
  }
  return arr;
}

function siftDown(arr, i, size) {
  while (true) {
    let largest = i;
    const l = 2 * i + 1, r = 2 * i + 2;
    if (l < size && arr[l] > arr[largest]) largest = l;
    if (r < size && arr[r] > arr[largest]) largest = r;
    if (largest === i) break;
    [arr[i], arr[largest]] = [arr[largest], arr[i]];
    i = largest;
  }
}

console.log(heapSort([3, 1, 4, 1, 5, 9])); // [1,1,3,4,5,9]

79. `topK()`

Theory: Find the K largest elements. A min-heap of size K gives O(n log K) — better than
sorting (O(n log n)) when K ≪ n.

function topK(nums, k) {
  const heap = new MinHeap(); // from Level 7
  for (const num of nums) {
    heap.insert(num);
    // Keep only the K largest: if heap grows past K, drop the smallest.
    if (heap.size() > k) heap.extractMin();
  }
  const result = [];
  while (heap.size()) result.push(heap.extractMin());
  return result.reverse(); // largest first
}

console.log(topK([3, 1, 5, 12, 2, 11], 3)); // [12, 11, 5]

Alternative: Quickselect gives O(n) average for the k-th element.

80. `median()`

Theory: Middle value of a sorted list; average of the two middles for even length.
Simple version sorts (O(n log n)); Quickselect gives O(n) average.

function median(nums) {
  if (nums.length === 0) return NaN;
  const sorted = [...nums].sort((a, b) => a - b); // numeric sort, no mutation
  const mid = sorted.length >> 1;
  return sorted.length % 2 === 0
    ? (sorted[mid - 1] + sorted[mid]) / 2 // even: average the two middles
    : sorted[mid];                        // odd: the middle element
}

console.log(median([3, 1, 2]));    // 2
console.log(median([4, 1, 2, 3])); // 2.5

Streaming variation: maintain a max-heap (lower half) + min-heap (upper half) for O(log n) insertions and O(1) median — the classic "find median from data stream" problem.

Level 13 — Google Frontend Machine Coding

The Level 1–12 building blocks map directly onto these classic Google frontend rounds. Below are
the production-grade versions of the ones most likely to appear.

81. Production Debounce (leading, trailing, maxWait)

Theory: Real debounce (à la Lodash) supports firing on the leading edge, trailing edge,
and a maxWait so a continuously-called function still fires periodically.

function debounce(fn, wait, options = {}) {
  const { leading = false, trailing = true, maxWait } = options;
  let timerId = null;
  let lastCallTime = null;   // when debounced was last invoked
  let lastInvokeTime = 0;    // when fn was last actually called
  let lastArgs, lastThis, result;

  function invoke(time) {
    lastInvokeTime = time;
    result = fn.apply(lastThis, lastArgs);
    lastArgs = lastThis = null;
    return result;
  }

  function shouldInvoke(time) {
    const sinceLastCall = time - lastCallTime;
    const sinceLastInvoke = time - lastInvokeTime;
    return (
      lastCallTime === null ||           // first call
      sinceLastCall >= wait ||           // idle long enough
      sinceLastCall < 0 ||               // clock moved back
      (maxWait !== undefined && sinceLastInvoke >= maxWait) // maxWait exceeded
    );
  }

  function timerExpired() {
    const time = Date.now();
    if (shouldInvoke(time)) {
      timerId = null;
      if (trailing && lastArgs) invoke(time); // trailing edge
      return;
    }
    // Reschedule for the remaining time.
    timerId = setTimeout(timerExpired, wait - (time - lastCallTime));
  }

  function debounced(...args) {
    const time = Date.now();
    const isInvoking = shouldInvoke(time);
    lastArgs = args;
    lastThis = this;
    lastCallTime = time;

    if (isInvoking && timerId === null) {
      lastInvokeTime = time;
      timerId = setTimeout(timerExpired, wait);
      return leading ? invoke(time) : result; // leading edge
    }
    if (timerId === null) timerId = setTimeout(timerExpired, wait);
    return result;
  }

  debounced.cancel = () => { clearTimeout(timerId); timerId = null; lastCallTime = null; };
  debounced.flush = () => { if (timerId) { invoke(Date.now()); debounced.cancel(); } return result; };
  return debounced;
}

Talking points: leading vs trailing, maxWait guarantees progress, cancel/flush API.

82. Promise Scheduler with Concurrency Limit

Covered as Promise Queue (#33) and
Task Scheduler (#34). The interviewer usually wants:
new Scheduler(limit) with .add(taskFn) → Promise that resolves with the task's result while
never running more than limit tasks at once. Use the Promise Queue implementation.

83. Retry with Exponential Backoff

Theory: On failure, wait base * 2^attempt (plus optional jitter to avoid thundering herds)
before retrying. Standard for flaky network calls.

async function retryWithBackoff(fn, {
  retries = 5,
  baseDelay = 200,
  maxDelay = 5000,
  jitter = true,
} = {}) {
  let attempt = 0;
  while (true) {
    try {
      return await fn(); // success → return immediately
    } catch (err) {
      if (attempt >= retries) throw err; // exhausted → rethrow

      // Exponential delay, capped, with optional random jitter.
      let delay = Math.min(baseDelay * 2 ** attempt, maxDelay);
      if (jitter) delay = Math.random() * delay;

      await new Promise((r) => setTimeout(r, delay));
      attempt++;
    }
  }
}

// retryWithBackoff(() => fetch("/flaky"), { retries: 4 });

84. Flatten Deeply Nested Array Without Recursion

Use the explicit-stack approach from flat (#7). Restated:

function flattenNoRecursion(arr) {
  const stack = [...arr];
  const out = [];
  while (stack.length) {
    const next = stack.pop();
    if (Array.isArray(next)) stack.push(...next); // defer nested items
    else out.push(next);
  }
  return out.reverse(); // pop reverses; restore original order
}

console.log(flattenNoRecursion([1, [2, [3, [4, [5]]]]])); // [1,2,3,4,5]

85. DOM Serialization / Deserialization

Theory: Serialize a DOM node to a JSON vnode and back — round-tripping between the DOM and a
virtual representation.

// DOM element -> plain JSON vnode.
function serialize(node) {
  if (node.nodeType === Node.TEXT_NODE) return node.textContent;
  const props = {};
  for (const attr of node.attributes) props[attr.name] = attr.value;
  return {
    type: node.tagName.toLowerCase(),
    props,
    children: Array.from(node.childNodes).map(serialize),
  };
}

// JSON vnode -> DOM element (reuses createElement from #65).
function deserialize(vnode) {
  if (typeof vnode === "string") return document.createTextNode(vnode);
  const el = document.createElement(vnode.type);
  for (const [k, v] of Object.entries(vnode.props || {})) el.setAttribute(k, v);
  (vnode.children || []).forEach((c) => el.appendChild(deserialize(c)));
  return el;
}

Quick Reference — Complexity Cheat Sheet

Utility	Time (avg)	Space	Notes
map/filter/reduce	O(n)	O(n)	single pass
deepClone	O(n)	O(n)	WeakMap for cycles
debounce/throttle	O(1)/call	O(1)	one timer
Promise.all	O(n)	O(n)	fail-fast
LRU get/put	O(1)	O(cap)	Map ordering trick
Heap insert/extract	O(log n)	O(n)	array-backed
Trie op	O(L)	O(Σ·N)	L = word length
binarySearch	O(log n)	O(1)	requires sorted input
quick/merge/heap	O(n log n)	varies	merge stable, heap in-place
topK	O(n log k)	O(k)	min-heap of size k

30-Day Practice Plan

Week 1 — Fundamentals: Array methods (1–10), object utilities (11–15), bind/call/apply (24–26), debounce (16, 81), throttle (17).
Week 2 — Async & core: Promises (27–34), async utilities (35–39), EventEmitter (40), deep clone (10), deep equality (54).
Week 3 — Data structures: LRU (50) / LFU (51), heaps (47–48), tries (49), flatten/unflatten (52–53), parsers (58–61), rate limiters (66–68).
Week 4 — Machine coding: Promise scheduler (33–34), virtual DOM diff (64), task queue (33), DOM traversal (62–63), retry/backoff (83) — then do timed mock interviews.

Rule: write each from scratch, state complexity, enumerate edge cases, and test it —
no peeking. That is exactly what a Google frontend loop expects.

The Event Loop: Microtasks, Macrotasks & Output Prediction

ZeeshanAli-0704 — Sat, 04 Jul 2026 07:01:12 +0000

The Event Loop, Microtasks, Macrotasks and Output Prediction

The single most asked JavaScript question at Google, Meta, and every senior frontend loop.
Master the Call Stack, Microtask Queue, Macrotask Queue, the Rendering phase,
queueMicrotask, and MutationObserver, then you can predict the output of any snippet.

1. The Mental Model
2. Call Stack
3. Macrotask Queue
3a. WebSocket and the Event Loop
4. Microtask Queue
5. The One Rule That Solves Every Question
6. Rendering Phase and requestAnimationFrame
7. queueMicrotask
8. MutationObserver
9. Worked Output Examples
10. async await Decoded
11. Cheat Sheet and Priority Table
12. Interview Questions and Answers
13. Node.js Event Loop Phases and Special Queues
14. Promise Combinator Timing
15. await Inside Loops
16. Blocking the Main Thread and Fixing It
17. Web Workers and Their Own Event Loop

1. The Mental Model

JavaScript is single-threaded: one call stack, one thing at a time. The event loop
is the coordinator that decides what runs next when the stack is empty.

flowchart TB
    CS["Call Stack\n(runs synchronous code)"]
    MIC["Microtask Queue\n(Promises, queueMicrotask, MutationObserver)"]
    MAC["Macrotask Queue\n(setTimeout, setInterval, I/O, events)"]
    RENDER["Render\n(style, layout, paint, rAF)"]

    CS -->|stack empty| MIC
    MIC -->|drain ALL| RENDER
    RENDER -->|maybe| MAC
    MAC -->|take ONE| CS

Before the loop makes sense, you need to know the two kinds of "jobs" it juggles.
Learn them in this order: macrotask → microtask → who wins → the loop.

Step 1: What is a Macrotask?

A macrotask is a big, standalone job scheduled by the browser. Think of it as
"one full run of a callback." The initial <script> is a macrotask, and so is each
timer/event callback.

setTimeout(() => console.log("I am a macrotask"), 0);
button.addEventListener("click", () => {}); // each click = one macrotask

Common macrotask sources: setTimeout, setInterval, DOM events (click, scroll),
network/I/O callbacks, MessageChannel.

Rule: the loop runs only ONE macrotask per turn.

Step 2: What is a Microtask?

A microtask is a small, urgent follow-up job, mostly things related to Promises.
It is meant to run as soon as the current code finishes, before the browser moves on
to anything else.

Promise.resolve().then(() => console.log("I am a microtask"));
queueMicrotask(() => console.log("also a microtask"));

Common microtask sources: Promise.then / catch / finally, await (the code after it),
queueMicrotask, MutationObserver.

Rule: the loop runs ALL microtasks per turn, and any microtask added while
draining also runs in the same turn.

Step 3: Who Wins? (Priority)

When the call stack empties, the loop always follows this priority:

1. Synchronous code   (runs first, top to bottom)
2. ALL microtasks     (drain the whole queue)
3. Render             (maybe paint the screen)
4. ONE macrotask      (then go back to step 2)

Microtasks always beat macrotasks. A Promise.then always runs before a
setTimeout(…, 0), even though both were "scheduled for later."

Step 4: The Loop, With an Example

The loop repeats forever: run one macrotask → drain all microtasks → maybe render → repeat.

console.log("A");                                  // sync
setTimeout(() => console.log("B"), 0);             // macrotask
Promise.resolve().then(() => console.log("C"));    // microtask
console.log("D");                                  // sync

Walk it through with the priority list:

Phase	What runs	Output so far
Sync code	`console.log("A")`	`A`
Sync code	schedule `B` (macrotask), schedule `C` (microtask)	`A`
Sync code	`console.log("D")`	`A D`
Stack empty → drain microtasks	`C`	`A D C`
Take one macrotask	`B`	`A D C B`

Output: A D C B

That is the entire skill: label each line as sync / micro / macro, then apply
"sync first, all micro next, one macro last." Everything below is just practice.

2. Call Stack

The call stack tracks the currently executing function. Synchronous code runs
top-to-bottom, frames pushed on call and popped on return.

function a() { b(); }
function b() { console.log("hello"); }
a();

push a() ─► push b() ─► console.log ─► pop b ─► pop a ─► stack empty

Nothing from any queue runs until the stack is completely empty. This is why a long
synchronous loop freezes the page, timers, promises, clicks, everything waits.

3. Macrotask Queue

A macrotask (a.k.a. "task") is a discrete unit of work scheduled by the host.

Source	Notes
`setTimeout` / `setInterval`	Even `setTimeout(fn, 0)` waits for the next tick + min clamp (~4ms nested)
`setImmediate`	Node.js only
`MessageChannel` / `postMessage`	Fast macrotask, used by libraries
DOM events	`click`, `scroll`, `input` dispatched from user actions
I/O, network callbacks	Host-driven
`requestIdleCallback`	Runs in idle periods

Only one macrotask is processed per event-loop iteration. After it finishes, the
microtask queue is fully drained before the next macrotask.

3a. WebSocket and the Event Loop

WebSocket does not add a new queue. Its network traffic is handled off the main
thread by the browser's networking layer; when something happens (connection opens, a
message arrives, it closes, or errors), the browser queues a macrotask that dispatches
the corresponding event. Your handler runs like any other macrotask, only once the call
stack is empty and it is that task's turn.

const ws = new WebSocket("wss://example.com");

ws.onopen    = () => console.log("open");      // macrotask
ws.onmessage = (e) => console.log(e.data);      // macrotask (one PER message)
ws.onerror   = () => console.log("error");     // macrotask
ws.onclose   = () => console.log("close");     // macrotask

flowchart LR
    NET["Network layer\n(off main thread)"] -->|frame received| MAC["Macrotask queue\n(message event)"]
    MAC -->|stack empty + its turn| CS["onmessage handler\nruns on call stack"]
    CS -->|handler done| MICRO["drain microtasks"]
    MICRO --> NEXT["next macrotask\n(next message)"]

Key facts for output prediction

Fact	Consequence
Each `open`/`message`/`close`/`error` = one macrotask	Behaves like a `setTimeout` callback: runs after sync code + full microtask drain
Microtasks still win	A `Promise.then` from sync code runs before a pending `onmessage`
One message handled per tick	100 messages → 100 macrotasks, each with a microtask drain + possible paint between them
Handler blocks the loop	A slow `onmessage` freezes the UI and delays later messages; offload heavy parsing to a Web Worker
Fast producer, slow consumer	Messages back up in the task queue if handlers can't keep pace, batch or process in a worker

Mental model: a WebSocket is just a stream of macrotasks. Everything you know about
setTimeout ordering applies directly to onmessage.

4. Microtask Queue

A microtask is a short job that must run before the browser does anything else
(before rendering, before the next macrotask).

Source	Notes
`Promise.then / catch / finally`	Callback queued when the promise settles
`await` continuation	Everything after `await` is a microtask
`queueMicrotask(fn)`	Direct API to enqueue a microtask
`MutationObserver` callback	Fires as a microtask after DOM mutations

Key property: after each macrotask, the loop drains the entire microtask queue, and if
a microtask schedules another microtask, that one runs in the same drain cycle.

A microtask that keeps queueing microtasks can starve rendering and macrotasks forever.

5. The One Rule That Solves Every Question

1. Run all synchronous code (the current macrotask).
2. Empty the ENTIRE microtask queue.
3. Render if needed.
4. Take ONE macrotask. Go to 2.

Apply it mechanically:

console.log("1");                       // sync
setTimeout(() => console.log("2"), 0);  // macrotask
Promise.resolve().then(() => console.log("3")); // microtask
console.log("4");                       // sync

Trace:

Sync run: 1, schedule timeout, schedule promise, 4.
Stack empty → drain microtasks: 3.
Take one macrotask: 2.

Output: 1 4 3 2

6. Rendering Phase and requestAnimationFrame

The browser tries to paint at ~60fps (every ~16.6ms). Rendering happens between
macrotasks, but only after the microtask queue is empty.

flowchart LR
    MAC["1 macrotask"] --> MIC["drain ALL microtasks"]
    MIC --> RAF["requestAnimationFrame callbacks"]
    RAF --> STYLE["style + layout + paint"]
    STYLE --> NEXT["next macrotask"]

Ordering facts to memorize:

requestAnimationFrame runs just before paint, after microtasks, before layout/paint.
It is not a macrotask and not a microtask, it belongs to the render steps.
A microtask scheduled inside a rAF callback runs before the paint that follows it.
The browser may skip rendering entirely if nothing is dirty or the tab is hidden.

console.log("script start");
requestAnimationFrame(() => console.log("rAF"));
Promise.resolve().then(() => console.log("microtask"));
setTimeout(() => console.log("timeout"), 0);
console.log("script end");

Typical output: script start → script end → microtask → rAF → timeout
(rAF before timeout because the render step precedes the next macrotask; exact rAF
timing depends on when a frame is due).

Deep Dive: How the Browser Scheduler Decides When to Render

The event loop does not paint after every macrotask. Painting is expensive, so the
browser coalesces work and repaints on a display-synchronized cadence (VSync),
typically every ~16.67ms on a 60Hz screen (or ~6.94ms on 144Hz). This target interval
is the frame budget: everything, your JS, style, layout, paint, must fit inside it or
the frame is dropped (visible as jank/stutter).

Frame budget on a 60Hz display ≈ 16.67ms

|◄──────────────── one frame (16.67ms) ────────────────►|
| JS (tasks + microtasks) | rAF | style | layout | paint |
         you control this ▲          browser owns this ▲

The full "frame" sequence the browser runs when it decides a frame is due:

flowchart TB
    A["Run a macrotask\n(e.g. input, timer)"] --> B["Drain ALL microtasks"]
    B --> C{"Is a frame due?\n(VSync tick reached)"}
    C -->|no| A
    C -->|yes| D["requestAnimationFrame callbacks"]
    D --> E["Run ResizeObserver / IntersectionObserver"]
    E --> F["Recalculate style"]
    F --> G["Layout (reflow)"]
    G --> H["Paint + Composite"]
    H --> A

Key scheduler facts (senior-interview level):

Concept	What it means
VSync alignment	Repaints are aligned to the monitor's refresh signal, not to your JS. `rAF` fires right before this render step.
Frame budget (~16.67ms)	If JS + style + layout + paint exceed the budget, the frame is missed → FPS drops below 60.
rAF is render-phase, not a queue	It is not a macrotask or microtask. Its callbacks run once per frame, immediately before style/layout/paint.
Coalescing	Multiple `setTimeout`s or events between frames do not each trigger a paint; the browser paints at most once per VSync.
Throttling when hidden	In a background tab, `rAF` stops firing and timers are clamped (≥1s), the browser skips rendering entirely to save power.
Off-main-thread compositing	Transforms/opacity animations can be composited on the GPU thread, avoiding main-thread layout/paint, this is why `transform` animates smoother than `top/left`.

Why `requestAnimationFrame` Is Different From Both Queues

requestAnimationFrame((timestamp) => {
  // timestamp = high-res time of THIS frame's render start (shared by all rAF cbs)
});

Timing: runs after microtasks are drained, once per frame, synchronized to the display, right before layout/paint. A microtask runs many times per frame; a macrotask is unrelated to frames.
Purpose: it is the only correct place to make visual changes, because your DOM writes land just before the browser lays out and paints, so they show up in the very next frame with no wasted intermediate paint.
Batching: all rAF callbacks scheduled for a frame receive the same timestamp, and run back-to-back before a single paint, ideal for animation loops.

function animate(now) {
  moveBox(now);                 // mutate DOM here (write phase)
  requestAnimationFrame(animate); // schedule next frame
}
requestAnimationFrame(animate);

How Browsers Avoid Jank (and How You Help)

Jank = a frame that misses its budget, so the screen doesn't update on time.

Keep main-thread work per frame under ~5–10ms to leave room for the browser's own style/layout/paint within the ~16.67ms budget.
Avoid layout thrashing: batch DOM reads then writes. Interleaving read → write → read forces synchronous reflows (forced layout / "layout thrashing").

  // BAD: read, write, read, write → multiple forced reflows
  el.style.width = el.offsetWidth + 10 + "px";
  // GOOD: read all, then write all
  const w = el.offsetWidth;          // read
  requestAnimationFrame(() => {      // write in the frame's render step
    el.style.width = w + 10 + "px";
  });

Prefer transform / opacity for animation, they can skip layout & paint and run on the compositor thread.
Chunk long tasks so a single macrotask never blocks a frame. Yield with setTimeout, MessageChannel, or the modern scheduler.postTask() / scheduler.yield() APIs; use isInputPending() to yield when the user is interacting.
Do heavy work off-thread in a Web Worker so the main thread stays free to render.

Mental model for interviews: microtasks and macrotasks decide what runs, but the
display's VSync decides when the browser paints. requestAnimationFrame is your hook
into that render cadence, run once per frame, right before layout and paint, so your
visual updates land in sync with the screen instead of causing extra, wasted repaints.

7. queueMicrotask

queueMicrotask(fn) is the explicit, purpose-built way to schedule a microtask,
without the overhead or semantics of creating a promise.

queueMicrotask(() => console.log("runs as a microtask"));

Why prefer it over Promise.resolve().then(...):

Aspect	`queueMicrotask`	`Promise.resolve().then`
Intent	Explicit "schedule a microtask"	Side effect of promise chaining
Allocation	No promise object	Allocates a promise
Error handling	Throws become uncaught (reported to global)	Swallowed into rejected promise
Ordering	Same microtask queue, FIFO	Same microtask queue, FIFO

Use it to defer work until after the current synchronous block but before rendering
or timers, e.g. batching state updates while preserving synchronous-looking order.

console.log("A");
queueMicrotask(() => console.log("B"));
console.log("C");
// Output: A C B

8. MutationObserver

What Is It?

MutationObserver is a built-in browser API that watches an element for DOM changes
and notifies you asynchronously when they happen. Instead of you repeatedly polling the
DOM ("did anything change yet?"), you register a callback once and the browser calls it
whenever the parts of the DOM you asked about are modified.

const observer = new MutationObserver((mutations) => {
  // called after the DOM changes you subscribed to
});

observer.observe(targetNode, {
  childList: true,    // nodes added/removed
  attributes: true,   // attribute changes (class, style, data-*, ...)
  characterData: true,// text content changes
  subtree: true,      // also watch all descendants
});

observer.disconnect(); // stop watching when you're done (avoid leaks)

What Is It Used For?

Use case	Why `MutationObserver`
Reacting to DOM you don't control	Third-party widgets, ads, or CMS content inject nodes, observe and adapt
Detecting when an element appears	Wait for a lazily-rendered node before running code on it
Auto-resize / re-layout	Recompute sizes when children are added/removed
Syncing state to DOM edits	e.g. a rich-text editor reacting to `contenteditable` changes
Framework internals & testing	Detect when components mount/unmount; test utilities wait for DOM to settle
Enforcing invariants	Re-apply an attribute/class if something external strips it

Why It Belongs in an Event-Loop Discussion

MutationObserver watches DOM changes (child list, attributes, text) and invokes its
callback as a microtask, batching all mutations since the last delivery.

const target = document.getElementById("box");

const observer = new MutationObserver((mutations) => {
  console.log("mutations:", mutations.length); // microtask
});

observer.observe(target, { childList: true, attributes: true, subtree: true });

target.setAttribute("data-x", "1");
target.appendChild(document.createElement("span"));
console.log("sync done");

// Output:
// sync done
// mutations: 2   ← batched, delivered as ONE microtask

Why it matters for output prediction:

The callback is a microtask, so it runs in the same drain cycle as promises.
Multiple synchronous mutations are coalesced into a single callback invocation.
It runs before setTimeout and before the next paint.

Historically (pre-queueMicrotask), libraries abused MutationObserver on a dummy text
node just to get a fast microtask, that trick is now obsolete, use queueMicrotask.

9. Worked Output Examples

Example A, microtasks jump the timer queue

console.log("start");

setTimeout(() => console.log("timeout 1"), 0);

Promise.resolve()
  .then(() => console.log("promise 1"))
  .then(() => console.log("promise 2"));

setTimeout(() => console.log("timeout 2"), 0);

console.log("end");

Trace:

Sync: start, end (both timeouts + promise chain scheduled).
Drain microtasks: promise 1, then its .then queues → promise 2.
Macrotask 1: timeout 1.
Macrotask 2: timeout 2.

Output:

start
end
promise 1
promise 2
timeout 1
timeout 2

Example B, nested microtask inside a macrotask

setTimeout(() => {
  console.log("timeout");
  Promise.resolve().then(() => console.log("inner promise"));
}, 0);

Promise.resolve().then(() => console.log("outer promise"));

console.log("sync");

Output:

sync
outer promise
timeout
inner promise

The inner promise is queued inside the timeout macrotask, so its microtask drains
immediately after that macrotask, before any later macrotask.

Example C, `queueMicrotask` vs Promise ordering (FIFO)

queueMicrotask(() => console.log("mt 1"));
Promise.resolve().then(() => console.log("promise"));
queueMicrotask(() => console.log("mt 2"));

Output: mt 1 → promise → mt 2 (single queue, strict FIFO by scheduling order).

Example D, microtask starvation vs macrotask

setTimeout(() => console.log("macrotask"), 0);

function loopMicro(n) {
  if (n === 0) return;
  queueMicrotask(() => {
    console.log("micro", n);
    loopMicro(n - 1);
  });
}
loopMicro(3);

Output: micro 3 → micro 2 → micro 1 → macrotask
(all microtasks drain, recursively, before the single macrotask).

Example E, the classic `async`/`await` + timer mix

console.log("1");

setTimeout(() => console.log("2"), 0);

async function run() {
  console.log("3");
  await Promise.resolve();
  console.log("4");
}
run();

Promise.resolve().then(() => console.log("5"));

console.log("6");

Trace:

Sync: 1, schedule timeout, call run() → 3 (up to await), schedule promise 5, 6.
The code after await (4) is queued as a microtask first, then 5.
Drain microtasks in FIFO order: 4, then 5.
Take one macrotask: 2.

Output:

Example F, `Promise.resolve` in a value vs a `.then`

console.log("start");

Promise.resolve().then(() => console.log("A")).then(() => console.log("B"));

Promise.resolve().then(() => console.log("C")).then(() => console.log("D"));

console.log("end");

Two chains are drained in lockstep: each .then re-queues onto the back of the
microtask queue, so the ticks interleave rather than one chain finishing first.

Trace:

Sync: start, end. Queue has A, C.
Tick: A runs → queues B. C runs → queues D. Queue now B, D.
Tick: B, then D.

Output:

start
end
A
C
B
D

WebSocket examples

These assume the socket is already open and messages/handlers are ready to fire. Remember:
onmessage is a macrotask, so microtasks always jump ahead of it.

Example G, microtask beats an incoming message

console.log("sync start");

ws.onmessage = () => console.log("ws message");

Promise.resolve().then(() => console.log("promise"));

console.log("sync end");

Assuming a message is already queued when this script runs:

Trace:

Sync: sync start, register handler, schedule promise, sync end.
Stack empty → drain microtasks: promise.
Take one macrotask (the message): ws message.

Output:

sync start
sync end
promise
ws message

Example H, each message is a separate macrotask

let count = 0;
ws.onmessage = () => {
  count++;
  console.log("message", count);
  Promise.resolve().then(() => console.log("  after", count));
};
// Three frames arrive back-to-back.

Each message runs as its own macrotask, and its microtask drains before the next
message is processed:

Output:

message 1
  after 1
message 2
  after 2
message 3
  after 3

Not message 1 message 2 message 3 then all the afters, because the microtask queue is
emptied after each macrotask.

Example I, message vs `setTimeout` ordering

setTimeout(() => console.log("timeout"), 0);
ws.onmessage = () => console.log("ws message");
Promise.resolve().then(() => console.log("promise"));
console.log("sync");

First, the guaranteed part:

sync prints (synchronous code).
promise prints next (microtasks drain before any macrotask).
ws message and timeout are both macrotasks, so they come last.

Now the part people get wrong, why ws message before timeout? It is not a
priority rule; both are equal-priority macrotasks. It comes down to which task landed in
the queue first:

setTimeout(fn, 0) is not actually 0ms. The browser clamps it to a minimum (~4ms, and more if nested/throttled). The timer callback is only enqueued after that delay elapses.
A WebSocket message is enqueued the moment the frame arrives from the network.

So if the socket already has a message waiting (or one arrives within those few
milliseconds), that macrotask is sitting in the queue before the timer's delay is up,
and the loop takes it first.

Output (message already queued before the ~4ms timer elapses):

sync
promise
ws message
timeout

Flip it: if no message has arrived yet and the 4ms passes first, you'd get timeout
then ws message. The order of two macrotasks is decided purely by enqueue time,
not by type. Only the sync-then-microtask part is guaranteed.

Example J, a slow handler blocks everything

ws.onmessage = () => {
  const end = Date.now() + 200;
  while (Date.now() < end) {}   // 200ms of blocking work
  console.log("processed");
};

While this handler runs, nothing else happens: no other message is processed, no
promise resolves, no frame paints, the tab appears frozen for 200ms. Fix by chunking the
work or moving parsing into a Worker:

const worker = new Worker("parse.js");
ws.onmessage = (e) => worker.postMessage(e.data); // hand off, stay responsive
worker.onmessage = (e) => render(e.data);          // still a macrotask, but cheap

Example K, `queueMicrotask` that spawns a timer and a microtask

console.log(1);

setTimeout(() => console.log(2));

queueMicrotask(() => {
  console.log(3);
  setTimeout(() => console.log(4));
  Promise.resolve().then(() => {
    console.log(5);
  });
});

Promise.resolve().then(() => {
  console.log(6);
});

console.log(7);

Trace:

Sync: 1, schedule timer 2 (macrotask), queue microtask M1 (the block), queue microtask M2 (6), 7. → prints 1, 7.
Drain microtasks (FIFO: M1, then M2):
- M1: 3; schedules timer 4 (macrotask, goes after timer 2); queues microtask M3 (5) onto the back. → prints 3. Queue now: [M2, M3].
- M2: 6.
- M3: 5.
Macrotasks (in enqueue order): timer 2, then timer 4. → prints 2, 4.

Output:

Key takeaways:

The microtask spawned inside M1 (5) still runs in the same drain, but after the already-queued 6, because it joins the back of the queue.
The timer scheduled inside a microtask (4) is a macrotask, so it waits until after every microtask and after the earlier timer (2).

10. async await Decoded

await X is syntactic sugar: everything after the await becomes a microtask
continuation that runs once X settles.

async function foo() {
  console.log("foo start");
  await null;                 // suspends here → rest is a microtask
  console.log("foo end");
}

console.log("script start");
foo();
Promise.resolve().then(() => console.log("promise"));
console.log("script end");

Trace:

script start
foo start (runs synchronously up to the await)
script end
Microtasks in order queued: foo end, then promise

Output:

script start
foo start
script end
foo end
promise

Rule of thumb: split every async function at each await. Code before the first
await is synchronous, each subsequent chunk is a separate microtask.

11. Cheat Sheet and Priority Table

Execution priority when the stack empties (highest first):

Priority	Category	Examples
1	Synchronous	Current call stack code
2	Microtasks (all)	`Promise.then`, `await`, `queueMicrotask`, `MutationObserver`
3	Render steps	`requestAnimationFrame`, style, layout, paint
4	Macrotask (one)	`setTimeout`, `setInterval`, DOM events, I/O, `MessageChannel`

Golden rules:

Stack must be empty before any queue runs.
All microtasks drain per tick; only one macrotask runs per tick.
Microtasks scheduled during a drain run in the same drain cycle.
requestAnimationFrame runs after microtasks, before paint, and before the next macrotask.
setTimeout(fn, 0) is not immediate, minimum ~4ms clamp when nested.
Infinite microtask chains starve rendering and timers.

12. Interview Questions and Answers

Q1. Why does a promise callback run before setTimeout(fn, 0)?
Because promise callbacks are microtasks, and the entire microtask queue drains after the
current task and before the next macrotask. setTimeout schedules a macrotask, which is
lower priority.

Q2. Difference between queueMicrotask and Promise.resolve().then?
Both enqueue onto the same microtask queue with FIFO ordering. queueMicrotask is explicit,
allocates no promise, and surfaces thrown errors to the global handler instead of turning
them into a rejected promise.

Q3. Is requestAnimationFrame a macrotask or microtask?
Neither. It is part of the browser's render steps, running after microtasks are drained
and just before layout/paint, at most once per frame.

Q4. When does a MutationObserver callback fire?
As a microtask, after the current synchronous code, batching all DOM mutations since the
last delivery into a single invocation, before rendering and before macrotasks.

Q5. Can microtasks block rendering?
Yes. Because all microtasks (including ones scheduled during the drain) must finish before
rendering, an ever-growing microtask chain starves the render step and freezes the UI.

Q6. Predict the output:

console.log(1);
setTimeout(() => console.log(2));
queueMicrotask(() => console.log(3));
Promise.resolve().then(() => console.log(4));
console.log(5);

Answer: 1 5 3 4 2 — sync (1,5), microtasks FIFO (3,4), then the macrotask (2).

13. Node.js Event Loop Phases and Special Queues

Everything above describes the browser event loop. Node.js uses libuv and has a
different, phase-based loop. Knowing this split is a big interview differentiator.

The Six Phases

Each full turn of the Node loop walks through these phases in order; each phase has its
own callback queue that it drains before moving on.

flowchart TB
    T["1. timers\nexpired setTimeout / setInterval"] --> P["2. pending callbacks\nsome deferred system/IO callbacks"]
    P --> I["3. idle / prepare\n(internal use only)"]
    I --> POLL["4. poll\nretrieve new I/O events; run I/O callbacks"]
    POLL --> CH["5. check\nsetImmediate callbacks"]
    CH --> CL["6. close callbacks\ne.g. socket.on('close')"]
    CL --> T

Phase	What runs here
timers	Callbacks whose `setTimeout` / `setInterval` delay has elapsed
pending callbacks	A few system operations' callbacks deferred from the previous loop
idle / prepare	Internal only
poll	The heart: waits for and processes I/O (file, network) callbacks
check	`setImmediate` callbacks, run right after poll
close	`close` events (e.g. `socket.on('close', ...)`)

The Two Special Queues: `process.nextTick` and Promises

Node has two microtask-like queues that run between every phase (and after each
individual callback), not tied to any single phase:

process.nextTick queue — highest priority, drained first.
Promise microtask queue — (.then / await / queueMicrotask), drained after the nextTick queue.

After EACH callback (and between phases), Node drains, in this order:
   1. the ENTIRE process.nextTick queue
   2. the ENTIRE Promise microtask queue
then it continues to the next callback / phase.

process.nextTick beats Promises. This is the Node-specific twist: nextTick
callbacks run before any promise callback, and both run before the loop advances to the
next phase. Recursively queuing nextTick can starve the I/O loop entirely.

Priority Order (Node)

1. Synchronous code
2. process.nextTick queue      (drained fully)
3. Promise microtask queue     (drained fully)
4. Current phase's macrotask callbacks (timers / poll / check / ...)
   → then repeat 2–3 before the next callback/phase

Worked Example: `nextTick` vs Promise vs timers vs `setImmediate`

console.log("1: sync start");

setTimeout(() => console.log("2: setTimeout"), 0);
setImmediate(() => console.log("3: setImmediate"));

Promise.resolve().then(() => console.log("4: promise"));
process.nextTick(() => console.log("5: nextTick"));

console.log("6: sync end");

Trace:

Sync: 1, schedule timer, schedule immediate, queue a promise, queue a nextTick, 6.
Stack empty → drain nextTick first: 5.
Drain Promise microtasks: 4.
Enter phases: timers phase runs the elapsed timer: 2.
check phase runs setImmediate: 3.

Output:

1: sync start
6: sync end
5: nextTick
4: promise
2: setTimeout
3: setImmediate

`setTimeout(fn, 0)` vs `setImmediate` — the classic "it depends"

setTimeout(() => console.log("timeout"), 0);
setImmediate(() => console.log("immediate"));

At the top level, the order is not guaranteed — it depends on how fast the process
starts relative to the ~1ms timer threshold, so you may see either order.

But inside an I/O callback (the poll phase), setImmediate always wins, because the
check phase comes immediately after poll, whereas the next timers phase is a
full loop away:

const fs = require("fs");
fs.readFile(__filename, () => {
  setTimeout(() => console.log("timeout"), 0);
  setImmediate(() => console.log("immediate"));
});
// Always: immediate → timeout

Node vs Browser, Key Differences

	Browser	Node.js
Model	One task queue + one microtask queue + render steps	Phase-based libuv loop (timers/poll/check/…)
Highest priority	Microtasks (Promises)	`process.nextTick`, then Promises
"Run after I/O, this loop"	—	`setImmediate` (check phase)
Rendering	`requestAnimationFrame` + paint	No rendering (server)
Microtask drain	After each macrotask	After each callback and between phases

Interview soundbite: In Node, process.nextTick > Promise microtasks > the current
phase's callbacks. setImmediate (check phase) beats setTimeout(0) (timers phase) when
scheduled from within an I/O callback.

14. Promise Combinator Timing

The combinators (Promise.all, race, allSettled, any) don't settle synchronously.
Each one attaches its own .then internally to every input promise, so resolving the
combined promise costs extra microtask ticks. This is a classic hard output question.

The core rule

A combinator's .then fires after the .thens of its already-resolved inputs,
because the combinator itself must first observe each input settle (one microtask hop),
then settle its own promise (another hop).

Example: `Promise.all` vs a direct `.then`

const a = Promise.resolve("a");
const b = Promise.resolve("b");

Promise.all([a, b]).then(() => console.log("all done"));

a.then(() => console.log("a then"));
b.then(() => console.log("b then"));

console.log("sync");

Trace (by microtask tick):

Sync: sync. Promise.all internally attaches .then to a and b.
Tick 1: a then, b then run (direct handlers). Internally, all also records that a and b are now fulfilled, on the second of these it schedules its own resolution.
Tick 2: Promise.all's combined promise resolves → its .then runs: all done.

Output:

sync
a then
b then
all done

all done lands after the individual .thens, even though every input was already
resolved, because the combinator needs an extra tick to settle.

`Promise.race` — settles on the first input, still one hop

const fast = Promise.resolve("fast");
const slow = new Promise((r) => setTimeout(r, 100, "slow"));

Promise.race([fast, slow]).then((v) => console.log("race:", v));
fast.then((v) => console.log("fast:", v));
console.log("sync");

Output:

sync
fast: fast
race: fast

race mirrors the first settled input (fast), but its .then still runs one tick after
fast's own .then. The slow timer never affects the result.

`allSettled` — never rejects, waits for all to settle

const ok  = Promise.resolve(1);
const bad = Promise.reject("boom");

Promise.allSettled([ok, bad]).then((results) => console.log(results));
console.log("sync");

Output:

sync
[
  { status: "fulfilled", value: 1 },
  { status: "rejected", reason: "boom" }
]

Unlike all (which rejects the moment any input rejects), allSettled waits for every
input to settle and resolves with a status array, so no .catch is needed.

Combinator cheat sheet

Combinator	Settles when	On rejection	Extra ticks
`Promise.all`	all fulfill	rejects on first rejection	+1 tick after inputs settle
`Promise.allSettled`	all settle (never rejects)	included as `{status:'rejected'}`	+1 tick after all settle
`Promise.race`	first to settle (fulfill or reject)	rejects if first settles as rejected	+1 tick after first settles
`Promise.any`	first to fulfill	rejects only if all reject (`AggregateError`)	+1 tick after first fulfills

15. await Inside Loops

How you loop over async work changes whether it runs sequentially or in parallel, and
how many microtask ticks it costs. A frequent "why is my code slow / out of order" question.

`for…of` + `await` — sequential (one at a time)

async function sequential(urls) {
  for (const url of urls) {
    const res = await fetch(url); // waits for THIS before starting the next
    console.log(res);
  }
}

Each iteration suspends the whole loop until its await settles.
Total time ≈ sum of all requests (request 2 doesn't start until request 1 finishes).
Order is preserved. Use this when each step depends on the previous one.

`.map` + `await` — parallel (all at once)

async function parallel(urls) {
  const promises = urls.map((url) => fetch(url)); // all fetches START immediately
  const results = await Promise.all(promises);     // then wait for all together
  results.forEach((r) => console.log(r));
}

.map fires every fetch synchronously (no await between them), so requests run concurrently.
Total time ≈ the slowest single request, not the sum.
Use this when the steps are independent.

Common bug: array.forEach(async (x) => { await ... }) does not wait, forEach
ignores the returned promises, so the outer function continues before they settle. Use
for…of (sequential) or map + Promise.all (parallel) instead.

Tick / ordering example

async function run() {
  for (const n of [1, 2, 3]) {
    await Promise.resolve();
    console.log("loop", n);
  }
}

run();
Promise.resolve()
  .then(() => console.log("A"))
  .then(() => console.log("B"))
  .then(() => console.log("C"));

Each await in the loop costs one microtask tick, interleaving with the outer chain:

Output:

loop 1
A
loop 2
B
loop 3
C

Why it interleaves, step by step. Both the async loop and the .then chain feed the
same microtask queue, and each advances only one step per tick, so they take turns.

After the synchronous code runs:

run() executes until its first await (n=1), which suspends the function and queues the rest of that iteration (console.log("loop", 1) + continue) as microtask R1.
Promise.resolve().then(A) queues A. The chained .then(B) / .then(C) are not queued yet, a chained .then is only scheduled after its previous one runs.

So the queue starts as [R1, A] (R1 first because run() was called before the chain).

Tick	Runs	Prints	Queues next	Queue after
1	R1	`loop 1`	hits next `await` (n=2) → R2	`[A, R2]`
2	A	`A`	`.then` resolves → B	`[R2, B]`
3	R2	`loop 2`	hits next `await` (n=3) → R3	`[B, R3]`
4	B	`B`	`.then` resolves → C	`[R3, C]`
5	R3	`loop 3`	loop ends, `run()` finishes	`[C]`
6	C	`C`	—	`[]`

Neither side can "run ahead": every await sends the loop's next chunk to the back of
the queue, and every .then only schedules its successor after it runs, so they
alternate perfectly, one loop, one letter, one loop, one letter.

Caveat: this clean 1:1 interleave works because await Promise.resolve() costs exactly
one tick in modern engines. Two awaits per iteration would advance the chain two
links per loop step instead.

The loop and the .then chain advance one tick at a time, in lockstep, because both
feed the same microtask queue.

Which to use

Goal	Pattern
Steps depend on each other / run in order	`for…of` + `await` (sequential)
Independent steps, want them concurrent	`.map()` + `await Promise.all(...)`
Concurrent but tolerate failures	`.map()` + `await Promise.allSettled(...)`
❌ Never	`forEach(async …)` — it doesn't await

16. Blocking the Main Thread and Fixing It

The main thread runs your JS and does layout/paint. A single long task blocks
everything, no clicks, no scroll, no paint, until it finishes. A task over 50ms is
officially a "long task" and hurts responsiveness (INP).

The problem

// ❌ Blocks the thread for the whole loop — the page freezes.
function processAll(items) {
  for (const item of items) heavyWork(item); // e.g. 100k items
}

While this runs: no frame paints, input handlers queue up, the tab appears frozen.

Fix 1: Chunk the work (yield between batches)

Split the work into slices and yield to the event loop between them so the browser can
paint and handle input:

async function processInChunks(items, chunkSize = 500) {
  for (let i = 0; i < items.length; i += chunkSize) {
    const slice = items.slice(i, i + chunkSize);
    for (const item of slice) heavyWork(item);
    await new Promise((r) => setTimeout(r)); // yield: let the browser breathe
  }
}

Each setTimeout yield ends the current macrotask, letting microtasks, rendering, and
input run before the next chunk. (MessageChannel is a faster yield than setTimeout.)

Fix 2: `requestIdleCallback` — run low-priority work when idle

requestIdleCallback((deadline) => {
  // Keep working while there is idle time this frame.
  while (deadline.timeRemaining() > 0 && queue.length) {
    processOne(queue.shift());
  }
  if (queue.length) requestIdleCallback(/* schedule the rest */);
}, { timeout: 2000 }); // timeout guarantees it eventually runs

deadline.timeRemaining() tells you how much idle time is left in the frame (~up to 50ms).
Ideal for non-urgent work: analytics, prefetching, cleanup.
The timeout option ensures it runs even if the browser never goes idle.
Not for visual updates (use requestAnimationFrame) or critical work.

Fix 3: `scheduler.postTask()` and `scheduler.yield()` (modern)

The Prioritized Task Scheduling API gives explicit priorities:

// Priorities: "user-blocking" > "user-visible" (default) > "background"
scheduler.postTask(() => doImportantWork(), { priority: "user-blocking" });
scheduler.postTask(() => doAnalytics(),     { priority: "background" });

// scheduler.yield() — yield mid-task, then RESUME with priority (better than setTimeout,
// which sends you to the back of the queue).
async function work(items) {
  for (let i = 0; i < items.length; i++) {
    heavyWork(items[i]);
    if (i % 500 === 0) await scheduler.yield(); // pause, let the browser respond, resume
  }
}

Fix 4: `isInputPending()` — yield only when the user needs the thread

function processWhileFree(items) {
  while (items.length) {
    if (navigator.scheduling?.isInputPending()) {
      // A click/keypress is waiting — yield so the UI stays responsive.
      setTimeout(() => processWhileFree(items));
      return;
    }
    heavyWork(items.shift());
  }
}

This keeps the thread busy for throughput but bails out the instant input arrives,
balancing speed and responsiveness.

Fix 5: Move heavy work off-thread (Web Worker)

For genuinely CPU-heavy work (parsing, crypto, image processing), get it off the main
thread entirely so the UI never blocks:

const worker = new Worker("heavy.js");
worker.postMessage(bigData);
worker.onmessage = (e) => render(e.data); // main thread only renders the result

Decision guide

Situation	Tool
Big loop on the main thread	Chunk + yield (`setTimeout` / `MessageChannel`)
Non-urgent background work	`requestIdleCallback`
Need explicit task priorities	`scheduler.postTask()`
Yield mid-task but resume soon	`scheduler.yield()`
Keep working but respect input	`isInputPending()`
CPU-heavy computation	Web Worker (off-thread)
Visual/animation updates	`requestAnimationFrame`

Golden rule: keep every task short. Break long work into chunks that each finish
under ~50ms, yield between them, and push truly heavy computation to a Worker, so the main
thread is always free to paint and respond to the user.

17. Web Workers and Their Own Event Loop

Everything so far assumed one event loop on the main thread. A Web Worker runs your
code on a separate OS thread, and that thread has its own, completely independent
event loop, its own call stack, its own macrotask queue, and its own microtask queue.

One event loop per thread

flowchart LR
    subgraph MAIN["Main thread"]
      MCS["Call Stack"] --> MMIC["Microtask Q"] --> MMAC["Macrotask Q"]
    end
    subgraph WORKER["Worker thread"]
      WCS["Call Stack"] --> WMIC["Microtask Q"] --> WMAC["Macrotask Q"]
    end
    MAIN <-->|postMessage / onmessage| WORKER

Key consequences:

Fact	Why it matters
Separate stack + queues	A worker's `setTimeout` / promises / loops never touch the main thread's queues, and vice versa.
No shared scope	Workers can't touch the DOM, `window`, or your variables. They share nothing by default.
True parallelism	Worker code runs at the same time as the main thread, blocking the worker's loop does not freeze the UI.
Communication is async	Data crosses threads only via `postMessage`, which lands as a macrotask (`message` event) on the other thread's loop.
Messages are copied	Payloads are structured-cloned (deep-copied), not shared, unless you use `Transferable`s or `SharedArrayBuffer`.

A worker blocking itself does NOT block the UI

// main.js
const worker = new Worker("worker.js");
worker.postMessage(1_000_000_000);          // ask it to do heavy work
worker.onmessage = (e) => console.log("result:", e.data); // macrotask on MAIN loop
console.log("main thread stays responsive");

// worker.js
self.onmessage = (e) => {
  let sum = 0;
  for (let i = 0; i < e.data; i++) sum += i; // blocks the WORKER's loop only
  self.postMessage(sum);                      // macrotask back on MAIN loop
};

The for loop fully blocks the worker's event loop (its own timers/promises wait), but
the main thread keeps painting and handling input the whole time. That is the entire
point of a worker: move blocking work off the loop that renders the UI.

Cross-thread ordering: `postMessage` is a macrotask

// Inside the worker:
self.onmessage = () => {
  console.log("worker: sync");
  Promise.resolve().then(() => console.log("worker: microtask"));
  self.postMessage("done"); // does NOT run main's handler now — just queues a task there
  console.log("worker: after postMessage");
};
// Worker output: worker: sync → worker: after postMessage → worker: microtask

postMessage doesn't synchronously call the other side, it enqueues a macrotask on the
receiving thread's loop. Each thread still follows the same rule internally: sync → all
microtasks → one macrotask.

Worker types (all get their own loop)

Type	Scope	Use
Dedicated Worker (`new Worker`)	One page	Offload CPU work for a single tab
Shared Worker (`SharedWorker`)	Shared across tabs/windows of same origin	One background loop several tabs talk to
Service Worker	Origin-wide, event-driven proxy	Caching, offline, push, background sync

Mental model: an event loop belongs to a thread, not to the whole app. Each worker is
its own little "single-threaded world" with a private stack and queues; threads stay
isolated and only exchange copied messages that arrive as macrotasks. This is how JS
gets real parallelism without giving up the single-threaded-per-loop model.

More Details:

Get all articles related to system design
Hashtag: SystemDesignWithZeeshanAli

systemdesignwithzeeshanali

Git: https://github.com/ZeeshanAli-0704/front-end-system-design

⬆ Back to Top

Debounce, Throttle & Race-Safe Search Patterns

ZeeshanAli-0704 — Sat, 04 Jul 2026 01:16:38 +0000

Debounce, Throttle & Race-Safe Search Patterns

A complete guide to rate-limiting user input for search / typeahead, built up through
common interview follow-ups. Every pattern below is a standalone factory function that
returns a rate-limited version of your searchFn.

1. Core Idea
2. Debounce vs Throttle
3. Leading edge Debounce
4. Trailing edge Debounce
5. Leading Trailing Debounce
6. Empty input Instant Reset
7. Throttle
8. Idle Eager Mode
9. Race Conditions (Out of Order Responses)
10. Throttle with Trailing Edge
11. Debounce with maxWait
12. Quick Comparison

1. Core Idea

Every keystroke could trigger a network request. Firing one request per character
floods the backend, wastes bandwidth, and produces stale UI. Rate limiting collapses
a burst of calls into far fewer, well-timed calls.

flowchart LR
    K["Keystrokes\n(many per second)"] --> RL["Rate limiter\n(debounce / throttle)"]
    RL --> API["Backend requests\n(few, well-timed)"]

2. Debounce vs Throttle

	Debounce	Throttle
Fires	After the user stops for `delay` ms	On a steady cadence while active
Requests during fast typing	~1 (at the end)	Several (one per interval)
Best for	Search, autocomplete, autosave	Scroll, mousemove, drag, resize

sequenceDiagram
    participant U as User (typing fast)
    participant D as Debounce
    participant T as Throttle
    U->>D: stream of calls
    Note over D: waits for silence -> 1 fire
    U->>T: stream of calls
    Note over T: fires every interval -> N fires

3. Leading edge Debounce

The first call in a burst fires immediately; the rest are ignored until delay ms
of silence re-arms it.

sequenceDiagram
    participant U as User
    participant D as Debounced fn
    U->>D: "a" (t=0)
    D-->>D: FIRE immediately, cool-down ON
    U->>D: "ap" (t=100)
    D-->>D: ignored, timer reset
    U->>D: "app" (t=200)
    D-->>D: ignored, timer reset
    Note over D: 300ms silence...
    D-->>D: re-armed
    U->>D: "b" (t=800)
    D-->>D: FIRE immediately again

function createSearch(searchFn, delay = 300) {
    let timer = null;          // handle for the "cool-down" timer
    let isCoolingDown = false; // true while we are inside a burst

    return function (...args) {
        if (!isCoolingDown) {
            searchFn(...args);   // leading edge: fire right away
            isCoolingDown = true;
        }

        clearTimeout(timer);
        timer = setTimeout(() => {
            isCoolingDown = false; // quiet period elapsed -> re-arm
            timer = null;
        }, delay);
    };
}

Key bug to avoid: you must reset isCoolingDown = false after the quiet period,
otherwise the leading edge only ever fires once.

4. Trailing edge Debounce

The classic/default debounce. Fires once after the user stops. Best for autosave.

function createSearchTrailing(searchFn, delay = 300) {
    let timer = null;

    return function (...args) {
        clearTimeout(timer);
        timer = setTimeout(() => {
            searchFn(...args); // fire with the LATEST args after silence
            timer = null;
        }, delay);
    };
}

5. Leading Trailing Debounce

Fires immediately on the first call and once more at the end if there were extra
calls (lodash-style). Here the timer variable itself is the "idle" flag — no separate
boolean needed.

stateDiagram-v2
    [*] --> Idle: timer = null
    Idle --> Bursting: call arrives\nleading fire + set timer
    Bursting --> Bursting: another call\nsave lastArgs + reset timer
    Bursting --> Idle: silence\ntrailing fire + timer = null

function createSearchBoth(searchFn, delay = 300, { leading = true, trailing = true } = {}) {
    let timer = null;
    let lastArgs = null;

    return function (...args) {
        const isIdle = timer === null; // derived fresh each call

        if (isIdle && leading) {
            searchFn(...args);   // leading fire
        } else {
            lastArgs = args;     // remember newest args for the trailing fire
        }

        clearTimeout(timer);
        timer = setTimeout(() => {
            if (trailing && lastArgs) {
                searchFn(...lastArgs); // trailing fire with latest input
            }
            timer = null;   // re-arms "idle"
            lastArgs = null;
        }, delay);
    };
}

leading / trailing are config options (never reassigned). The real state is
timer: null = idle/armed, non-null = mid-burst.

6. Empty input Instant Reset

Follow-up: "What if the user clears the input?" Clearing should reset results
instantly — bypass the debounce and cancel any pending search.

sequenceDiagram
    participant U as User
    participant D as Debounced search
    U->>D: "app" (t=0)
    D-->>D: leading fire, timer armed
    U->>D: "" clear (t=120)
    D-->>D: clearTimeout(pending) + fire("") now
    Note over D: no stale "app" result can land

function createSearchSmart(searchFn, delay = 300) {
    let timer = null;
    let isCoolingDown = false;

    function debounced(...args) {
        const query = args[0];

        // Empty input -> reset instantly, bypass the debounce.
        if (query === "" || query == null) {
            clearTimeout(timer);
            timer = null;
            isCoolingDown = false;
            searchFn(query);
            return;
        }

        if (!isCoolingDown) {
            searchFn(...args);
            isCoolingDown = true;
        }

        clearTimeout(timer);
        timer = setTimeout(() => {
            isCoolingDown = false;
            timer = null;
        }, delay);
    }

    // Let callers manually cancel a pending search (e.g. on unmount).
    debounced.cancel = function () {
        clearTimeout(timer);
        timer = null;
        isCoolingDown = false;
    };

    return debounced;
}

7. Throttle

Fires at most once every interval ms. Does not wait for silence.

function createSearchThrottle(searchFn, interval = 300) {
    let lastRun = 0;

    return function (...args) {
        const now = Date.now();
        if (now - lastRun >= interval) {
            searchFn(...args);
            lastRun = now;
        }
    };
}

⚠️ A plain throttle can drop the final keystroke — see section 10 for the fix.

8. Idle Eager Mode

Follow-up: "What if the user waits 10 seconds, then types more?" A long pause breaks
the burst — the next input is a fresh intent, so fire it eagerly.

sequenceDiagram
    participant U as User
    participant D as Debounced fn
    U->>D: "a" (t=0)
    D-->>D: debounce... fires "a"
    Note over U,D: idle 10s (> 5s threshold)
    U->>D: "ab" (t=10s)
    D-->>D: idle exceeded -> EAGER fire "ab" now

function createSearchIdleEager(searchFn, delay = 300, idleThreshold = 5000) {
    let timer = null;
    let lastCallTime = 0;

    return function (...args) {
        const now = Date.now();
        const idleFor = now - lastCallTime;
        lastCallTime = now;

        // Long pause -> treat as a fresh, eager search.
        if (idleFor >= idleThreshold) {
            clearTimeout(timer);
            timer = null;
            searchFn(...args);   // eager fire
            return;
        }

        // Otherwise normal trailing debounce within the burst.
        clearTimeout(timer);
        timer = setTimeout(() => {
            searchFn(...args);
            timer = null;
        }, delay);
    };
}

9. Race Conditions (Out of Order Responses)

Follow-up (Google favorite): "What if responses come out of order?" Debounce cuts the
number of requests but does not guarantee ordering. The last response to arrive
may not be the last one requested.

sequenceDiagram
    participant U as User
    participant S as Server
    U->>S: search("a")     (t=0, takes 500ms)
    U->>S: search("apple") (t=50, takes 100ms)
    S-->>U: "apple" results (t=150) ✅
    S-->>U: "a" results     (t=500) ❌ overwrites!
    Note over U: UI now shows "a" results for "apple"

Solution A — AbortController (preferred)

Cancel the previous request before firing a new one.

function createSearchAbortable(onResult) {
    let controller = null;

    return async function search(query) {
        if (controller) {
            controller.abort(); // cancel the in-flight request
        }
        controller = new AbortController();

        try {
            const response = await fetch(`/search?q=${encodeURIComponent(query)}`, {
                signal: controller.signal,
            });
            const data = await response.json();
            onResult(data); // only the latest, non-aborted request reaches here
        } catch (err) {
            if (err.name === "AbortError") {
                return; // expected: a newer search superseded this one
            }
            throw err;
        }
    };
}

Solution B — Request IDs (sequence numbers)

Use when you cannot cancel (legacy APIs, WebSocket). Apply a response only if it is still
the newest.

function createSearchSequenced(onResult) {
    let latestRequestId = 0;

    return async function search(query) {
        const requestId = ++latestRequestId;

        const response = await fetch(`/search?q=${encodeURIComponent(query)}`);
        const data = await response.json();

        if (requestId !== latestRequestId) {
            return; // stale response -> drop it
        }
        onResult(data);
    };
}

Best practice: debounce + AbortController (reduce load and prevent stale
overwrites), with request IDs as a safety net.

10. Throttle with Trailing Edge

Fixes the dropped-final-keystroke flaw of the plain throttle by scheduling one trailing
call.

function createSearchThrottleTrailing(searchFn, interval = 300) {
    let lastRun = 0;
    let timer = null;
    let lastArgs = null;

    return function (...args) {
        const now = Date.now();
        const remaining = interval - (now - lastRun);
        lastArgs = args;

        if (remaining <= 0) {
            if (timer) {
                clearTimeout(timer);
                timer = null;
            }
            lastRun = now;
            searchFn(...args);   // leading of this window
        } else if (!timer) {
            // schedule ONE trailing call so the last keystroke is not lost
            timer = setTimeout(() => {
                lastRun = Date.now();
                timer = null;
                searchFn(...lastArgs);
            }, remaining);
        }
    };
}

11. Debounce with maxWait

Often the ideal answer for search: debounce normally, but force a fire at least every
maxWait ms so results are never starved during continuous typing (lodash
debounce({ maxWait })).

function createSearchMaxWait(searchFn, delay = 300, maxWait = 1000) {
    let timer = null;
    let firstCallTime = 0;
    let lastArgs = null;

    function fire() {
        clearTimeout(timer);
        timer = null;
        firstCallTime = 0;
        searchFn(...lastArgs);
    }

    return function (...args) {
        const now = Date.now();
        lastArgs = args;
        if (firstCallTime === 0) firstCallTime = now;

        // Force a fire if we've been waiting too long overall.
        if (now - firstCallTime >= maxWait) {
            fire();
            return;
        }

        clearTimeout(timer);
        timer = setTimeout(fire, delay); // normal trailing debounce
    };
}

12. Quick Comparison

Function	Strategy	Fires	Best for
`createSearch`	Leading debounce	Immediately, then ignores burst	Instant first result
`createSearchTrailing`	Trailing debounce	Once after silence	Autosave, resize
`createSearchBoth`	Leading + trailing	First + last of burst	Search wanting both
`createSearchSmart`	Leading + empty reset + cancel	Instant, resets on clear	Production typeahead
`createSearchThrottle`	Throttle	Every interval	Scroll, mousemove
`createSearchIdleEager`	Idle-reset debounce	Eager after long pause	Returning-user UX
`createSearchAbortable`	AbortController	Latest request only	Race safety (modern)
`createSearchSequenced`	Request IDs	Latest request only	Race safety (legacy)
`createSearchThrottleTrailing`	Throttle + trailing	Cadence + final call	Throttle without data loss
`createSearchMaxWait`	Debounce + maxWait cap	Debounced, min once/maxWait	Best default for search

Interview Soundbites

"Debounce cuts the number of requests; it does not fix ordering." Use AbortController or request IDs for correctness.
Empty input is a reset signal, not a search term — bypass the debounce and cancel pending calls.
A long idle gap breaks the burst — reset to eager mode for lower perceived latency.
Pure debounce can starve results if the user never pauses — add a maxWait cap.
In React, call .cancel() on unmount to avoid firing after the component is gone.

More Details:

Get all articles related to system design
Hashtag: SystemDesignWithZeeshanAli

systemdesignwithzeeshanali

Git: https://github.com/ZeeshanAli-0704/front-end-system-design

⬆ Back to Top

Frontend System Design: Video Streaming (YouTube)

ZeeshanAli-0704 — Mon, 29 Jun 2026 16:43:44 +0000

Frontend System Design: Video Streaming (YouTube)

Frontend System Design: Video Streaming (YouTube)
- 1. Concept, Idea, Product Overview
- 1.1 Product Description
- 1.2 Key User Personas
- 1.3 Core User Flows (High Level)
- 2. Requirements
- 2.1 Functional Requirements
- 2.2 Non Functional Requirements
- 3. Scope Clarification (Interview Scoping)
- 3.1 In Scope
- 3.2 Out of Scope
- 3.3 Assumptions
- 4. High Level Frontend Architecture
- 4.1 Overall Approach
- 4.2 Major Architectural Layers
- 4.3 External Integrations
- 5. Component Design and Modularization
- 5.1 Component Hierarchy
- 5.2 Video Player Architecture and Adaptive Streaming (Deep Dive)
  - 5.2.1 HLS and DASH Adaptive Bitrate Streaming
  - 5.2.2 Video Player State Machine
  - 5.2.3 Custom Controls Overlay
  - 5.2.4 Buffering and Preload Strategy
  - 5.2.5 Quality Selection and Auto Resolution
  - 5.2.6 Picture in Picture and Mini Player
  - 5.2.7 Keyboard Shortcuts and Accessibility
  - 5.2.8 Decision Matrix
- 5.3 Reusability Strategy
- 5.4 Module Organization
- 6. High Level Data Flow Explanation
- 6.1 Initial Load Flow
- 6.2 User Interaction Flow
- 6.3 Error and Retry Flow
- 7. Data Modelling (Frontend Perspective)
- 7.1 Core Data Entities
- 7.2 Data Shape
- 7.3 Entity Relationships
- 7.4 UI Specific Data Models
- 8. State Management Strategy
- 8.1 State Classification
- 8.2 State Ownership
- 8.3 Persistence Strategy
- 9. High Level API Design (Frontend POV)
- 9.1 Required APIs
- 9.2 Adaptive Streaming Manifest Fetching Strategy (Deep Dive)
- 9.3 Request and Response Structure
- 9.4 Error Handling and Status Codes
- 10. Caching Strategy
- 11. CDN and Asset Optimization
- 12. Rendering Strategy
- 13. Cross Cutting Non Functional Concerns
- 13.1 Security
- 13.2 Accessibility
- 13.3 Performance Optimization
- 13.4 Observability and Reliability
- 14. Edge Cases and Tradeoffs
- 15. Summary and Future Improvements

1. Concept, Idea, Product Overview

1.1 Product Description

A web application that allows users to discover, watch, and interact with video content — similar to YouTube.
Target users: content consumers (watchers), content creators (uploaders), and advertisers.
Primary use case: browsing a personalized video feed, watching videos with adaptive streaming, and engaging through likes, comments, and subscriptions.

1.2 Key User Personas

Viewer: Browses the home feed, searches for content, watches videos, interacts with likes/comments, subscribes to channels, manages watch history and playlists.
Creator: Uploads videos, manages channel page, reads comments, tracks analytics (views, watch time, subscribers).
Casual Browser: Lands on a shared link, watches a single video, may or may not sign in.

1.3 Core User Flows (High Level)

Watching a Video (Primary Flow):
1. User opens the app or clicks a shared link → video page loads.
2. Video player initializes → fetches adaptive streaming manifest (HLS/DASH).
3. Video starts playing at an appropriate quality based on network conditions.
4. User interacts with player controls (play/pause, seek, volume, fullscreen, quality selector).
5. Recommended videos load in the sidebar or below the player.
6. User scrolls to comments section, reads or posts a comment.
Browsing the Home Feed (Secondary Flow):
1. User opens the home page → personalized video grid loads.
2. Video thumbnails display with title, channel name, view count, and upload date.
3. User hovers on a thumbnail → silent video preview plays (desktop).
4. User clicks a thumbnail → navigates to the video watch page.
5. Infinite scroll loads more recommendations as user scrolls.
Searching for Content (Secondary Flow):
1. User types in the search bar → typeahead suggestions appear.
2. User presses enter → search results page with video cards, channel results, and filters.
3. User clicks a result → navigates to the video watch page.

2. Requirements

2.1 Functional Requirements

Video Playback:
- Adaptive bitrate streaming (HLS/DASH) with automatic quality switching.
- Custom video player controls (play/pause, seek bar, volume, fullscreen, playback speed, quality selector, captions toggle).
- Resume playback from last watched position ("Continue watching").
- Picture-in-Picture (PiP) and mini-player on scroll.
- Keyboard shortcuts (space = play/pause, arrow keys = seek, f = fullscreen, m = mute, c = captions).
Home Feed:
- Personalized video grid (thumbnail, title, channel info, view count, timestamp).
- Category chips for filtering (Trending, Music, Gaming, etc.).
- Infinite scroll with cursor-based pagination.
- Thumbnail hover preview (silent autoplay on desktop).
Video Page:
- Video player (primary content).
- Video metadata (title, description with expandable "Show More", tags, publish date).
- Engagement actions: like, dislike, share, save to playlist, subscribe/unsubscribe.
- Comments section with threaded replies, sort options (Top, Newest), infinite scroll.
- Recommended videos sidebar (desktop) or below player (mobile).
Search:
- Typeahead suggestions with debounced input.
- Search results with filtering (upload date, type, duration, sort order).
Channel Page:
- Channel banner, avatar, name, subscriber count, subscribe button.
- Tabbed content: Videos, Shorts, Playlists, Community, About.

2.2 Non Functional Requirements

Performance: Video playback start (time-to-first-frame) < 2s; FCP < 1.5s for feed pages; TTI < 3s; smooth 60fps scrolling for video grid; buffer ahead of playback to prevent stalls.
Scalability: Support millions of videos in search/recommendations; video pages with millions of comments; home feed with thousands of personalized entries.
Availability: Graceful degradation — show cached thumbnails if offline; fallback to lower quality if bandwidth drops; skeleton UI during loading.
Security: Signed CDN URLs for video segments; DRM integration (Widevine/FairPlay) for protected content; XSS prevention on user-generated comments/descriptions; CSRF tokens on all mutations.
Accessibility: Full keyboard navigation for player and UI; screen reader support with ARIA roles; closed captions and subtitles; focus management for modals and overlays; reduced motion support.
Device Support: Desktop web (primary), mobile web (responsive), tablet; low-bandwidth and low-end device handling via adaptive streaming.
i18n: RTL layout support; localized timestamps ("2 hours ago"); locale-aware number formatting (1.2M views); multi-language subtitle/caption support.

3. Scope Clarification (Interview Scoping)

3.1 In Scope

Video player component with adaptive streaming (HLS/DASH).
Custom player controls (seek, quality, captions, PiP, keyboard shortcuts).
Home feed video grid with infinite scroll.
Video watch page (player + metadata + engagement + recommendations + comments).
State management for playback, feed, and user interactions.
API design from the frontend perspective.
Performance optimization for video-heavy pages.

3.2 Out of Scope

Video upload and transcoding pipeline (backend concern).
Backend recommendation and ranking algorithms.
Ads and monetization system (pre-roll, mid-roll ad insertion).
Live streaming (a separate deep-dive).
Shorts / vertical video player.
Push notifications.
Creator Studio / Analytics dashboard.
Native mobile apps.

3.3 Assumptions

User may or may not be authenticated; unauthenticated users can watch videos but cannot interact (like, comment, subscribe).
Videos are pre-transcoded by the backend into multiple quality levels (240p to 4K) and available as HLS/DASH manifests.
Video segments and thumbnails are served from a CDN with signed or public URLs.
APIs return pre-ranked recommendations and search results (frontend does not rank).
Captions/subtitles are available as WebVTT files served alongside video manifests.

4. High Level Frontend Architecture

4.1 Overall Approach

SPA (Single Page Application) with client-side routing.
SSR for the video watch page shell — server renders the video metadata (title, description, channel info) for fast FCP and SEO (shared links, search engine indexing).
CSR for all interactive elements — video player, comments, recommendations, likes, and subscriptions are hydrated and managed client-side.
The video player module is the primary chunk; secondary features (comments, share modal, playlist modal) are code-split and lazy loaded.
Home feed page uses SSR for the initial grid shell with CSR for infinite scroll and hover previews.

4.2 Major Architectural Layers

┌────────────────────────────────────────────────────────────────────┐
│  UI Layer                                                          │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ VideoWatchPage                                               │  │
│  │  ┌─────────────────────┐  ┌──────────────────────────────┐   │  │
│  │  │ VideoPlayer         │  │ RecommendedVideosSidebar     │   │  │
│  │  │  ┌───────────────┐  │  │  ┌────────────────────────┐  │   │  │
│  │  │  │ ControlsBar   │  │  │  │ VideoCard[]            │  │   │  │
│  │  │  │ ProgressBar   │  │  │  └────────────────────────┘  │   │  │
│  │  │  │ QualityMenu   │  │  └──────────────────────────────┘   │  │
│  │  │  │ CaptionsLayer │  │                                     │  │
│  │  │  └───────────────┘  │  ┌──────────────────────────────┐   │  │
│  │  └─────────────────────┘  │ CommentsSection              │   │  │
│  │  ┌─────────────────────┐  │  ┌────────────────────────┐  │   │  │
│  │  │ VideoMetadata       │  │  │ CommentItem[]          │  │   │  │
│  │  │ EngagementBar       │  │  └────────────────────────┘  │   │  │
│  │  └─────────────────────┘  └──────────────────────────────┘   │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                    │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ HomeFeedPage                                                 │  │
│  │  ┌────────────────┐  ┌────────────────────────────────────┐  │  │
│  │  │ CategoryChips  │  │ VideoGrid (responsive grid)        │  │  │
│  │  └────────────────┘  │  ┌──────────┐ ┌──────────┐         │  │  │
│  │                      │  │VideoCard │ │VideoCard │ ...     │  │  │
│  │                      │  └──────────┘ └──────────┘         │  │  │
│  │                      └────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────────────────┘  │
├────────────────────────────────────────────────────────────────────┤
│  State Management Layer                                            │
│  (Player State, Feed Store, Watch History, User Session,           │
│   Comments State, Subscription State, UI Preferences)              │
├────────────────────────────────────────────────────────────────────┤
│  API and Data Access Layer                                         │
│  (REST/GraphQL Client, Streaming Manifest Fetcher,                 │
│   Optimistic Update Queue, Request Deduplication, Retry Logic)     │
├────────────────────────────────────────────────────────────────────┤
│  Shared / Utility Layer                                            │
│  (IntersectionObserver helpers, Debounce/Throttle, Date formatting,│
│   Number formatting, Media Session API, Analytics tracker,         │
│   ABR Controller, DRM Manager)                                     │
└────────────────────────────────────────────────────────────────────┘

4.3 External Integrations

CDN: Serves video segments (HLS .ts / DASH .m4s), thumbnails, channel avatars, and static assets (Cloudfront / Akamai / Fastly / Google CDN).
Analytics SDK: Track video impressions, play events, watch time, buffering events, quality switches, engagement actions, and session duration.
Backend Services: Video metadata API, recommendations API, comments API, search API, subscription API, watch history API.
Media Player Libraries: hls.js (HLS playback), dash.js (DASH playback), or shaka-player (unified HLS/DASH + DRM).
DRM Services: Widevine (Chrome, Android), FairPlay (Safari, iOS), PlayReady (Edge) for protected content licensing.
Caption Services: WebVTT subtitle files served alongside video manifests.

5. Component Design and Modularization

5.1 Component Hierarchy

App
 ├── Header
 │    ├── Logo (link to home)
 │    ├── SearchBar
 │    │    ├── SearchInput (with debounced typeahead)
 │    │    └── SuggestionsDropdown
 │    ├── VoiceSearchButton
 │    └── UserMenu (avatar, sign in, settings)
 │
 ├── Sidebar (collapsible navigation)
 │    ├── NavItem[] (Home, Trending, Subscriptions, Library, History)
 │    └── SubscriptionsList (channel links)
 │
 ├── HomeFeedPage
 │    ├── CategoryChips (horizontal scrollable filter chips)
 │    ├── VideoGrid (responsive CSS grid)
 │    │    └── VideoCard[] (repeated)
 │    │         ├── ThumbnailContainer
 │    │         │    ├── ThumbnailImage
 │    │         │    ├── HoverPreview (silent video on hover, desktop only)
 │    │         │    ├── DurationBadge ("12:34")
 │    │         │    └── WatchProgressBar (if partially watched)
 │    │         ├── VideoInfo
 │    │         │    ├── ChannelAvatar
 │    │         │    ├── VideoTitle (2 line clamp)
 │    │         │    ├── ChannelName
 │    │         │    └── MetaInfo ("1.2M views · 3 days ago")
 │    │         └── MoreMenu (Save, Add to queue, Not interested)
 │    └── FeedSentinel (IntersectionObserver for infinite scroll)
 │
 └── VideoWatchPage
      ├── VideoPlayer
      │    ├── VideoElement (HTML5 video with HLS/DASH source)
      │    ├── ControlsOverlay
      │    │    ├── PlayPauseButton
      │    │    ├── ProgressBar (seekable with preview thumbnails)
      │    │    ├── VolumeControl (slider + mute toggle)
      │    │    ├── TimeDisplay ("2:34 / 12:56")
      │    │    ├── PlaybackSpeedMenu
      │    │    ├── QualitySelector (Auto, 240p to 4K)
      │    │    ├── CaptionsToggle
      │    │    ├── PiPButton
      │    │    ├── TheaterModeButton
      │    │    └── FullscreenButton
      │    ├── CaptionsRenderer (WebVTT overlay)
      │    ├── BufferingSpinner
      │    └── SeekPreviewThumbnail (on hover over progress bar)
      │
      ├── VideoMetadata
      │    ├── VideoTitle
      │    ├── ViewCount + PublishDate
      │    └── ExpandableDescription ("Show More" / "Show Less")
      │
      ├── EngagementBar
      │    ├── LikeButton (with count)
      │    ├── DislikeButton
      │    ├── ShareButton → ShareModal
      │    ├── SaveButton → PlaylistModal
      │    └── MoreActions (Report, Transcript)
      │
      ├── ChannelInfo
      │    ├── ChannelAvatar
      │    ├── ChannelName + SubscriberCount
      │    └── SubscribeButton (toggle state)
      │
      ├── CommentsSection (lazy loaded)
      │    ├── CommentCount + SortToggle (Top / Newest)
      │    ├── CreateComment (avatar + input + submit)
      │    └── CommentList
      │         └── CommentItem[]
      │              ├── CommentAvatar
      │              ├── CommentBody (username + timestamp + text)
      │              ├── CommentActions (like, dislike, reply)
      │              └── RepliesThread (expandable, lazy loaded)
      │
      └── RecommendedVideos (sidebar on desktop, below on mobile)
           └── VideoCard[] (compact horizontal layout)

5.2 Video Player Architecture and Adaptive Streaming (Deep Dive)

The video player is the core of the entire application — the primary surface where users spend the vast majority of their time. Getting this right matters because:

Users expect instant playback — any delay in time-to-first-frame is immediately noticeable.
Network conditions vary wildly — from 5G to 2G to flaky WiFi. The player must adapt in real-time to avoid buffering stalls.
The player must handle a complex state machine — idle, loading, playing, paused, buffering, seeking, ended, error — with smooth transitions.
Custom controls must layer on top of the native <video> element without breaking accessibility or keyboard navigation.
DRM-protected content requires integration with browser-specific license servers.

5.2.1 HLS and DASH Adaptive Bitrate Streaming

Why Not Just Serve a Single MP4 File?

Approach	How it works	Problems
Single MP4	Server sends one fixed-quality video file	Cannot adapt to network changes; wastes bandwidth on slow connections; no quality options; huge download for HD/4K; no seeking without range requests; browser must download from start
Adaptive streaming (HLS/DASH)	Video is split into 2-10s segments at multiple quality levels; a manifest file describes all available qualities; the client requests segments one at a time, switching quality as needed	Adapts to bandwidth in real-time; fast startup (starts with low quality and upgrades); efficient seeking (jump to any segment); works with CDN caching per-segment

How Adaptive Bitrate (ABR) Streaming Works

┌──── Backend (pre-processing) ────────────────────────────────────┐
│                                                                   │
│  Original Video (1080p, 2GB)                                     │
│       │                                                           │
│       ▼                                                           │
│  Transcoder (FFmpeg / MediaConvert)                              │
│       │                                                           │
│       ├── 240p   → segments (seg0.ts, seg1.ts, seg2.ts, ...)    │
│       ├── 360p   → segments (seg0.ts, seg1.ts, seg2.ts, ...)    │
│       ├── 480p   → segments (seg0.ts, seg1.ts, seg2.ts, ...)    │
│       ├── 720p   → segments (seg0.ts, seg1.ts, seg2.ts, ...)    │
│       ├── 1080p  → segments (seg0.ts, seg1.ts, seg2.ts, ...)    │
│       └── master.m3u8 (manifest listing all quality levels)      │
│                                                                   │
└──────────────── uploaded to CDN ─────────────────────────────────┘

┌──── Frontend (runtime) ──────────────────────────────────────────┐
│                                                                   │
│  1. Player fetches master.m3u8 manifest                          │
│  2. Parses available quality levels and their bandwidth targets  │
│  3. Estimates current network bandwidth                          │
│  4. Selects the highest quality that fits within bandwidth       │
│  5. Fetches segment 0 of that quality → starts playback          │
│  6. Continuously monitors download speed                         │
│  7. If bandwidth drops → switches DOWN to lower quality segment  │
│  8. If bandwidth improves → switches UP to higher quality        │
│                                                                   │
└──────────────────────────────────────────────────────────────────┘

HLS Master Manifest Example (master.m3u8)

#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=400000,RESOLUTION=426x240
quality/240p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=640x360
quality/360p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1400000,RESOLUTION=854x480
quality/480p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2800000,RESOLUTION=1280x720
quality/720p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080
quality/1080p/playlist.m3u8

HLS vs DASH Comparison

Feature	HLS (HTTP Live Streaming)	DASH (Dynamic Adaptive Streaming over HTTP)
Origin	Apple	MPEG consortium (open standard)
Manifest format	.m3u8 (playlist text)	.mpd (XML)
Segment format	.ts (MPEG-TS) or .fmp4	.m4s (fragmented MP4)
Native browser support	Safari, iOS, macOS	None natively (needs dash.js)
JS library needed	hls.js (for non-Safari)	dash.js or shaka-player
DRM support	FairPlay (Safari), Widevine via EME	Widevine, PlayReady via EME
Industry adoption	Dominant (YouTube, Netflix, Twitch all use HLS or hybrid)	Used by YouTube (alongside HLS), Netflix

Implementation with hls.js

import Hls from 'hls.js';
import { useEffect, useRef, useState } from 'react';

function useAdaptivePlayer(manifestUrl: string) {
  const videoRef = useRef<HTMLVideoElement>(null);
  const hlsRef = useRef<Hls | null>(null);
  const [qualityLevels, setQualityLevels] = useState<QualityLevel[]>([]);
  const [currentLevel, setCurrentLevel] = useState<number>(-1); // -1 = auto

  useEffect(() => {
    const video = videoRef.current;
    if (!video || !manifestUrl) return;

    // Safari supports HLS natively via <video src="...m3u8">
    if (video.canPlayType('application/vnd.apple.mpegurl')) {
      video.src = manifestUrl;
      return;
    }

    // All other browsers: use hls.js
    if (Hls.isSupported()) {
      const hls = new Hls({
        startLevel: -1,                    // auto-select initial quality
        capLevelToPlayerSize: true,        // don't fetch 4K for a 360px player
        maxBufferLength: 30,               // buffer up to 30s ahead
        maxMaxBufferLength: 60,            // hard cap at 60s
        lowLatencyMode: false,             // not live, no need for low-latency
      });

      hls.loadSource(manifestUrl);
      hls.attachMedia(video);

      hls.on(Hls.Events.MANIFEST_PARSED, (_event, data) => {
        setQualityLevels(
          data.levels.map((level, index) => ({
            index,
            height: level.height,
            bitrate: level.bitrate,
            label: `${level.height}p`,
          }))
        );
      });

      hls.on(Hls.Events.LEVEL_SWITCHED, (_event, data) => {
        setCurrentLevel(data.level);
      });

      hlsRef.current = hls;

      return () => {
        hls.destroy();
        hlsRef.current = null;
      };
    }
  }, [manifestUrl]);

  const setQuality = (levelIndex: number) => {
    if (hlsRef.current) {
      // -1 = auto, 0+ = fixed quality
      hlsRef.current.currentLevel = levelIndex;
    }
  };

  return { videoRef, qualityLevels, currentLevel, setQuality };
}

Why `capLevelToPlayerSize: true`?

If the video player element is 640px wide, there is no visual benefit in downloading 1080p or 4K video — the extra pixels are wasted. This option tells hls.js to cap the quality level to the player's physical dimensions, saving bandwidth significantly on smaller viewports (mobile, embedded players, mini-player mode).

5.2.2 Video Player State Machine

The video player has a complex set of states that must be managed carefully to avoid glitchy behavior:

                    ┌──────────┐
                    │  IDLE    │  (no video loaded yet)
                    └────┬─────┘
                         │ loadSource()
                         ▼
                    ┌──────────┐
                    │ LOADING  │  (fetching manifest + first segments)
                    └────┬─────┘
                         │ canplay event
                         ▼
                   ┌──────────┐
            ┌──────│ READY    │  (first frame available, not playing yet)
            │      └────┬─────┘
            │           │ play()
            │           ▼
            │      ┌──────────┐     seek()    ┌──────────┐
            │      │ PLAYING  │──────────────→│ SEEKING  │
            │      └────┬─────┘               └────┬─────┘
            │           │ │                       │ seeked event
            │    pause()│ │ waiting event         │
            │           │ ▼                       ▼
            │      ┌──────────┐              ┌──────────┐
            │      │ PAUSED   │              │ PLAYING  │
            │      └──────────┘              └──────────┘
            │           │
            │    ended event
            │           ▼
            │      ┌──────────┐
            │      │ ENDED    │  (reached video end)
            │      └──────────┘
            │
            │      ┌──────────┐
            └─────→│ ERROR    │  (network failure, decode error, DRM error)
                   └──────────┘

State Machine Implementation

type PlayerState = 'idle' | 'loading' | 'ready' | 'playing' | 'paused'
  | 'buffering' | 'seeking' | 'ended' | 'error';

interface PlayerStore {
  state: PlayerState;
  currentTime: number;
  duration: number;
  buffered: number;         // buffered ahead in seconds
  volume: number;
  isMuted: boolean;
  isFullscreen: boolean;
  playbackRate: number;
  qualityLevel: number;     // -1 = auto
  captionsEnabled: boolean;
  error: string | null;
}

function usePlayerState(videoRef: React.RefObject<HTMLVideoElement>) {
  const [store, setStore] = useState<PlayerStore>({
    state: 'idle',
    currentTime: 0,
    duration: 0,
    buffered: 0,
    volume: 1,
    isMuted: false,
    isFullscreen: false,
    playbackRate: 1,
    qualityLevel: -1,
    captionsEnabled: false,
    error: null,
  });

  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    const handlers: Record<string, () => void> = {
      loadstart: () => setStore((s) => ({ ...s, state: 'loading' })),
      canplay: () => setStore((s) => ({
        ...s,
        state: s.state === 'loading' ? 'ready' : s.state,
        duration: video.duration,
      })),
      play: () => setStore((s) => ({ ...s, state: 'playing' })),
      pause: () => setStore((s) => ({
        ...s,
        state: video.ended ? 'ended' : 'paused',
      })),
      waiting: () => setStore((s) => ({ ...s, state: 'buffering' })),
      playing: () => setStore((s) => ({ ...s, state: 'playing' })),
      seeking: () => setStore((s) => ({ ...s, state: 'seeking' })),
      seeked: () => setStore((s) => ({
        ...s,
        state: video.paused ? 'paused' : 'playing',
      })),
      ended: () => setStore((s) => ({ ...s, state: 'ended' })),
      timeupdate: () => setStore((s) => ({
        ...s,
        currentTime: video.currentTime,
        buffered: video.buffered.length > 0
          ? video.buffered.end(video.buffered.length - 1)
          : 0,
      })),
      volumechange: () => setStore((s) => ({
        ...s,
        volume: video.volume,
        isMuted: video.muted,
      })),
      error: () => setStore((s) => ({
        ...s,
        state: 'error',
        error: video.error?.message || 'Playback error',
      })),
    };

    Object.entries(handlers).forEach(([event, handler]) => {
      video.addEventListener(event, handler);
    });

    return () => {
      Object.entries(handlers).forEach(([event, handler]) => {
        video.removeEventListener(event, handler);
      });
    };
  }, [videoRef]);

  return store;
}

5.2.3 Custom Controls Overlay

YouTube (and all serious video platforms) replace the browser's default video controls with a fully custom UI. Reasons:

Default controls differ across browsers (Chrome vs Safari vs Firefox) — inconsistent UX.
No support for quality selection, playback speed, captions, PiP, theater mode, or seek preview thumbnails.
Limited styling capabilities — cannot match brand design.
No keyboard shortcut customization.

Controls Architecture

function VideoPlayer({ manifestUrl, videoId }: Props) {
  const { videoRef, qualityLevels, currentLevel, setQuality } =
    useAdaptivePlayer(manifestUrl);
  const playerState = usePlayerState(videoRef);
  const [controlsVisible, setControlsVisible] = useState(true);
  const hideTimerRef = useRef<ReturnType<typeof setTimeout>>();

  // Auto-hide controls after 3s of inactivity
  const showControls = useCallback(() => {
    setControlsVisible(true);
    clearTimeout(hideTimerRef.current);
    hideTimerRef.current = setTimeout(() => {
      if (playerState.state === 'playing') {
        setControlsVisible(false);
      }
    }, 3000);
  }, [playerState.state]);

  // Keyboard shortcuts
  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      const video = videoRef.current;
      if (!video) return;

      // Ignore if user is typing in an input field
      if (
        e.target instanceof HTMLInputElement ||
        e.target instanceof HTMLTextAreaElement
      ) return;

      switch (e.key) {
        case ' ':
        case 'k':
          e.preventDefault();
          video.paused ? video.play() : video.pause();
          break;
        case 'ArrowLeft':
          e.preventDefault();
          video.currentTime = Math.max(0, video.currentTime - 5);
          break;
        case 'ArrowRight':
          e.preventDefault();
          video.currentTime = Math.min(video.duration, video.currentTime + 5);
          break;
        case 'ArrowUp':
          e.preventDefault();
          video.volume = Math.min(1, video.volume + 0.1);
          break;
        case 'ArrowDown':
          e.preventDefault();
          video.volume = Math.max(0, video.volume - 0.1);
          break;
        case 'f':
          document.fullscreenElement
            ? document.exitFullscreen()
            : videoRef.current?.requestFullscreen();
          break;
        case 'm':
          video.muted = !video.muted;
          break;
        case 'c':
          // Toggle captions — handled by captions layer
          break;
        case 'j':
          video.currentTime = Math.max(0, video.currentTime - 10);
          break;
        case 'l':
          video.currentTime = Math.min(video.duration, video.currentTime + 10);
          break;
      }
      showControls();
    };

    document.addEventListener('keydown', handleKeyDown);
    return () => document.removeEventListener('keydown', handleKeyDown);
  }, [videoRef, showControls]);

  return (
    <div
      className="video-player-container"
      onMouseMove={showControls}
      onTouchStart={showControls}
      style={{ cursor: controlsVisible ? 'default' : 'none' }}
    >
      <video
        ref={videoRef}
        className="video-element"
        playsInline
        // Remove default controls
      />

      {/* Captions overlay */}
      <CaptionsRenderer videoRef={videoRef} enabled={playerState.captionsEnabled} />

      {/* Buffering spinner */}
      {playerState.state === 'buffering' && <BufferingSpinner />}

      {/* Click to play/pause */}
      <div
        className="click-layer"
        onClick={() => {
          const video = videoRef.current;
          if (video) video.paused ? video.play() : video.pause();
        }}
      />

      {/* Controls bar */}
      <ControlsOverlay
        visible={controlsVisible}
        playerState={playerState}
        videoRef={videoRef}
        qualityLevels={qualityLevels}
        currentLevel={currentLevel}
        onQualityChange={setQuality}
      />
    </div>
  );
}

5.2.4 Buffering and Preload Strategy

How Much to Buffer Ahead

Strategy	Buffer ahead	Trade-off
Minimal (10s)	10 seconds of video	Low bandwidth usage; risk of stalls on variable networks
Moderate (30s)	30 seconds	Good balance — enough buffer for network hiccups; reasonable bandwidth
Aggressive (60s+)	60+ seconds	Almost stall-proof; wastes bandwidth if user leaves early or seeks past buffered region
YouTube's approach	~30s playing, pauses buffering when paused (after ~1min buffer is built)	Saves bandwidth when user pauses; resumes buffering when play resumes

Pause Buffer Strategy

When the user pauses the video, YouTube stops buffering after a small lead buffer is filled. This saves bandwidth because users frequently pause and never return. Implementation:

function useSmartBuffering(videoRef: React.RefObject<HTMLVideoElement>, hlsRef: React.RefObject<Hls | null>) {
  useEffect(() => {
    const video = videoRef.current;
    const hls = hlsRef.current;
    if (!video || !hls) return;

    let pauseBufferTimer: ReturnType<typeof setTimeout>;

    const onPause = () => {
      // When paused, allow buffering for 10 more seconds of content,
      // then stop fetching new segments
      pauseBufferTimer = setTimeout(() => {
        // Reduce max buffer to what we already have
        hls.config.maxBufferLength = 10;
      }, 5000); // wait 5s after pause before throttling
    };

    const onPlay = () => {
      clearTimeout(pauseBufferTimer);
      // Restore normal buffer size on play
      hls.config.maxBufferLength = 30;
    };

    video.addEventListener('pause', onPause);
    video.addEventListener('play', onPlay);

    return () => {
      clearTimeout(pauseBufferTimer);
      video.removeEventListener('pause', onPause);
      video.removeEventListener('play', onPlay);
    };
  }, [videoRef, hlsRef]);
}

5.2.5 Quality Selection and Auto Resolution

The quality selector menu shows all available resolutions with an "Auto" option as default:

┌──────────────────┐
│ Quality          │
│ ────────────────│
│   Auto (720p)  ✓│  ← currently selected; shows actual auto-picked level
│   2160p (4K)    │
│   1080p         │
│   720p          │
│   480p          │
│   360p          │
│   240p          │
└──────────────────┘

Auto Quality Logic

When "Auto" is selected (default), the ABR controller in hls.js/dash.js picks the quality level based on:

Factor	How it is used
Measured bandwidth	Download speed of the last N segments — primary signal
Buffer health	If buffer is low (< 5s), be conservative and pick lower quality to fill buffer faster
Player dimensions	If player is 640px wide, cap at 720p (no visual benefit from 1080p)
Device capabilities	Some devices cannot decode 4K; respect `MediaCapabilities` API

When the user manually selects a quality (e.g., 1080p), the ABR controller is bypassed and all future segments are downloaded at that fixed quality regardless of bandwidth. The user can switch back to "Auto" at any time.

5.2.6 Picture in Picture and Mini Player

Two flavors of "keep watching while browsing":

Feature	Mechanism	When used
Browser PiP	`video.requestPictureInPicture()` — browser-native floating window	User clicks PiP button; video floats above all windows
Mini-player	Custom fixed-position element at bottom-right of the page	User scrolls past the video on the watch page; mini-player appears

Mini Player on Scroll

function useMiniPlayer(
  playerContainerRef: React.RefObject<HTMLElement>,
  videoRef: React.RefObject<HTMLVideoElement>
) {
  const [isMiniPlayer, setIsMiniPlayer] = useState(false);

  useEffect(() => {
    const container = playerContainerRef.current;
    if (!container) return;

    const observer = new IntersectionObserver(
      ([entry]) => {
        const video = videoRef.current;
        // Show mini-player only if video is playing and player is out of view
        if (!entry.isIntersecting && video && !video.paused) {
          setIsMiniPlayer(true);
        } else {
          setIsMiniPlayer(false);
        }
      },
      { threshold: 0.5 } // trigger when less than 50% visible
    );

    observer.observe(container);
    return () => observer.disconnect();
  }, [playerContainerRef, videoRef]);

  return isMiniPlayer;
}

When isMiniPlayer is true, the player renders as a fixed-position element:

.mini-player {
  position: fixed;
  bottom: 24px;
  right: 24px;
  width: 400px;
  aspect-ratio: 16 / 9;
  z-index: 1000;
  border-radius: 12px;
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
  transition: all 0.3s ease;
}

5.2.7 Keyboard Shortcuts and Accessibility

YouTube's keyboard shortcuts must be discoverable and accessible:

Key	Action	Notes
`Space` / `K`	Play / Pause	Space only when player is focused (not in input)
`J`	Rewind 10s
`L`	Forward 10s
`←`	Rewind 5s
`→`	Forward 5s
`↑` / `↓`	Volume up / down	10% increments
`F`	Toggle fullscreen
`M`	Toggle mute
`C`	Toggle captions
`0-9`	Seek to 0%-90%	Number keys as percentage of duration
`,` / `.`	Frame back / forward	When paused, step through frames
`>` / `<`	Increase / decrease speed
`Escape`	Exit fullscreen	Browser default

ARIA Requirements for the Player

<div role="region" aria-label="Video player" tabindex="-1">
  <video aria-label="Video: How to Build a React App" />

  <div role="toolbar" aria-label="Player controls">
    <button aria-label="Play" aria-pressed="false">▶</button>

    <input
      type="range"
      role="slider"
      aria-label="Seek"
      aria-valuemin="0"
      aria-valuemax="756"
      aria-valuenow="134"
      aria-valuetext="2 minutes 14 seconds of 12 minutes 36 seconds"
    />

    <button aria-label="Mute" aria-pressed="false">🔊</button>

    <input
      type="range"
      role="slider"
      aria-label="Volume"
      aria-valuemin="0"
      aria-valuemax="100"
      aria-valuenow="80"
    />

    <button aria-label="Captions" aria-pressed="false">CC</button>
    <button aria-label="Fullscreen">⛶</button>
  </div>
</div>

5.2.8 Decision Matrix

Decision	Options	Chosen	Rationale
Streaming protocol	HLS vs DASH vs Progressive MP4	HLS (with hls.js for non-Safari)	Widest device support; Safari native; hls.js is mature and lightweight (~60KB gzipped)
Player library	Custom + hls.js vs shaka-player vs video.js	Custom + hls.js	Minimal bundle; full control over UI; shaka-player adds DRM but is larger
Controls	Native browser vs Custom overlay	Custom overlay	Consistent UX across browsers; YouTube-like features (quality selector, speed, PiP) not available natively
Buffering strategy	Aggressive vs Moderate vs Minimal	Moderate (30s) with pause-aware throttling	Balances stall prevention with bandwidth savings
Quality default	Auto (ABR) vs Fixed	Auto with `capLevelToPlayerSize`	Best experience for majority; manual override available
Mini player	Browser PiP only vs Custom mini-player	Both — custom mini-player on scroll + PiP button	Mini-player keeps user in the app; PiP works across tabs
Captions	Burned-in vs WebVTT overlay	WebVTT overlay	User can toggle; style customization; multi-language support

5.3 Reusability Strategy

VideoCard component: Reused across home feed, search results, recommendations sidebar, channel page, and playlist views. Accepts variant prop for layout (grid, horizontal compact, list).
VideoPlayer: Standalone module that accepts a manifest URL and video metadata. Reusable for main watch page, embedded player, and mini-player.
EngagementBar: Reused for videos and community posts (like, dislike, share, save).
CommentSection: Generic threaded comment component reusable across videos and community posts.
InfiniteScrollContainer: Shared sentinel-based container used for home feed, search results, and comment lists.
Design System: Button, Menu, Modal, Toast, Avatar, Badge components from a shared library.

5.4 Module Organization

src/
 ├── pages/
 │    ├── HomePage/
 │    │    ├── HomePage.tsx
 │    │    ├── CategoryChips.tsx
 │    │    └── VideoGrid.tsx
 │    ├── WatchPage/
 │    │    ├── WatchPage.tsx
 │    │    ├── VideoMetadata.tsx
 │    │    ├── EngagementBar.tsx
 │    │    ├── ChannelInfo.tsx
 │    │    └── RecommendedVideos.tsx
 │    ├── SearchPage/
 │    └── ChannelPage/
 │
 ├── features/
 │    ├── player/
 │    │    ├── VideoPlayer.tsx
 │    │    ├── ControlsOverlay.tsx
 │    │    ├── ProgressBar.tsx
 │    │    ├── QualitySelector.tsx
 │    │    ├── CaptionsRenderer.tsx
 │    │    ├── MiniPlayer.tsx
 │    │    ├── useAdaptivePlayer.ts
 │    │    ├── usePlayerState.ts
 │    │    ├── useMiniPlayer.ts
 │    │    └── useSmartBuffering.ts
 │    ├── comments/
 │    │    ├── CommentsSection.tsx
 │    │    ├── CommentItem.tsx
 │    │    ├── CreateComment.tsx
 │    │    └── RepliesThread.tsx
 │    ├── search/
 │    │    ├── SearchBar.tsx
 │    │    └── SuggestionsDropdown.tsx
 │    └── feed/
 │         ├── VideoCard.tsx
 │         ├── ThumbnailPreview.tsx
 │         └── FeedSentinel.tsx
 │
 ├── shared/
 │    ├── components/   (Button, Modal, Menu, Avatar, Toast, Badge)
 │    ├── hooks/        (useIntersectionObserver, useDebounce, useMediaQuery)
 │    ├── utils/        (formatNumber, formatDuration, formatTimeAgo)
 │    └── api/          (apiClient, requestDeduplicator, retryLogic)
 │
 └── store/
      ├── playerStore.ts
      ├── feedStore.ts
      ├── commentsStore.ts
      ├── userStore.ts
      └── watchHistoryStore.ts

6. High Level Data Flow Explanation

6.1 Initial Load Flow

User navigates to /watch?v=abc123
        │
        ▼
┌─── Server (SSR) ──────────────────────────────────────┐
│  1. Fetch video metadata (title, description, channel) │
│  2. Render HTML shell with metadata (SEO + fast FCP)   │
│  3. Include <link rel="preconnect"> to CDN              │
│  4. Include <link rel="preload"> for manifest URL       │
│  5. Send HTML to browser                                │
└────────────────────────────────────────────────────────┘
        │
        ▼
┌─── Browser ────────────────────────────────────────────┐
│  1. Parse HTML → paint metadata (title, channel info)   │
│  2. Load JS bundle → hydrate React app                  │
│  3. VideoPlayer mounts:                                 │
│     a. Fetch HLS master manifest (master.m3u8)          │
│     b. Parse quality levels                             │
│     c. Select initial quality (based on bandwidth est.) │
│     d. Fetch first 2-3 video segments                   │
│     e. Decode and paint first frame → time-to-first-frame│
│     f. Start playback (autoplay if allowed by browser)  │
│  4. Lazy load comments section (below the fold)         │
│  5. Fetch recommended videos for sidebar                │
│  6. Report watch session start to analytics             │
└────────────────────────────────────────────────────────┘

Why preload the manifest?
The HLS manifest is a small text file (~1KB) but is on the critical path to playback. By including <link rel="preload" href="manifest.m3u8" as="fetch"> in the SSR HTML, the browser starts downloading it immediately — even before JS is parsed and the player component mounts. This shaves 100-300ms off time-to-first-frame.

6.2 User Interaction Flow

Action	Frontend Flow
Click play	`video.play()` → state changes to `playing` → controls update → analytics event "play"
Seek (drag progress bar)	Update preview thumbnail on hover → on release: `video.currentTime = seekTarget` → state `seeking` → segment fetched → `seeked` event → state `playing`
Change quality	`hls.currentLevel = selectedLevel` → hls.js fetches next segment at new quality → fade transition between qualities → state updates
Like video	Optimistic: UI immediately shows liked state → POST /api/videos/:id/like → on success: confirmed; on failure: revert UI + show toast
Post comment	Optimistic: comment appears immediately at top → POST /api/videos/:id/comments → on success: update with server-assigned ID; on failure: show retry option
Subscribe	Optimistic: button changes to "Subscribed" → POST /api/channels/:id/subscribe → confirmed or reverted
Toggle captions	Enable WebVTT track → render caption text overlay → persist preference to localStorage
Enter fullscreen	`playerContainer.requestFullscreen()` → CSS adapts layout → controls reflow → `fullscreenchange` event updates state

6.3 Error and Retry Flow

Error Type	Detection	Recovery
Manifest fetch failure	hls.js `ERROR` event with type `NETWORK_ERROR`	Retry with exponential backoff (1s, 2s, 4s); after 3 retries show error UI with "Tap to retry"
Segment fetch failure	hls.js `FRAG_LOAD_ERROR`	hls.js auto-retries; if persistent, drop to lower quality; if all qualities fail, show error
Decode error	`video.error` with `MEDIA_ERR_DECODE`	Try lower quality; if all fail, suggest different browser
DRM license failure	EME `keystatuseschange` with `output-restricted`	Show "Content not available on this device" message
API failure (like, comment)	HTTP 4xx/5xx response	Revert optimistic update; show toast with retry action
Network offline	`navigator.onLine` + `offline` event	Pause playback; show "You are offline" banner; resume when back online

function usePlaybackErrorRecovery(
  hlsRef: React.RefObject<Hls | null>,
  videoRef: React.RefObject<HTMLVideoElement>
) {
  useEffect(() => {
    const hls = hlsRef.current;
    if (!hls) return;

    const handleError = (_event: string, data: Hls.errorData) => {
      if (!data.fatal) return; // non-fatal errors are auto-recovered by hls.js

      switch (data.type) {
        case Hls.ErrorTypes.NETWORK_ERROR:
          // Try to recover by restarting the load
          hls.startLoad();
          break;
        case Hls.ErrorTypes.MEDIA_ERROR:
          // Try to recover from media errors
          hls.recoverMediaError();
          break;
        default:
          // Unrecoverable error — destroy and show error UI
          hls.destroy();
          break;
      }
    };

    hls.on(Hls.Events.ERROR, handleError);
    return () => hls.off(Hls.Events.ERROR, handleError);
  }, [hlsRef, videoRef]);
}

7. Data Modelling (Frontend Perspective)

7.1 Core Data Entities

Video: The primary content entity — metadata, streaming info, engagement counts.
Channel: The creator/publisher of videos — name, avatar, subscriber count.
Comment: User-generated text attached to a video, with threading support.
User: The authenticated viewer — preferences, watch history, subscriptions.
Playlist: An ordered collection of videos created by a user or system-generated.
Caption: Subtitle/caption track associated with a video.

7.2 Data Shape

interface Video {
  id: string;
  title: string;
  description: string;
  thumbnailUrl: string;          // CDN URL for thumbnail
  previewUrl: string | null;     // short silent preview clip for hover
  manifestUrl: string;           // HLS/DASH manifest URL
  duration: number;              // total duration in seconds
  viewCount: number;
  likeCount: number;
  dislikeCount: number;
  commentCount: number;
  publishedAt: string;           // ISO 8601
  channel: ChannelSummary;
  tags: string[];
  category: string;
  isLive: boolean;
  captions: CaptionTrack[];
  watchProgress: number | null;  // seconds watched (for "continue watching")
  isLiked: boolean | null;       // null = not voted, true = liked, false = disliked
}

interface ChannelSummary {
  id: string;
  name: string;
  avatarUrl: string;
  subscriberCount: number;
  isSubscribed: boolean;
}

interface Channel extends ChannelSummary {
  bannerUrl: string;
  description: string;
  videoCount: number;
  joinedAt: string;
  links: { label: string; url: string }[];
}

interface Comment {
  id: string;
  videoId: string;
  author: {
    id: string;
    name: string;
    avatarUrl: string;
    isChannelOwner: boolean;    // highlighted if video creator replies
  };
  text: string;
  likeCount: number;
  isLiked: boolean;
  replyCount: number;
  createdAt: string;
  isEdited: boolean;
  parentId: string | null;      // null = top-level comment
}

interface CaptionTrack {
  language: string;             // "en", "es", "hi"
  label: string;                // "English", "Spanish"
  url: string;                  // WebVTT file URL
  isAutoGenerated: boolean;
}

interface VideoCard {
  id: string;
  title: string;
  thumbnailUrl: string;
  duration: number;
  viewCount: number;
  publishedAt: string;
  channel: {
    id: string;
    name: string;
    avatarUrl: string;
  };
  watchProgress: number | null;
}

interface Playlist {
  id: string;
  title: string;
  thumbnailUrl: string;
  videoCount: number;
  visibility: 'public' | 'unlisted' | 'private';
  updatedAt: string;
}

7.3 Entity Relationships

Channel  ──(1:many)──→  Video
Video    ──(1:many)──→  Comment
Comment  ──(1:many)──→  Comment (replies via parentId)
Video    ──(1:many)──→  CaptionTrack
User     ──(many:many)──→  Channel (subscriptions)
User     ──(many:many)──→  Video (watch history, likes)
Playlist ──(many:many)──→  Video (ordered list)

Normalized storage: Videos, channels, and comments are stored in separate normalized maps in the store. References use IDs.
Denormalized in API responses: API returns embedded channel data within Video to avoid N+1 fetches for the feed. Frontend can extract and normalize on receipt.

7.4 UI Specific Data Models

// Derived state for the video player
interface PlayerUIState {
  formattedCurrentTime: string;        // "2:34"
  formattedDuration: string;           // "12:56"
  progressPercent: number;             // 0-100 for progress bar width
  bufferedPercent: number;             // 0-100 for buffer indicator
  qualityLabel: string;               // "720p" or "Auto (720p)"
  isControlsVisible: boolean;
  isMiniPlayer: boolean;
}

// Derived state for video card in feed
interface VideoCardUIState {
  formattedViewCount: string;          // "1.2M views"
  formattedPublishedAt: string;        // "3 days ago"
  formattedDuration: string;           // "12:34"
  watchProgressPercent: number | null; // red bar on thumbnail
}

// Aggregated comment section state
interface CommentSectionUIState {
  formattedCommentCount: string;       // "1.2K comments"
  sortOrder: 'top' | 'newest';
  isLoadingMore: boolean;
  hasMoreComments: boolean;
}

8. State Management Strategy

8.1 State Classification

State Type	What it contains	Tool
Server state	Video metadata, comments, recommendations, search results, channel data	React Query / TanStack Query (cache, refetch, optimistic updates)
Player state	Current time, duration, buffered, playing/paused, volume, quality level, fullscreen, captions	Local component state via `usePlayerState` hook (high-frequency updates)
Global app state	Current user session, auth token, theme preference, sidebar collapsed state	Zustand or React Context
Feature state	Comments sort order, search filters, category chip selection	Component-local or feature-level Zustand slice
Persisted state	Watch history, playback position per video, volume preference, caption preference, playback speed	localStorage synced to store

8.2 State Ownership

State	Owner	Why
Video metadata	React Query cache (keyed by videoId)	Server-owned data; cache invalidated on refetch
Player playback state	`usePlayerState` hook (local to VideoPlayer)	High-frequency time updates should NOT propagate to global store — would cause unnecessary re-renders
Like/Dislike state	React Query mutation with optimistic update	Server-owned but UI needs instant feedback
Comments list	React Query infinite query (keyed by videoId + sort)	Paginated server data with cursor-based fetching
Subscription state	React Query + global user store	Affects multiple UI elements (subscribe button, sidebar)
Mini-player visibility	`useMiniPlayer` hook (local)	Derived from IntersectionObserver — no need in global store
Watch progress	localStorage + debounced API sync	Persisted locally for instant "continue watching"; synced to server periodically

Why Player State is Kept Local

The video timeupdate event fires ~4 times per second. If player state lived in a global store (Redux, Zustand), every 250ms would trigger:

Store update
Selector recalculation for all subscribers
Re-renders in any component consuming player state

By keeping player state in the VideoPlayer component tree, only the progress bar and time display re-render on timeupdate. The rest of the page is unaffected.

8.3 Persistence Strategy

Data	Storage	Sync Strategy
Watch progress per video	`localStorage: { [videoId]: seconds }`	Write on `timeupdate` (throttled to every 5s); sync to server every 30s
Volume and mute	`localStorage: volume`	Write on `volumechange`
Playback speed	`localStorage: playbackRate`	Write on change; applied to next video
Caption preference	`localStorage: captionsEnabled` and `preferredCaptionLang`	Write on toggle; auto-enable on next video
Search history	`localStorage: searchHistory[]` (capped at 20 entries)	Write on search submit; used for suggestions
Theme preference	`localStorage: theme`	Write on toggle; applied on app load before render (avoid flash)

// Throttled watch progress persistence
function useWatchProgressSync(videoId: string, videoRef: React.RefObject<HTMLVideoElement>) {
  const lastSyncRef = useRef<number>(0);

  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    const handleTimeUpdate = () => {
      const now = Date.now();
      // Throttle localStorage writes to every 5 seconds
      if (now - lastSyncRef.current < 5000) return;
      lastSyncRef.current = now;

      const progress = Math.floor(video.currentTime);
      localStorage.setItem(`wp_${videoId}`, String(progress));
    };

    video.addEventListener('timeupdate', handleTimeUpdate);
    return () => video.removeEventListener('timeupdate', handleTimeUpdate);
  }, [videoId, videoRef]);

  // Restore on mount
  useEffect(() => {
    const video = videoRef.current;
    const saved = localStorage.getItem(`wp_${videoId}`);
    if (video && saved) {
      const seconds = parseInt(saved, 10);
      // Only resume if not near the end (within last 10s = treat as watched)
      if (seconds > 5 && seconds < video.duration - 10) {
        video.currentTime = seconds;
      }
    }
  }, [videoId, videoRef]);
}

9. High Level API Design (Frontend POV)

9.1 Required APIs

API	Method	Purpose
`GET /api/videos/:id`	GET	Fetch video metadata, manifest URL, channel info, caption tracks
`GET /api/videos/:id/recommendations`	GET	Fetch recommended videos for sidebar
`GET /api/videos/:id/comments`	GET	Fetch paginated comments (cursor-based)
`POST /api/videos/:id/comments`	POST	Post a new comment
`POST /api/videos/:id/like`	POST	Like a video
`POST /api/videos/:id/dislike`	POST	Dislike a video
`DELETE /api/videos/:id/reaction`	DELETE	Remove like/dislike
`GET /api/feed`	GET	Fetch personalized home feed (cursor-based)
`GET /api/search`	GET	Search videos with filters
`GET /api/search/suggestions`	GET	Typeahead suggestions
`GET /api/channels/:id`	GET	Fetch channel profile
`POST /api/channels/:id/subscribe`	POST	Subscribe to channel
`DELETE /api/channels/:id/subscribe`	DELETE	Unsubscribe
`GET /api/history`	GET	Watch history
`PUT /api/history/:videoId`	PUT	Update watch progress

9.2 Adaptive Streaming Manifest Fetching Strategy (Deep Dive)

The video manifest URL is the most critical resource for playback start. How we fetch it determines time-to-first-frame.

Three Phase Strategy

Phase 1: SSR Preload (during server rendering)
────────────────────────────────────────────
  Server embeds: <link rel="preload" href="https://cdn.example.com/v/abc123/master.m3u8" as="fetch" crossorigin>
  → Browser starts downloading manifest immediately, in parallel with JS bundle

Phase 2: Player Mount (after JS hydration)
────────────────────────────────────────────
  VideoPlayer mounts → hls.loadSource(manifestUrl)
  → If preload completed, manifest is served from browser cache (0ms fetch)
  → If still loading, hls.js waits for the in-flight request

Phase 3: Segment Fetching (after manifest parsed)
────────────────────────────────────────────
  hls.js parses manifest → selects quality → fetches first 2 segments
  → First segment decodes → first frame painted → playback starts

Why Preloading Works

Without preload	With preload
HTML loads → JS loads → React hydrates → Player mounts → manifest starts downloading → segments download → playback	HTML loads → manifest starts downloading (parallel) → JS loads → React hydrates → Player mounts → manifest already cached → segments download → playback
Manifest fetch blocked behind JS execution (~500ms-1s delay)	Manifest fetch overlaps with JS loading (saves 200-500ms)

9.3 Request and Response Structure

Get Video Details

// GET /api/videos/abc123

// Response:
{
  "data": {
    "id": "abc123",
    "title": "How to Build a React App in 2025",
    "description": "In this video we cover...",
    "thumbnailUrl": "https://cdn.example.com/thumbs/abc123.webp",
    "manifestUrl": "https://cdn.example.com/v/abc123/master.m3u8",
    "duration": 756,
    "viewCount": 1245000,
    "likeCount": 45200,
    "dislikeCount": 890,
    "commentCount": 3400,
    "publishedAt": "2025-01-15T10:30:00Z",
    "channel": {
      "id": "ch_xyz",
      "name": "React Mastery",
      "avatarUrl": "https://cdn.example.com/avatars/ch_xyz.webp",
      "subscriberCount": 850000,
      "isSubscribed": true
    },
    "tags": ["react", "tutorial", "frontend"],
    "category": "Education",
    "captions": [
      {
        "language": "en",
        "label": "English",
        "url": "https://cdn.example.com/captions/abc123_en.vtt",
        "isAutoGenerated": false
      },
      {
        "language": "hi",
        "label": "Hindi",
        "url": "https://cdn.example.com/captions/abc123_hi.vtt",
        "isAutoGenerated": true
      }
    ],
    "watchProgress": 245,
    "isLiked": true
  }
}

Get Home Feed (Cursor Based Pagination)

// GET /api/feed?cursor=eyJ0IjoiMjAyNS0wMS0xNSJ9&limit=20&category=trending

// Response:
{
  "data": [
    {
      "id": "vid_001",
      "title": "10 CSS Tricks You Didn't Know",
      "thumbnailUrl": "https://cdn.example.com/thumbs/vid_001.webp",
      "duration": 480,
      "viewCount": 520000,
      "publishedAt": "2025-01-14T08:00:00Z",
      "channel": {
        "id": "ch_css",
        "name": "CSS Weekly",
        "avatarUrl": "https://cdn.example.com/avatars/ch_css.webp"
      },
      "watchProgress": null
    }
  ],
  "pagination": {
    "nextCursor": "eyJ0IjoiMjAyNS0wMS0xNCJ9",
    "hasMore": true
  }
}

Get Comments (Cursor Based)

// GET /api/videos/abc123/comments?sort=top&cursor=cmnt_page2&limit=20

// Response:
{
  "data": [
    {
      "id": "cmnt_001",
      "author": {
        "id": "user_42",
        "name": "DevFan",
        "avatarUrl": "https://cdn.example.com/avatars/user_42.webp",
        "isChannelOwner": false
      },
      "text": "Great tutorial! The hooks explanation was really clear.",
      "likeCount": 234,
      "isLiked": false,
      "replyCount": 12,
      "createdAt": "2025-01-15T12:30:00Z",
      "isEdited": false,
      "parentId": null
    }
  ],
  "pagination": {
    "nextCursor": "cmnt_page3",
    "hasMore": true
  }
}

9.4 Error Handling and Status Codes

Status	Meaning	Frontend Behavior
`200`	Success	Render data normally
`400`	Bad request (invalid params)	Show inline validation error
`401`	Unauthorized	Redirect to login; for engagement actions show "Sign in to like/comment" prompt
`403`	Forbidden (age-restricted, geo-blocked)	Show "This video is not available" with reason
`404`	Video/channel not found	Show "This video is no longer available" page
`429`	Rate limited	Back off; show "Too many requests, try again later" toast
`500`	Server error	Show generic error with retry button
`503`	Service unavailable	Show cached data if available; retry with backoff

10. Caching Strategy

10.1 What to Cache

Data	Cache?	Reason
Video metadata	Yes (5min TTL via React Query)	Metadata rarely changes; stale data is acceptable briefly
Home feed	Yes (stale-while-revalidate)	Show cached feed instantly on revisit; refetch in background
Recommendations	Yes (per videoId, 5min TTL)	Unlikely to change during a single session
Comments	Yes (stale-while-revalidate)	Show cached; refetch for new comments
Search results	Yes (per query string, 2min TTL)	Allow instant back-navigation to search results
Channel profile	Yes (10min TTL)	Rarely changes
Video segments (HLS)	Yes (HTTP cache, long TTL)	Segments are immutable after transcoding
Thumbnails	Yes (HTTP cache, long TTL, CDN)	Static assets; cache-busted via URL when updated
Watch progress	localStorage (not HTTP cached)	Client-owned data; must persist across sessions

10.2 Where to Cache

Layer	What	How
React Query in-memory cache	API responses (metadata, feed, comments)	Automatic with `staleTime` and `gcTime` configuration
Browser HTTP cache	Video segments (.ts), thumbnails (.webp), caption files (.vtt)	`Cache-Control: public, max-age=31536000, immutable` for versioned assets
Service Worker cache	App shell, static assets (JS, CSS, fonts)	Precache on install; serve from cache with network fallback
localStorage	Watch progress, volume, playback speed, caption preference	Written on user interaction; read on mount

10.3 Cache Invalidation

Data	Invalidation Strategy
Video metadata	Time-based (5min staleTime); manual refetch on like/dislike action
Comments	Refetch after posting a comment; staleTime 2min otherwise
Feed	Stale-while-revalidate; refetch on category change or pull-to-refresh
Subscriptions	Invalidate channel query and subscriber count on subscribe/unsubscribe
Video segments	Immutable — never invalidated. New transcode creates new segment URLs.
Thumbnails	URL-versioned (e.g., `thumb_v2.webp`); long HTTP cache; new URL on update

11. CDN and Asset Optimization

11.1 Video Delivery

Video segments served from multi-region CDN (edge servers close to user for low latency).
Each segment is 2-10 seconds of video — small enough for HTTP cache and fast enough for adaptive quality switching.
Segments use Cache-Control: public, max-age=31536000, immutable — once transcoded, segment content never changes.
Manifest files (.m3u8) have short TTL (30-60s) for live streams but can be cached longer for VOD.

11.2 Thumbnail Optimization

Strategy	Implementation
Format	WebP (30% smaller than JPEG) with JPEG fallback via `<picture>`
Responsive sizes	Multiple thumbnail sizes: 120px (mini), 246px (sidebar), 360px (grid), 720px (hover preview)
Lazy loading	`loading="lazy"` for below-the-fold thumbnails; `loading="eager"` for first row
Blur-up placeholder	Inline 16px base64 LQIP in API response → blurred → full image loads
CDN with auto-resize	Use CDN image transformation (e.g., `thumbs/vid_001.webp?w=360&q=80`)

<picture>
  <source
    type="image/webp"
    srcset="thumb_360.webp 360w, thumb_720.webp 720w"
    sizes="(max-width: 600px) 360px, 720px"
  />
  <img
    src="thumb_360.jpg"
    alt="Video thumbnail: 10 CSS Tricks"
    width="360"
    height="202"
    loading="lazy"
  />
</picture>

11.3 Static Asset Optimization

JS bundles: Code-split per route; main bundle < 150KB gzipped; player chunk loaded on watch page; comments chunk lazy-loaded.
CSS: Critical CSS inlined in SSR; rest loaded async.
Fonts: font-display: swap; preload primary font; subset to reduce file size.
Compression: Brotli (preferred) or gzip for all text assets (HTML, JS, CSS, JSON).

12. Rendering Strategy

Page	Strategy	Rationale
Watch page	SSR (shell with metadata) + CSR (player, comments, recommendations)	SEO for shared links (title, thumbnail in OG tags); fast FCP with metadata; player requires client-side HLS/DASH
Home feed	SSR (first grid batch) + CSR (infinite scroll, hover previews)	Fast initial paint; SEO for crawlers; subsequent pages are client-fetched
Search results	SSR (first results) + CSR (filters, pagination)	SEO for search URLs; fast FCP
Channel page	SSR (channel info + first video tab) + CSR (tab switching, infinite scroll)	SEO for channel URLs
Embed page	CSR only	Embedded in iframes on third-party sites; no SEO needed; minimal JS bundle (player only)

Hydration Strategy

Server renders static HTML with video metadata, descriptions, and first-batch thumbnails.
Client hydrates React on the rendered HTML — interactive elements (player, buttons, comments) become functional.
Progressive hydration: Player hydrates first (critical); comments section hydrates on scroll (below fold); sidebar recommendations hydrate after player.
Use <Suspense> boundaries around lazy-loaded sections (comments, recommendations) to prevent blocking the player.

13. Cross Cutting Non Functional Concerns

13.1 Security

Signed CDN URLs: Video manifest and segment URLs include short-lived tokens (e.g., ?token=abc&expires=1710000000). Prevents unauthorized direct access to video files.
DRM: For premium content, use Encrypted Media Extensions (EME) with Widevine (Chrome, Firefox, Android), FairPlay (Safari, iOS), or PlayReady (Edge). License keys are fetched from a license server and never exposed to JavaScript.
XSS prevention: All user-generated content (comments, descriptions, channel names) is rendered via React JSX (auto-escaped). HTML in descriptions is parsed and sanitized server-side; only safe tags (links, line breaks) are allowed.
CSRF: All mutation APIs (like, comment, subscribe) require CSRF tokens or use SameSite=Strict cookies.
Content Security Policy: Restrict sources for scripts, media, and frames via CSP headers. Only allow CDN domains for media.
Token storage: Auth tokens stored in HTTP-only, Secure, SameSite=Lax cookies — never in localStorage or JS-accessible cookies.

13.2 Accessibility

Video player:
- Full keyboard navigation: all controls focusable and operable via keyboard.
- ARIA roles: role="slider" for seek/volume with aria-valuenow, aria-valuetext.
- Screen reader announcements: quality change, captions toggled, error states via aria-live regions.
- Closed captions: WebVTT support; user can toggle; caption style customizable (size, background).
- Reduced motion: Disable auto-advancing animations; respect prefers-reduced-motion.
Feed and navigation:
- Semantic HTML: <nav>, <main>, <article> for proper document structure.
- Skip link: "Skip to main content" link that bypasses header and sidebar.
- Focus management: When navigating to a new page, focus moves to page heading.
- Video cards: alt text on thumbnails; duration and view count available to screen readers.
Color contrast: WCAG AA minimum (4.5:1) for all text; AAA (7:1) for critical controls.

13.3 Performance Optimization

Code splitting: Route-based splitting (home, watch, search, channel); player module loaded only on watch page; comments lazy-loaded on scroll.
Bundle size budget: Main bundle < 150KB gzipped; player chunk < 80KB; hls.js ~60KB gzipped imported only on watch page.
Image lazy loading: loading="lazy" on all below-fold thumbnails; eager for first visible row.
Thumbnail hover preview: Load preview video only on hover (after 500ms delay) to avoid wasted requests on accidental hovers.
Debounced search: Typeahead debounced at 300ms to limit API calls.
Virtualization: For large comment threads (1000+ comments), virtualize the comment list to keep DOM lean.
Web Workers: Offload heavy computations (e.g., comment text processing, analytics batching) to Web Workers.
Media Session API: Integrate with OS media controls (lock screen, notification bar) for playback control.
Performance metrics: Track FCP, LCP, TTI, CLS, time-to-first-frame, buffering ratio, quality switches.

// Report time-to-first-frame metric
function useTimeToFirstFrame(videoRef: React.RefObject<HTMLVideoElement>) {
  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    const startTime = performance.now();

    const handleFirstFrame = () => {
      const ttff = performance.now() - startTime;
      // Send to analytics
      analytics.track('time_to_first_frame', { ttff, videoId: video.dataset.videoId });
      video.removeEventListener('playing', handleFirstFrame);
    };

    video.addEventListener('playing', handleFirstFrame);
    return () => video.removeEventListener('playing', handleFirstFrame);
  }, [videoRef]);
}

13.4 Observability and Reliability

Error boundaries: Wrap player, comments, and recommendations in independent error boundaries. A crash in comments should not take down the player.
Logging: Capture player errors (manifest failures, segment errors, DRM issues), API errors, and client exceptions. Send to centralized logging (e.g., Sentry, Datadog).
Video quality metrics: Track per-session: average bitrate, quality switches count, buffering duration, stall count, time-to-first-frame.
Feature flags: Gate new features (new player UI, experimental ABR algorithm, new comment layout) behind flags for gradual rollout.
Health checks: Monitor CDN availability, manifest accessibility, and playback success rate.

// Error boundary for player isolation
function WatchPage() {
  return (
    <div className="watch-page">
      <ErrorBoundary fallback={<PlayerErrorFallback />}>
        <VideoPlayer manifestUrl={manifestUrl} videoId={videoId} />
      </ErrorBoundary>

      <VideoMetadata videoId={videoId} />
      <EngagementBar videoId={videoId} />

      <ErrorBoundary fallback={<CommentsErrorFallback />}>
        <Suspense fallback={<CommentsSkeleton />}>
          <CommentsSection videoId={videoId} />
        </Suspense>
      </ErrorBoundary>

      <ErrorBoundary fallback={<RecommendationsErrorFallback />}>
        <Suspense fallback={<RecommendationsSkeleton />}>
          <RecommendedVideos videoId={videoId} />
        </Suspense>
      </ErrorBoundary>
    </div>
  );
}

14. Edge Cases and Tradeoffs

Edge Case	Handling
Very long video (4+ hours)	Progress bar precision: use seconds (not pixels) for accurate seeking; buffer only 30s ahead to save bandwidth; thumbnail sprites may be very large — paginate sprite sheets
User seeks past buffered region	Discard current buffer; fetch segments at new position; show brief buffering spinner; ABR may start at lower quality then upgrade
Slow network (2G/3G)	ABR drops to 240p automatically; show quality indicator; if buffer empties, player enters buffering state with spinner
Network disconnects mid-playback	Player continues from buffer; when buffer exhausts, show "You are offline" overlay; auto-resume when connectivity returns (`online` event)
Browser autoplay policy blocks playback	Detect `play()` promise rejection; show a "Click to play" overlay with muted autoplay as fallback (muted autoplay is always allowed)
Video not available (deleted or private)	API returns 404/403; show "This video is unavailable" page with recommended videos
Age restricted content	API response includes `ageRestricted: true`; show age verification gate before loading manifest
Multiple tabs playing	Use `document.visibilityState` — pause video when tab becomes hidden (optional, configurable)
Comment spam / long text	Truncate comments at 500 characters with "Read more"; sanitize all input server-side; rate limit comment submissions
Concurrent like/subscribe clicks	Debounce rapid clicks; ignore duplicate mutations; use request deduplication in API layer
Embed in third party sites	Minimal player bundle; no sidebar/comments; communicate with parent page via `postMessage` API
RTL languages	Mirror player controls; swap left/right seek zones; ensure progress bar fills from right-to-left
Low-end devices	Cap max quality to 480p; reduce buffer size; disable hover preview; simplify animations

15. Summary and Future Improvements

Key Architectural Decisions

Decision	Rationale
SPA with SSR for watch/feed pages	SEO for shared video links; fast FCP; rich interactivity
HLS with hls.js for adaptive streaming	Universal browser support; automatic quality adaptation; mature library
Custom video controls over native	Consistent UX; YouTube-like features (quality, speed, PiP, captions)
React Query for server state	Caching, deduplication, optimistic updates, stale-while-revalidate
Local state for player internals	High-frequency `timeupdate` events; avoid global store churn
Code-split player and comments	Player loads on watch page only; comments lazy loaded below fold
IntersectionObserver for infinite scroll and mini-player	Performant, off-main-thread intersection detection
Cursor-based pagination	Stable under concurrent inserts; efficient for infinite scroll
localStorage for watch progress	Instant resume; periodic server sync for cross-device

Major Tradeoffs

Tradeoff	Chosen	Alternative	Why
Bundle size vs features	Custom player + hls.js (~60KB)	Full-featured video.js (~200KB+)	Smaller bundle; full control over UI and behavior
SSR complexity vs SEO	SSR for metadata shell	Full CSR with prerendering	Critical for social sharing (OG tags) and search indexing
Buffer size vs bandwidth	30s with pause-aware throttling	Aggressive 60s+ buffering	Saves bandwidth on paused/abandoned videos
Optimistic updates vs consistency	Optimistic for likes/comments	Wait for server confirmation	Instant feedback; rare conflicts in engagement actions
Virtualization for comments vs simplicity	Virtualize at 50+ comments	Render all comments	Prevents DOM bloat in popular videos with thousands of comments

Future Enhancements

Offline viewing: Service Worker caches video segments for later playback (premium feature).
Watch party: Synchronized playback across multiple users via WebSocket.
AI-generated chapters: Auto-segment videos with chapter markers using backend ML.
Theater mode: Widen player to full browser width while dimming sidebar.
Ambient mode: Extract dominant colors from video frames to create ambient glow behind player.
Playback in background tab: Continue audio playback when tab is not visible.
Multi-language audio tracks: Switch audio language without reloading video.
Advanced analytics for creators: Real-time view counts, audience retention graphs (separate Creator Studio deep-dive).

Hashtag: SystemDesignWithZeeshanAli

systemdesignwithzeeshanali

Git: https://github.com/ZeeshanAli-0704/front-end-system-design

Frontend System Design: Google Sheets

ZeeshanAli-0704 — Mon, 29 Jun 2026 14:39:56 +0000

Frontend + Backend System Design: Google Sheets (Collaborative Spreadsheet)

0. Architecture Diagram
1. Concept, Idea, Product Overview
- 1.1 Product Description
- 1.2 Key User Personas
- 1.3 Core User Flows (High Level)
2. Requirements
- 2.1 Functional Requirements
- 2.2 Non Functional Requirements
3. Scope Clarification (Interview Scoping)
- 3.1 In Scope
- 3.2 Out of Scope
- 3.3 Assumptions
4. High Level Architecture
- 4.1 Overall Approach
- 4.2 Major Architectural Layers
- 4.3 External Integrations
5. Grid Rendering and Virtualization (Deep Dive)
- 5.1 Why Naive Rendering Fails
- 5.2 Visible Range Computation
- 5.3 Windowing (Overscan)
- 5.4 Scroll Lifecycle: From Scroll Event to New Window
- 5.5 Node Reuse and Old DOM Removal
- 5.6 Frozen Rows/Columns and Variable Sizes
- 5.7 Virtualization vs Windowing (What Is the Difference)
6. Formula Engine and Dependency Graph (Deep Dive)
- 6.1 Formula Parse Pipeline
- 6.2 Dependency Graph Model
- 6.3 Incremental Recalculation Strategy
- 6.4 Circular References and Error Propagation
7. High Level Data Flow Explanation
- 7.1 Initial Load Flow
- 7.2 Cell Edit Flow (Optimistic + Authoritative Reconcile)
- 7.3 Error and Retry Flow
8. Data Modelling
- 8.1 Core Entities
- 8.2 Data Shape
- 8.3 Backend Storage Split
9. State Management Strategy
- 9.1 State Classification
- 9.2 State Ownership
- 9.3 Persistence and Recovery
10. Real Time Collaboration and Conflict Handling
- 10.1 Operation Model
- 10.2 OT vs CRDT (Spreadsheet Context)
- 10.3 Presence, Cursor, and Selection Sync
11. High Level API Design
- 11.1 Required APIs
- 11.2 Request and Response Shape
- 11.3 Versioning and Idempotency
12. Caching, Chunking, and Large Dataset Strategy
13. Cross Cutting Non Functional Concerns
- 13.1 Security
- 13.2 Accessibility
- 13.3 Performance Optimization
- 13.4 Observability and Reliability
14. Edge Cases and Tradeoffs
15. Interview Summary

0. Architecture Diagram

1. Concept, Idea, Product Overview

1.1 Product Description

Google Sheets is a collaborative, browser-based spreadsheet platform that combines a massive interactive grid with formula-based computation and real-time multi-user editing.
It is not just a table UI. It is a reactive compute system where cell values form a dependency graph that updates continuously as users edit data.
Target users include analysts, finance teams, operations teams, educators, and general users creating lightweight databases and dashboards.
Primary use case: edit large sheets with low interaction latency while maintaining consistency across collaborators.

1.2 Key User Personas

Analyst / Power User: Works on large sheets with thousands of formulas, filters, and aggregations. Expects smooth scroll, rapid recalculation, and keyboard-heavy workflows.
Collaborative Team Member: Co-edits shared sheets with multiple users, expects live updates, conflict-safe edits, and version-aware reconciliation.
Casual User: Uses smaller sheets for planning or tracking, expects intuitive editing, instant feedback, and low complexity.

1.3 Core User Flows (High Level)

Primary Flow: Edit and Recompute:
1. User edits a cell (for example, A1=500).
2. UI updates optimistically.
3. Client formula engine performs lightweight local evaluation.
4. Sync engine sends versioned operation to server.
5. Server recalculates impacted dependency subgraph and returns deltas.
6. Client reconciles optimistic state with authoritative patch.
Secondary Flow: Scroll Large Sheet:
1. User scrolls across large row/column ranges.
2. Grid computes visible window with overscan.
3. Recycled DOM/canvas nodes are rebound to new row/column indexes.
4. Additional chunks are lazily fetched for non-cached regions.
Secondary Flow: Real-Time Collaboration:
1. Multiple users edit overlapping ranges.
2. Server orders and merges operations.
3. Clients receive cell-level deltas and presence updates.
4. All replicas converge to the same sheet state.

2. Requirements

2.1 Functional Requirements

Spreadsheet Grid:
- Support up to 1,048,576 rows and 18,278 columns per sheet.
- Cell editing, selection, copy/paste, fill handle, keyboard navigation.
- Frozen rows/columns and variable row heights/column widths.
Formula System:
- Parse and evaluate formulas with cell/range references.
- Maintain dependency graph and incremental recomputation.
- Surface formula errors (#REF!, #DIV/0!, circular reference).
Collaboration:
- Real-time co-editing with operation ordering.
- Presence indicators (active users, selections, cursors).
- Conflict handling with deterministic convergence.
Persistence:
- Reliable save and restore of workbook/sheet/cell state.
- Version history pointers and operation log for replay.
Data Handling:
- Delta-based updates instead of full-sheet payloads.
- Lazy loading/chunked fetch for large datasets.

2.2 Non Functional Requirements

Performance: Scroll should remain near 60 FPS in typical datasets; local edit-to-paint latency should stay under one frame budget where possible.
Scalability: Must support large workbooks, high formula density, and concurrent editors.
Consistency: Clients must converge to server-authoritative state despite offline/reconnect scenarios.
Reliability: Retry, replay, and idempotent operation handling on flaky networks.
Security: Access control, authenticated sessions, and encrypted transport.

3. Scope Clarification (Interview Scoping)

3.1 In Scope

Virtualized grid rendering strategy.
Windowing + recycling for smooth scrolling.
Formula parsing, AST model, dependency graph recomputation.
Cell update sync flow and versioned reconciliation.
Collaboration model and backend storage split.

3.2 Out of Scope

Enterprise permissions UX and admin governance workflows.
Advanced BI/chart engine internals.
Print/export pipeline details.
Billing, tenancy partitioning, and legal retention policies.

3.3 Assumptions

Authentication and basic authorization already exist.
Collaboration service supports low-latency pub/sub.
Calculation service can execute recalculation in topological batches.
Network protocol supports operation versioning and delta patches.

4. High Level Architecture

4.1 Overall Approach

Browser client handles rendering and optimistic interactions.
Server side is authoritative for merge ordering and final computation.
Formula evaluation is split:
- Client: lightweight evaluation for immediate feedback.
- Server: canonical recomputation and conflict-safe final state.
Data transfer is patch-first, not snapshot-first, for steady-state interactions.

4.2 Major Architectural Layers

flowchart TD
    U[User Browser] --> FE[Sheets Frontend]
    FE --> GR[Grid Renderer]
    FE --> FEG[Client Formula Engine]
    FE --> SYNC[Sync Engine]
    FE --> COLLAB[Collaboration Server]

    COLLAB --> CALC[Calculation Server]
    COLLAB --> DOC[Document Store]
    COLLAB --> META[Metadata DB]

Layer responsibilities:

Grid Renderer: virtual viewport computation, windowing, node recycling, hit-testing.
Client Formula Engine: parse + validate + fast local eval.
Sync Engine: operation batching, version tracking, retry/replay.
Collaboration Server: operation ordering, merge, fanout.
Calculation Server: dependency graph maintenance + incremental recomputation.
Document Store: workbook/sheet/cell durable state.
Metadata DB: ACL, ownership, sharing, history pointers.

4.3 External Integrations

Identity provider for authentication and session validation.
Notification/presence channels for active collaborators.
Optional audit pipeline for operation history and governance.

5. Grid Rendering and Virtualization (Deep Dive)

5.1 Why Naive Rendering Fails

A full DOM for millions of rows and thousands of columns is infeasible due to memory, layout, and paint overhead.

5.2 Visible Range Computation

For fixed sizes:

rowStart = floor(scrollTop / rowHeight)
rowVisible = ceil(viewportHeight / rowHeight)
rowEnd = rowStart + rowVisible - 1
colStart = floor(scrollLeft / colWidth)
colVisible = ceil(viewportWidth / colWidth)
colEnd = colStart + colVisible - 1

Only this range (plus buffer) is mounted.

Two practical notes:

Clamp bounds to sheet limits so indices never go negative or exceed max rows/cols.
Recompute only on animation frame during fast scroll to avoid over-rendering on every raw scroll event.

5.3 Windowing (Overscan)

Render beyond the exact viewport to reduce churn.

Visible rows: 100..130
Window rows (with overscan): 80..150

Formulas:

windowStart = max(0, start - overscan)
windowEnd = min(total - 1, end + overscan)

Apply for rows and columns.

How to choose overscan:

Low overscan: lower memory, but more frequent mounts during fast scroll.
High overscan: smoother scroll, but more paint/layout work per frame.
Typical strategy: adaptive overscan based on scroll velocity (increase overscan for fast fling, decrease when idle).

5.4 Scroll Lifecycle: From Scroll Event to New Window

When user scrolls, the renderer typically follows this loop:

Capture scrollTop and scrollLeft from the scroll container.
Compute visible row/column range.
Expand to window range using overscan.
Diff old window vs new window.
Rebind/reposition pooled nodes for incoming cells.
Release or park nodes no longer needed.
Apply style transform offsets in one batch paint.

flowchart LR
    S[Scroll event] --> R[Compute visible range]
    R --> W[Expand to window with overscan]
    W --> D[Diff old vs new window]
    D --> B[Reuse or create nodes]
    B --> P[Position with transforms]
    P --> C[Commit batched update]

Pseudo-flow (conceptual):

onScroll() {
  scheduleOnAnimationFrame(() => {
    const visible = computeVisible(scrollTop, scrollLeft);
    const window = applyOverscan(visible, overscan);
    const diff = diffRanges(prevWindow, window);
    recycleAndBind(diff);
    commitPositions(window);
    prevWindow = window;
  });
}

5.5 Node Reuse and Old DOM Removal

There are two common strategies for old nodes:

Recycle pool (preferred): remove mapping from old cell, keep node object, reuse for incoming cell.
Hard unmount: remove node from DOM tree and create later (simpler, but higher churn).

Recommended lifecycle:

Build set of cells that exited window.
Detach their logical mapping from node ids.
Push freed nodes to reusable pool.
For cells entering window, pop from pool and rebind content.
If pool is empty, create new nodes.
If pool exceeds threshold, trim extras (actual DOM removal) to control memory.

Before/after idea:

Before: node1 -> row100,col2, node2 -> row101,col2
Scroll down far
After: node1 -> row500,col2, node2 -> row501,col2

Key implementation detail:

Keep node position updates as transform translations instead of full layout-affecting style writes whenever possible.

Practical React example (conceptual, simplified):

import React, { useMemo, useRef, useState } from "react";

type CellKey = string; // "row:col"

type CellVM = {
  key: CellKey;
  row: number;
  col: number;
  value: string;
  top: number;
  left: number;
};

type Range = { rowStart: number; rowEnd: number; colStart: number; colEnd: number };

const keyOf = (row: number, col: number) => `${row}:${col}`;

function rangeKeys(r: Range): CellKey[] {
  const out: CellKey[] = [];
  for (let row = r.rowStart; row <= r.rowEnd; row++) {
    for (let col = r.colStart; col <= r.colEnd; col++) {
      out.push(keyOf(row, col));
    }
  }
  return out;
}

export function VirtualGrid({
  rowHeight,
  colWidth,
  maxPoolSize = 400,
}: {
  rowHeight: number;
  colWidth: number;
  maxPoolSize?: number;
}) {
  // nodeId -> current cell key mapping
  const [nodeMap, setNodeMap] = useState<Map<number, CellKey>>(new Map());
  // free reusable node ids
  const recyclePoolRef = useRef<number[]>([]);
  const nextNodeIdRef = useRef(1);
  const prevWindowRef = useRef<Range | null>(null);

  function bindWindow(nextWindow: Range) {
    // Step 1: Read previous window state.
    const prevWindow = prevWindowRef.current;

    // Step 2: Build previous and next key sets.
    const prevKeys = new Set(prevWindow ? rangeKeys(prevWindow) : []);
    const nextKeys = new Set(rangeKeys(nextWindow));

    // Step 3: Diff windows into leaving and entering cell sets.
    const leaving = [...prevKeys].filter((k) => !nextKeys.has(k));
    const entering = [...nextKeys].filter((k) => !prevKeys.has(k));

    // Step 4: Update node bindings in one state transition.
    setNodeMap((prevMap) => {
      const map = new Map(prevMap);

      // Step 4.1: Release leaving cells and push their node ids to recycle pool.
      if (leaving.length > 0) {
        for (const [nodeId, cellKey] of map.entries()) {
          if (leaving.includes(cellKey)) {
            map.delete(nodeId);
            recyclePoolRef.current.push(nodeId);
          }
        }
      }

      // Step 4.2: Bind entering cells: reuse pooled ids first, create only if needed.
      for (const cellKey of entering) {
        const reused = recyclePoolRef.current.pop();
        const nodeId = reused ?? nextNodeIdRef.current++;
        map.set(nodeId, cellKey);
      }

      // Step 4.3: Optional cleanup: trim recycle pool to cap memory.
      if (recyclePoolRef.current.length > maxPoolSize) {
        recyclePoolRef.current.length = maxPoolSize;
      }

      return map;
    });

    // Step 5: Commit this window as previous for next diff.
    prevWindowRef.current = nextWindow;
  }

  // Step 6: Build render list from current node bindings.
  const cells: CellVM[] = useMemo(() => {
    const out: CellVM[] = [];
    for (const [nodeId, cellKey] of nodeMap.entries()) {
      const [rowStr, colStr] = cellKey.split(":");
      const row = Number(rowStr);
      const col = Number(colStr);
      out.push({
        key: `node-${nodeId}`,
        row,
        col,
        value: `R${row}C${col}`,
        top: row * rowHeight,
        left: col * colWidth,
      });
    }
    return out;
  }, [nodeMap, rowHeight, colWidth]);

  // Step 7: On scroll, compute nextWindow and call bindWindow(nextWindow).
  // bindWindow({ rowStart: 100, rowEnd: 150, colStart: 2, colEnd: 8 });

  return (
    <div style={{ position: "relative" }}>
      {cells.map((c) => (
        <div
          key={c.key}
          style={{
            position: "absolute",
            width: colWidth,
            height: rowHeight,
            transform: `translate(${c.left}px, ${c.top}px)`,
            willChange: "transform",
          }}
        >
          {c.value}
        </div>
      ))}
    </div>
  );
}

What this snippet demonstrates:

Leaving cells are unmapped and their node ids are pushed to recyclePoolRef.
Entering cells consume pooled ids first, so old DOM nodes are reused.
Pool trimming (maxPoolSize) represents deliberate old-node cleanup to cap memory.
Stable React keys are tied to node ids (node-<id>), not cell positions, enabling reuse.

First render walkthrough with mock data:

Assume:

Total grid size: 10,000 rows x 200 cols
rowHeight = 24px, colWidth = 100px
Viewport size: 480px height x 500px width
Overscan: 5 rows, 2 cols

Step 1: initial visible range at top-left (scrollTop=0, scrollLeft=0)

rowVisible = ceil(480 / 24) = 20
colVisible = ceil(500 / 100) = 5
Visible rows: 0..19
Visible cols: 0..4

Step 2: compute initial window with overscan

Window rows: max(0, 0-5) .. (19+5) => 0..24 (25 rows)
Window cols: max(0, 0-2) .. (4+2) => 0..6 (7 cols)
Total mounted cells: 25 x 7 = 175

Step 3: first-time creation behavior

prevWindow = null, so all 175 cells are "entering"
Recycle pool is empty
Create node ids 1..175
Bind each node id to one cell key (example: node-1 -> 0:0, node-2 -> 0:1, ...)
React renders 175 absolutely-positioned cell nodes

Step 4: user scrolls down and right (scrollTop=240, scrollLeft=200)

New visible rows: 10..29
New visible cols: 2..6
New window rows: 5..34 (30 rows)
New window cols: 0..8 (9 cols)
New window cell count: 30 x 9 = 270

Diff against old window (rows 0..24, cols 0..6):

Intersection cells remain bound and untouched
Leaving cells are unmapped and moved to recycle pool
Entering cells use pooled node ids first, then create only the extra required ids

Why this is efficient:

We do not recreate every cell on each scroll
Most updates are remaps + transform moves
Hard removal happens only when pool exceeds cap

Tiny mock data generator (for local testing):

function mockValue(row: number, col: number): string {
  return `R${row}C${col}`;
}

function getCellData(row: number, col: number) {
  return {
    key: `${row}:${col}`,
    value: mockValue(row, col),
  };
}

5.6 Frozen Rows/Columns and Variable Sizes

Frozen panes are rendered as separate synchronized layers.
Variable dimensions require prefix sums / cumulative offset maps for fast index-to-pixel and pixel-to-index conversions.

For variable row heights, use binary search over prefix sums to map scrollTop to rowStart efficiently.

5.7 Virtualization vs Windowing (What Is the Difference)

These terms are related, but not identical:

Virtualization: overall technique of rendering only a tiny subset of a huge logical list/grid.
Windowing: one implementation strategy inside virtualization where we render a moving contiguous range (window), usually with overscan.

In short:

Virtualization = big concept.
Windowing = concrete mechanism to realize virtualization.

Practical spreadsheet stack:

Virtualization decides "do not render all cells".
Windowing chooses "render this moving range + buffer".
Recycling optimizes "reuse nodes as the range moves".

6. Formula Engine and Dependency Graph (Deep Dive)

6.1 Formula Parse Pipeline

When a user enters =A1+B1:

Tokenize and parse expression.
Build AST.
Resolve references (cell/range names).
Evaluate against current context.

AST example:

    +
   / \
 A1   B1

6.2 Dependency Graph Model

Directed graph where edges point from precedent to dependent.

Example:

graph LR
    A1 --> C1
    B1 --> C1
    C1 --> D1

6.3 Incremental Recalculation Strategy

If A1 changes:

Mark impacted descendants dirty.
Recompute in topological order.
Emit only changed cells as delta patch.

Avoid full-sheet recomputation.

6.4 Circular References and Error Propagation

Detect cycles during dependency updates.
Mark cycle participants with deterministic circular-reference error state.
Propagate dependent errors with stable precedence rules.

7. High Level Data Flow Explanation

7.1 Initial Load Flow

Client loads workbook metadata and initial viewport chunks.
Renderer mounts virtual window.
Formula cache warms for visible cells.
Collaboration channel subscribes to document updates.

7.2 Cell Edit Flow (Optimistic + Authoritative Reconcile)

sequenceDiagram
    participant UI as Frontend UI
    participant SY as Sync Engine
    participant CS as Collaboration Server
    participant DG as Calc Server

    UI->>SY: Local change event (A1=500)
    SY->>UI: Optimistic paint
    SY->>CS: Send op with base version
    CS->>DG: Apply change and find impacted cells
    DG-->>CS: Recomputed delta (A1, C1, D1...)
    CS-->>SY: Authoritative patch + new version
    SY-->>UI: Reconcile local state and repaint viewport

7.3 Error and Retry Flow

If request fails, operation remains in pending queue.
Sync engine retries with backoff.
On reconnect, pending operations are replayed with version checks.
Diverged optimistic state is corrected by authoritative patch.

8. Data Modelling

8.1 Core Entities

Workbook
Sheet
Cell
Operation (edit, format, structural change)
Dependency edge

8.2 Data Shape

{
  "id": "A1",
  "value": 10,
  "formula": "=B1+C1",
  "type": "number",
  "format": "general",
  "version": 42
}

Notes:

value: computed/display value.
formula: expression entered by user.
version: monotonic version used for reconciliation.

8.3 Backend Storage Split

Metadata DB (SQL): owner, ACL, sharing, lifecycle metadata.
Cell State Store (distributed KV/document):
- Key: spreadsheetId:sheetId:cellId
- Value: formula, computed value, format, version
Append Log (optional): replay/history/audit support.

9. State Management Strategy

9.1 State Classification

UI State: selection, active cell, editing mode, scroll offsets.
Data State: visible cells, formula map, dependency metadata.
Network State: pending operations, in-flight requests, connection state.

9.2 State Ownership

Grid subsystem owns viewport and recycle pool state.
Formula subsystem owns parsed expressions and local eval cache.
Sync subsystem owns operation queue, versions, and reconciliation markers.

9.3 Persistence and Recovery

Persist lightweight session cache for faster resume.
Recover with server snapshot + operation replay after reconnect.

10. Real Time Collaboration and Conflict Handling

10.1 Operation Model

Each operation includes:

Document/sheet/cell target
Intent (set value, set formula, format, structural change)
Base revision/version
Operation id (idempotency)

10.2 OT vs CRDT (Spreadsheet Context)

OT: central ordering + transform logic, simpler integration with authoritative server pipeline.
CRDT: peer-friendly conflict-free merges, often higher metadata complexity.

For spreadsheet workloads with central authoritative compute, OT-style sequencing with deterministic server merge is commonly pragmatic.

10.3 Presence, Cursor, and Selection Sync

Presence channel broadcasts user online status.
Cursor/selection updates are ephemeral and throttled.
Presence events are separated from durable cell operations.

11. High Level API Design

11.1 Required APIs

GET /workbooks/:id -> workbook metadata
GET /sheets/:id/chunks?range=... -> chunked cell data
POST /operations/batch -> submit versioned operations
GET /revisions/:workbookId?since=... -> incremental sync
WS /collab/:workbookId -> real-time patches and presence

11.2 Request and Response Shape

Request includes baseVersion, opId, and operation payload.
Response includes accepted version and minimal delta patch.

11.3 Versioning and Idempotency

Reject or rebase stale operations.
Deduplicate retries using operation id.
Ensure replay safety after reconnect.

12. Caching, Chunking, and Large Dataset Strategy

Lazy fetch only visible and near-visible chunks.
Keep LRU cache of recently visited chunks.
Prefetch in scroll direction to hide network latency.
Use delta compression for patches.
Optional hybrid storage path:
- Row/cell oriented for transactional edits.
- Columnar paths for heavy analytical scans.

13. Cross Cutting Non Functional Concerns

13.1 Security

Authenticated APIs and WebSocket channels.
Workbook/sheet ACL enforcement server-side.
TLS in transit and strict audit trails for critical actions.

13.2 Accessibility

Full keyboard navigation for cell traversal and editing.
Screen reader announcements for active cell and formula errors.
Focus management during edit mode transitions.

13.3 Performance Optimization

Virtualization + overscan + recycling.
Batched paints and minimized style/layout thrash.
Incremental graph recompute and delta fanout.

13.4 Observability and Reliability

Metrics: edit latency, recalc latency, patch size, dropped frames, reconnect rate.
Tracing across UI edit -> sync -> calc -> patch apply.
Alerting on recalculation backlog and collaboration lag.

14. Edge Cases and Tradeoffs

Very large paste operations: chunk parse/apply to avoid UI lockups.
Formula storms: throttle non-critical recalcs; prioritize visible range updates.
Concurrent edits on same cell: deterministic server ordering and last accepted version policy.
Offline edits: queue operations and reconcile on reconnect.
Tradeoff: larger overscan improves smoothness but increases memory and CPU cost.
Tradeoff: aggressive local eval improves UX but increases potential rollback frequency.

15. Interview Summary

Problem	Primary Solution
Millions of cells	Virtualized rendering
Scroll jank	Windowing + DOM recycling
Fast formula feedback	Client-side parse/eval + AST
Correct dependent updates	Server-maintained dependency graph
High update throughput	Incremental recomputation + deltas
Huge datasets	Lazy chunk loading + cache
Multi-user editing	Versioned operations with deterministic merge

Final Mental Model

Google Sheets behaves like a virtualized UI over a distributed reactive compute graph.
Frontend guarantees interaction speed, while backend guarantees convergence and correctness.

More Details:

Get all articles related to system design
Hashtag: SystemDesignWithZeeshanAli

systemdesignwithzeeshanali

Git: https://github.com/ZeeshanAli-0704/front-end-system-design

Frontend System Design: WebSocket Architecture

ZeeshanAli-0704 — Sun, 28 Jun 2026 16:24:54 +0000

Frontend System Design: WebSocket Architecture (Beginner Friendly, Full Theory)

A from-scratch guide to designing a real-time frontend with WebSocket, explained for someone reading about it for the first time. We use a Slack-like chat app as the running example and slowly build up from "what problem are we even solving" to "how do we scale this to millions of users".

1. The Problem WebSocket Solves
- 1.1 How the Web Normally Works Request and Response
- 1.2 The Four Ways to Get Live Updates
- 1.3 What a WebSocket Actually Is
2. The Slack Example in Plain English
3. Functional Requirements What the App Must Do
- 3.1 Connect Once
- 3.2 Subscribe to Needed Channels Only
- 3.3 Receive and Process Events
- 3.4 Send User Actions
- 3.5 Recover Automatically
- 3.6 Multi Tab Behavior
4. Non Functional Requirements How Well It Must Do It
5. High Level Architecture
6. Data Flow Walk Throughs
- 6.1 Initial Load
- 6.2 Sending a Message
- 6.3 On Network Drop
7. Data Model
- 7.1 Event Schema Versioning and Compatibility
8. State Management
9. API Design From the Frontend View
- 9.1 Delivery Guarantees and Failure Semantics
10. Caching Rendering and Performance
- 10.1 Connection Management Defaults
- 10.2 Client Backpressure and Memory Policy
11. Security and Reliability
- 11.1 Auth Lifecycle After Connect
12. Edge Cases
- 12.1 Protocol Fallback Strategy
13. WSS Token and Handshake Explained
- 13.1 End to End Sequence
- 13.2 API Count and Call Pattern
- 13.3 Token Fetch and Connect Flow
- 13.4 Handshake Headers
- 13.5 First Messages After Handshake
- 13.6 Failure Cases
- 13.7 Token Mechanism in Simple Terms
14. WebSocket Internals and Scaling
- 14.1 How WebSocket Works Internally
- 14.2 Internal Components on the Backend
- 14.3 Scaling Stages From One to Millions
- Why Scaling Sockets Is Hard
- Stage A One Server
- Sticky Sessions Explained
- What the Load Balancer Actually Does
- Stage B Many Servers and Shared State
- Fan Out Explained With Numbers
- The Event Bus Explained
- Partitioning Explained
- Stage C Putting It All Together
- Hot Channels and Hot Connections
- Migration Checklist
- 14.4 How Traffic Is Handled Safely
- Backpressure Explained
- Rate Limiting Explained
- Fan Out Control Explained
- Slow Consumer Handling Explained
- Replay and Recovery Explained
- 14.5 Capacity Metrics to Track
- 14.6 Deep Theory Kafka Routing Table and Consumers
- 14.7 Ordering Policy
- 14.8 Observability SLOs and Alerts
- 14.9 Testing Strategy and Validation Gates
15. Final Summary

1. The Problem WebSocket Solves

Before we talk about WebSocket, we need to understand why it exists at all. If you are new, start here — everything later builds on this.

1.1 How the Web Normally Works Request and Response

The normal web works on a simple rule: the browser asks, the server answers, and then the conversation ends.

Browser:  "Hey server, give me the messages."   (request)
Server:   "Here they are."                        (response)
--- connection closes, conversation over ---

This is called the request-response model (HTTP). It is like sending a letter in the mail: you send one letter, you get one letter back, and if you want more you must send another letter.

This works great for loading a web page. But chat apps have a problem: new messages arrive at random times, and the server has no way to reach the browser after the response is sent. The mailbox is closed. The server cannot "push" a new message to you because there is no open line to talk through.

So how do we get live updates? There are four classic approaches. Let's build them up one at a time.

⬆ Back to Top

1.2 The Four Ways to Get Live Updates

1) Short Polling — "Are we there yet?"

The browser keeps asking again and again on a timer.

every 3 seconds:  Browser -> "Any new messages?" -> Server -> "No."
                  Browser -> "Any new messages?" -> Server -> "No."
                  Browser -> "Any new messages?" -> Server -> "Yes! Here."

Simple, works everywhere.
Wasteful: most requests return "nothing new". And a message can sit up to 3 seconds before you see it.

2) Long Polling — "Tell me when you know."

The browser asks, but the server holds the request open and only answers when there is actually something new. Then the browser immediately asks again.

Feels near real-time, no special protocol needed.
But every waiting user ties up a server connection, and you keep re-opening requests.

3) Server-Sent Events (SSE) — "Keep talking, I'm listening."

The server keeps one connection open and streams updates to the browser. But it is one-way: server can talk to browser, browser cannot talk back on that same channel.

Great for feeds, notifications, progress bars.
Not ideal for chat, where the browser also needs to send messages, typing signals, etc.

4) WebSocket — "Let's keep a phone line open both ways."

The browser and server open one connection that stays open, and both sides can send messages at any time. This is exactly what a chat app wants.

Approach	Live?	Two-way?	Cost	Best for
Short polling	Delayed	Yes (new request each time)	Wasteful	Simple status checks
Long polling	Almost	Yes (new request each time)	Medium	Near-real-time without sockets
SSE	Yes	No (server → client only)	Low	Feeds, notifications, progress
WebSocket	Yes	Yes (both directions)	Low per message	Chat, presence, collaboration

⬆ Back to Top

1.3 What a WebSocket Actually Is

In plain words:

A WebSocket is one live connection between the browser and the server.
Once it is open, it stays open.
Both sides can send data at any time, instantly, without starting a new request each time.
You do not need to refresh the page to see new data.

A good analogy: HTTP polling is like texting ("any news? … any news? … any news?"). A WebSocket is like a phone call that stays connected — either person can speak the moment they have something to say.

The system we design in this whole document is:

A Slack-like chat app with channels, direct messages, typing indicators, and presence (who is online).

Keep that picture in your head. Everything below serves that app.

⬆ Back to Top

2. The Slack Example in Plain English

Let's walk through what happens when you use Slack, step by step, with no jargon:

You open Slack in your browser.
The app logs you in and opens one live socket (the phone line).
The app subscribes to the channels you care about (tells the server "send me updates for these rooms").
A teammate sends a message — it appears instantly on your screen.
You send a message — it shows sending, and a moment later becomes sent once the server confirms it saved.
Your internet drops for a few seconds — the app quietly reconnects and catches up on anything you missed, so you never notice a gap.

That's the whole experience. The rest of this document explains how to build each of those six behaviors correctly and reliably.

⬆ Back to Top

3. Functional Requirements What the App Must Do

"Functional requirements" just means: the list of things the app is supposed to do. Here are ours, each explained.

3.1 Connect Once

Goal: after login, open a single WebSocket connection and keep it healthy.

Why once? Because each open connection costs memory and resources on the server. One user should not open five sockets. We open one and reuse it for everything.

The UI should always show the user what state the connection is in, because a silent failure is confusing:

connecting — we are opening the line.
connected — live and working.
reconnecting — we lost it and are trying again.
offline — we gave up for now and will retry.

3.2 Subscribe to Needed Channels Only

Goal: only ask for updates you actually need right now.

A big workspace might have thousands of channels. You do not want updates from all of them — that would flood the browser. So the client subscribes only to the relevant ones.

Where does the "relevant" list come from?

A bootstrap API at startup (gives your workspace info).
Your membership data (channels and DMs you belong to).
The current screen (the channel or thread you have open right now).

Simple rule:

Subscribed channels = channels you are allowed to see ∩ channels you actually need right now.

3.3 Receive and Process Events

Goal: when an event arrives, update the right part of the UI — correctly.

Examples of events and what they do:

message.created → add the message to the thread and update the sidebar preview.
presence.updated → turn a user's online dot green or grey.

Two subtle problems every real-time app must handle:

Duplicates: the same event may arrive twice (networks retry). We ignore repeats using a unique eventId.
Order: events can arrive out of order. We keep them in the right order using a sequence number.

3.4 Send User Actions

Goal: when the user does something (sends a message), make the UI feel instant.

We use a trick called optimistic UI:

User clicks send.
We immediately show the message bubble with a sending status — before the server even replies.
The server saves it and sends back an ack (acknowledgement).
We flip the bubble to sent.
If it fails, we show a retry button.

This makes the app feel fast even though the round-trip takes time.

3.5 Recover Automatically

Goal: survive network drops without the user losing data or context.

The recovery loop:

Detect the disconnect (heartbeat stops responding).
Reconnect using backoff (wait a bit longer between each retry so we do not hammer the server).
Resubscribe to the channels we had.
Replay the events we missed while offline, starting from the last sequence we saw.

3.6 Multi Tab Behavior

Goal: if the user opens the app in several browser tabs, do not open several sockets.

The clean pattern is a leader tab:

One tab is elected the leader and owns the single WebSocket.
Other tabs are followers and receive the same updates through a BroadcastChannel or a SharedWorker.
If the leader tab closes, the remaining tabs elect a new leader, which opens the socket.

    Tab A (leader)            BroadcastChannel             Tab B (follower)
        |                           |                            |
        |==== owns WebSocket ======>|                            |
        |<=== receives live events =|                            |
        |--- publish updates ------>|--- deliver updates ------->|
        |                           |                            |
        |---- closes/crashes ----X  |                            |
        |                           |<-- election heartbeat -----|
        |                           |--- Tab B becomes leader -->|
        |                           |==== Tab B opens socket ===>|

⬆ Back to Top

4. Non Functional Requirements How Well It Must Do It

"Non-functional requirements" means: not what it does, but how well it does it — the quality bar.

Fast: chat should feel instant. Target sub-second delivery.
Reliable: if the network hiccups, reconnect and recover on its own without losing messages.
Scalable: only subscribe to needed data, so one user does not pull the whole workspace.
Secure: the socket must be authenticated, and the server must check that the user is allowed in each channel.
Usable: the user should always be able to tell whether they are connected.

⬆ Back to Top

5. High Level Architecture

Think of the frontend as four layers stacked on top of each other, each with one job. This separation keeps the code understandable.

UI  ->  State  ->  Realtime  ->  API

UI layer — what the user sees: the channel list, the message thread, the message box. It only knows how to draw things.
State layer — the app's memory: messages, unread counts, presence, connection status. The UI reads from here.
Realtime layer — the socket manager: opening the connection, subscribing, reconnecting, replaying missed events. It feeds the state layer.
API layer — plain HTTPS calls used to bootstrap, fetch a snapshot of a channel, and replay missed events.

Why layer it this way? Because the UI should not care how a message arrived (socket vs replay vs snapshot). It just reads the state layer. The realtime and API layers do the messy work and keep the state layer up to date.

⬆ Back to Top

6. Data Flow Walk Throughs

Now let's trace real scenarios end to end. Read the diagrams left to right, top to bottom — each arrow is one step.

6.1 Initial Load

What happens the moment you open the app:

You log in.
The app calls the bootstrap API to learn your workspace, channels, and where to connect.
The app opens the WebSocket and authenticates it.
The app subscribes to the channels you need.
The app asks the replay API for anything it missed since last time.

    Browser                 App API                  WSS Gateway            Replay API
        |                       |                           |                     |
        |--- login/session ---->|                           |                     |
        |--- GET /bootstrap --->|                           |                     |
        |<-- wsUrl/channels ----|                           |                     |
        |--- POST /token ------>|                           |                     |
        |<-- wsToken -----------|                           |                     |
        |==================== open wss://...token ==============================>|
        |-------------------- subscribe(channel, fromSeq) ----------------------->|
        |--- GET /replay?fromSeq=cursor ----------------------------------------->|
        |<-- missed events -------------------------------------------------------|

6.2 Sending a Message

Notice the optimistic bubble appears before the server replies — that is what makes it feel instant.

You type and click send.
The message bubble appears immediately in sending state.
The command travels over the socket.
The server saves it and sends back an ack.
The bubble becomes sent.

    User/UI                   Browser Socket              WSS Gateway            Storage
        |                             |                         |                     |
        |-- click send -------------->|                         |                     |
        |  add optimistic bubble      |                         |                     |
        |                             |--- message.send ------->|                     |
        |                             |                         |--- persist --------->|
        |                             |                         |<-- saved id --------|
        |                             |<-- message.ack ---------|                     |
        |<-- optimistic -> sent ------|                         |                     |

6.3 On Network Drop

The key idea: backoff (waiting longer each retry) plus replay (asking only for what you missed).

The socket disconnects.
Reconnect begins, waiting 1s, then 2s, then 4s between tries.
After reconnecting, resubscribe.
Replay the missed events and continue as if nothing happened.

    Browser Client              Network              WSS Gateway             Replay API
        |                           |                      |                      |
        |<====== live stream ======>|                      |                      |
        |-------- X disconnect -----|                      |                      |
        | wait 1s, 2s, 4s           |                      |                      |
        |================ reconnect wss ===================>|                      |
        |---------------- resubscribe(fromSeq) ----------->|                      |
        |---------------- GET /replay?fromSeq=last ------->|--------------------->|
        |<--------------- missed events ------------------------------------------|
        | UI catches up and continues live                 |                      |

⬆ Back to Top

7. Data Model

The data model is the shape of the information the app keeps track of. Four core ideas:

ConnectionState — is the socket connecting, connected, reconnecting, or offline?
ChannelSubscription — which channels are we currently listening to?
EventEnvelope — the standard "wrapper" every event comes in.
ReplayCursor — a bookmark (sequence) of the last event we successfully processed.

Every event the server sends is wrapped in the same envelope so the client can handle them uniformly:

type EventEnvelope<T> = {
  eventId: string;   // unique id, used to ignore duplicates
  sequence: number;  // ordering number within a channel
  channel: string;   // which channel this belongs to
  type: string;      // e.g. "message.created"
  payload: T;        // the actual event data
};

7.1 Event Schema Versioning and Compatibility

The problem: you will change the shape of events over time (add fields, rename things). But not everyone updates their app at the same moment. An old tab open for two days should not crash when it receives a new-shaped event.

The solution: version your events from day one and prefer additive changes.

Simple rules:

Put a schemaVersion in every envelope.
Prefer adding new optional fields over changing or removing existing ones.
Never remove or rename a required field without bumping the version.
Support at least the previous client version (N-1) during a rollout.

Example envelope with a version:

{
  "eventId": "evt_123",
  "schemaVersion": 2,
  "channel": "channel:engineering",
  "type": "message.created",
  "payload": {
    "id": "m_1",
    "text": "hello",
    "mentions": []
  }
}

Safe deprecation flow (how to retire an old field without breaking anyone):

Introduce the new optional field alongside the old one.
Ship clients that can read both shapes.
Mark the old field deprecated in the API contract.
Remove the old field only after the upgrade window closes.

⬆ Back to Top

8. State Management

Not all state is equal. Organizing it by scope keeps the app predictable.

Global state (affects the whole app):
- socket status
- subscribed channels
- replay cursor
Feature state (belongs to the chat feature):
- messages
- unread counts
- presence
Local state (only one component cares):
- the draft text in the message box
- whether a side panel is open

Rule of thumb: keep state at the narrowest scope that works. Draft text does not belong in global state; socket status does.

⬆ Back to Top

9. API Design From the Frontend View

Even a real-time app needs a few normal HTTPS APIs — the socket is not the only channel. Here are the four core ones:

GET /realtime/bootstrap — startup info: socket URL, allowed channels, cursor hints.
GET /snapshot/{channel} — the current state of a channel (used on a cache miss).
GET /replay/{channel}?fromSeq=... — only the events you missed after a gap.
POST /realtime/token — a short-lived token used to open the socket.

How many APIs, and when is each called?

Total core APIs: 4
Always called on startup: 2
- GET /realtime/bootstrap
- POST /realtime/token
Called only when needed: 2
- GET /snapshot/{channel}
- GET /replay/{channel}?fromSeq=...

Step by step:

GET /realtime/bootstrap — right after login/page load. Gives the socket URL, allowed channels, and cursor hints.
POST /realtime/token — just before opening wss://. Returns the short-lived socket token.
GET /snapshot/{channel} — when a channel's data is not already cached.
GET /replay/{channel}?fromSeq=... — after a reconnect or a detected gap in sequence. Returns only the missed events.

Example subscribe message sent over the socket:

{
  "subscribe": {
    "channel": "channel:engineering",
    "fromSequence": 1234
  }
}

9.1 Delivery Guarantees and Failure Semantics

This sounds academic but it decides whether users ever see duplicate or missing messages. Let's define the terms simply.

At-most-once: no duplicates, but a message can be lost on failure.
At-least-once: no loss, but a retry can create a duplicate.
Effectively-once (at the UI): the transport may duplicate, but the client dedupes using eventId + sequence, so the user sees each message exactly once.

For chat, the recommended model is:

Transport: at-least-once (duplicates possible, loss unlikely).
UI: effectively-once (dedupe hides the duplicates).
Ordering: guaranteed per channel, not globally across all channels.

Failure situations to write down in your API contract:

Publisher timeout: the client shows a retry.
Ack lost but the write actually succeeded: the retry may create a duplicate → dedupe must catch it.
Replay overlap: replay may include events you already saw → dedupe handles it.

⬆ Back to Top

10. Caching Rendering and Performance

A real-time app can receive hundreds of events per second. If you re-render everything on every event, the UI will stutter. Performance rules:

Keep the current chat state in memory for instant access.
Store the replay cursor in IndexedDB / local storage so you can catch up after a full reload.
Render only the parts that changed, not the whole screen.
Use virtualization for long message lists (only render the rows on screen).
Batch frequent events so you re-render once per frame, not once per event.

10.1 Connection Management Defaults

Concrete starting numbers so behavior is predictable (tune later from real data):

Heartbeat interval: 25s
Heartbeat timeout: 10s
Reconnect backoff: 1s, 2s, 4s, 8s, 16s (cap at 30s)
Reconnect jitter: ±20% (randomize so all clients do not reconnect at the same instant)
Max reconnect attempts before showing an offline banner: 8
Max channels per socket (soft limit): 200
Max inbound frame size: 64 KB
Max outbound buffer per socket: 1 MB

Why jitter? If 10,000 users all disconnect at once (a server blip) and all reconnect at exactly 2s, they create a stampede. Random jitter spreads them out.

10.2 Client Backpressure and Memory Policy

Backpressure means: what to do when events arrive faster than the UI can handle. The client must never let its queue grow forever, or it will run out of memory.

Recommended policy:

Keep a bounded in-memory event queue (for example 5,000 events).
Prioritize the visible channel over background channels.
Coalesce high-frequency events (presence.updated, typing) — collapse many into one.
When the queue is nearly full:
- Drop non-critical transient events.
- Keep critical durable events (message.created, moderation actions).
When the queue overflows:
- Trigger a replay resync from the last stable sequence.
- Show a subtle "syncing" indicator.

⬆ Back to Top

11. Security and Reliability

Security basics:

Use wss:// only (the encrypted version of WebSocket, like HTTPS is to HTTP).
Validate the auth token when the socket connects.
Check channel permission on the server — never trust the client to only subscribe to allowed channels.

Reliability basics:

Heartbeat ping/pong to detect dead connections.
Reconnect with backoff.
Replay missed events.
Dedupe by eventId.

11.1 Auth Lifecycle After Connect

Important idea for beginners: authentication is not a one-time check at connect. Permissions can change while the socket is open, and the server must handle that.

Runtime cases to handle:

Session revoked (user logs out on another device):
- Server sends an auth.revoked control event.
- Client clears local auth and redirects to login.
Permission changed while connected (user removed from a channel):
- The next subscribe/publish for that channel must fail authorization.
- The server can also proactively push channel.access.revoked.
Token nearing expiry:
- Client fetches a fresh socket token before reconnecting.
- Never keep using a stale long-lived token.

Auth Service           Gateway                Client
    |                     |                     |
    |-- revoke user ----->|                     |
    |                     |-- auth.revoked ---->|
    |                     |<-- close/ack -------|
    |                     |                     |
    |                     |  client clears state |

⬆ Back to Top

12. Edge Cases

The situations that break naive implementations:

Tab sleeps (laptop closed): on resume, reconnect and replay.
Duplicate delivery: ignore by eventId.
Out-of-order delivery: fix using sequence.
Multiple tabs: use the leader-tab pattern (Section 3.6).

12.1 Protocol Fallback Strategy

The problem: some corporate networks and proxies block WebSocket. Your app must still work.

The fallback order — try the best first, degrade gracefully:

Try WebSocket (wss://).
If the upgrade repeatedly fails, fall back to SSE.
If SSE also fails, fall back to long-polling.

What you lose at each step:

WebSocket: full two-way real-time.
SSE: you still receive updates in real-time; your sends go over normal HTTP instead.
Long-poll: highest latency and cost — keep only the essential updates.

Client rule: remember the current transport in memory, and periodically retry WebSocket (say every 5–10 minutes) in case the network situation improves.

⬆ Back to Top

13. WSS Token and Handshake Explained

This section answers a very common beginner question: how does the socket get authenticated, and what actually happens when it "connects"?

The secure pattern in four steps:

The client gets a short-lived socket token using a normal HTTPS API (you are already logged in).
The client opens a wss:// connection using that token.
The server validates the token and upgrades the connection from HTTP to WebSocket.
After connecting, the client sends subscribe frames.

Important safety notes:

Keep the socket token short-lived (for example 1–5 minutes).
Prefer a dedicated ephemeral socket token, not your long-lived access token.
Never hardcode a real production token in frontend code.

13.1 End to End Sequence

+---------+        +-------------------+        +-------------------+        +----------------+
| Browser |        | App API           |        | Token API         |        | WSS Gateway    |
+---------+        +-------------------+        +-------------------+        +----------------+
|                        |                           |                            |
| (A) user already logged in                         |                            |
|----------------------->|                           |                            |
|                        |                           |                            |
| (1) GET /realtime/bootstrap                        |                            |
|----------------------->|                           |                            |
|<-----------------------| 200 { wsUrl, allowedChannels, cursorHints }            |
|                        |                           |                            |
| (2) POST /realtime/token                           |                            |
|----------------------------------->|               |                            |
|<-----------------------------------| 200 { wsToken, exp }                        |
|                        |                           |                            |
| (3) GET /snapshot/{channel} (optional, cache miss)                             |
|----------------------->|                           |                            |
|<-----------------------| 200 { initial channel state }                          |
|                        |                           |                            |
| (4) Open WSS: wss://rt.example.com/ws?token=...                                |
|--------------------------------------------------------------------------->     |
|<---------------------------------------------------------------------------     |
|                         101 Switching Protocols (Upgrade success)               |
|                                                                                    
| (5) WS frame: subscribe(channel:engineering, fromSeq:1234)                     |
|--------------------------------------------------------------------------->     |
| (6) WS frame: connection.ack(conn_7f2a)                                         |
|<---------------------------------------------------------------------------     |
|                                                                                    
| (7) On reconnect/gap -> GET /replay/{channel}?fromSeq=1234                      |
|----------------------->|                                                          |
|<-----------------------| 200 { missedEvents:[...] }                              |

13.2 API Count and Call Pattern

Core APIs = 4

[Always]
1) GET  /realtime/bootstrap
2) POST /realtime/token

[Conditional]
3) GET  /snapshot/{channel}
4) GET  /replay/{channel}?fromSeq=...

13.3 Token Fetch and Connect Flow

Browser Client                               API/Gateway
--------------                               -----------
1) HTTPS login already done

2) GET /realtime/token  ------------------->  validate session
   (cookie/JWT)

3) <-------------------------- 200 { wsToken: "eyJ...abc", exp: 60s }

4) new WebSocket(
     "wss://rt.example.com/ws?token=eyJ...abc"
   )

5) HTTP Upgrade request ------------------->  verify token + claims
                                              check exp, userId, tenantId

6) <-------------------------- 101 Switching Protocols (Upgrade success)

7) send subscribe frame ------------------->  start streaming events

13.4 Handshake Headers

What is a handshake? Even a wss:// connection starts as a normal HTTP request that politely asks "can we upgrade this to a WebSocket?" The server agrees with a special 101 response. After that, it is a WebSocket.

The browser's upgrade request:

GET /ws?token=eyJ...abc HTTP/1.1
Host: rt.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Origin: https://app.example.com

The server's acceptance:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=

That 101 Switching Protocols is the moment the connection stops being HTTP and becomes a live two-way WebSocket.

13.5 First Messages After Handshake

The client's first frame — "please stream me this channel from where I left off":

{
  "type": "subscribe",
  "channel": "channel:engineering",
  "fromSequence": 1234
}

The server's acknowledgement — "you are connected, here is your connection id":

{
  "type": "connection.ack",
  "connectionId": "conn_7f2a",
  "userId": "u_42"
}

13.6 Failure Cases

token expired -> server rejects upgrade or closes with auth code -> client fetches new wsToken -> reconnect
invalid channel subscribe -> server sends error frame -> client does not retry that channel
network break -> reconnect with backoff -> resubscribe -> replay missed events

Case 1: token expired
Client ---- open wss(token_old) ----> Gateway
Client <--- auth close / reject ----- Gateway
Client ---- POST /realtime/token ---> API
Client <--- new wsToken ------------- API
Client ---- open wss(token_new) ----> Gateway

Case 2: invalid subscribe
Client ---- subscribe(private:admin) -> Gateway
Client <--- error.not_authorized ----- Gateway
Client ---- stop retry for this chan -> (client rule)

Case 3: network break
Client ----X socket lost X----------- Gateway
Client ---- reconnect + subscribe ---> Gateway
Client ---- GET /replay?fromSeq ----> API
Client <--- missed events ----------- API

13.7 Token Mechanism in Simple Terms

The five stages, in order:

Normal login — user signs in with password/SSO; server creates an authenticated session (cookie or access token).
Socket token exchange — client calls POST /realtime/token with that session; server returns a short-lived wsToken.
Handshake auth — client opens wss://.../ws?token=wsToken; the gateway validates it and replies 101 Switching Protocols. The connection is now tied to that user.
Authorization after connect — authentication says who you are; authorization says which channels you may access. The server checks permission on every subscribe.
Reconnect + refresh — if the socket drops and the token expired, fetch a new wsToken, reconnect, resubscribe, replay.

Security checklist:

Use only wss://.
Keep the socket token very short-lived (1–5 min).
Do not expose a long-lived auth token in the socket URL.
Do not log full tokens anywhere.

⬆ Back to Top

14. WebSocket Internals and Scaling

Now we go under the hood: how a WebSocket works internally, and how the system grows from one user to millions. This is where system-design interviews spend most of their time.

14.1 How WebSocket Works Internally

First, clear up a common confusion:

In your code you write new WebSocket("wss://...").
Under the hood, the browser sends an ordinary HTTPS request with an Upgrade: websocket header.
The server replies 101 Switching Protocols.
After that 101, the connection stops speaking HTTP and starts speaking WebSocket frames.

The lifecycle:

HTTP starts it — client sends a request with Upgrade: websocket.
Server upgrades it — replies 101; now it is a persistent, full-duplex connection.
Frames flow — data travels as small frames (not full HTTP responses), and either side can send at any time.
Keep-alive — periodic ping/pong frames check the connection is still alive; if a pong is missed, the client reconnects.
Lifecycle — connect → authenticate → subscribe → stream events → reconnect if broken.

14.2 Internal Components on the Backend

You do not build all of this on the frontend, but knowing it helps you reason about failures.

+----------------+      +----------------+      +-------------------+
|  Clients (Web) | ---> |  WSS Gateway   | ---> |  Event Router      |
+----------------+      +----------------+      +-------------------+
        |                         |
        v                         v
   +----------------+       +-------------------+
   | Presence Store |       | Message/Event Bus |
   +----------------+       +-------------------+
        |                         |
        +-----------+-------------+
                    |
                    v
          +---------------------+
          | Channel Subscribers |
          +---------------------+

What each piece does:

WSS Gateway — accepts socket connections and authenticates them.
Event Router — sends each event to the correct channel's subscribers.
Presence Store — tracks who is online.
Event Bus — distributes events across many backend servers.

14.3 Scaling Stages From One to Millions

This is the heart of a real-time system-design interview, so we will go very slowly and explain every term from scratch. By the end you should understand why each piece (sticky sessions, load balancer, event bus, fan-out, partitioning) exists and what problem it solves.

Why Scaling Sockets Is Hard

Start with the single most important idea:

A normal HTTP request is like a quick phone call — you call, get your answer, and hang up in a few milliseconds. A WebSocket is like leaving the phone line open all day.

That one difference changes everything:

With HTTP, a single server can handle huge traffic because each request is over in a blink. The server is never "full" — connections are constantly freed up.
With WebSocket, every connected user permanently occupies a slot on one server: some memory, one network socket (a "file descriptor"), and a little CPU for heartbeats. If 50,000 users are online, that is 50,000 open lines sitting there — even when nobody is typing.

And there is a second, bigger cost: fan-out. When one person posts in a channel with 10,000 members, the system must copy that one message out to 10,000 different connections. One input, ten thousand outputs. This multiplication is the real scaling monster, and most of this section is about taming it.

So we have two enemies:

Too many long-lived connections for one server to hold.
Fan-out — one message exploding into many deliveries.

We now grow the system in three stages, adding one tool at a time to fight these two enemies.

Stage A One Server

Situation: 1 to ~100 users. Everything fits on a single server (we call it a gateway — the server that holds WebSocket connections).

How it keeps track of who wants what: a simple lookup table in the server's memory called a subscription map:

channelId              ->  list of connections listening to it
---------------------------------------------------------------
"channel:engineering"  ->  [conn_1, conn_5, conn_9]
"channel:random"       ->  [conn_2, conn_5]

When a message arrives for channel:engineering, the server looks up that row and pushes the message to conn_1, conn_5, and conn_9. Done.

✅ Simple. Easy to build and debug.
❌ Single point of failure — if this one server crashes or you deploy new code, every user is disconnected at once.
❌ Cannot grow — one machine has a ceiling on how many open sockets it can hold.

This is fine for a demo, but a real app cannot live on one server. So we add more.

Sticky Sessions Explained

The moment you run two or more gateways, a new problem appears. Picture it:

A user's WebSocket is a long-lived, open line to one specific server — say Gateway 1.
All of that user's state (which channels they subscribed to, their presence) is living in Gateway 1's memory.
Now their Wi-Fi blips and they reconnect. The load balancer might send them to Gateway 2 this time — which knows nothing about them. Gateway 2 has to rebuild everything from scratch.

Sticky sessions (also called session affinity) fix this: they tell the load balancer "once a user lands on Gateway 1, keep sending that same user back to Gateway 1."

A simple analogy:

Sticky sessions are like having your own regular barista. They already remember your order, so every visit is fast. Without stickiness, you get a random new barista each time and must re-explain your whole order.

How the load balancer decides who is "sticky" to which server:

Cookie affinity — the load balancer sets a cookie remembering your server.
Source-IP hash — route by the user's IP address (less reliable on mobile, where IPs change).
Consistent hashing on userId / tenantId — a math function that always maps the same user to the same server, and (importantly) reshuffles as few users as possible when a server is added or removed.

Note: sticky sessions are a helpful optimization, not a correctness requirement. Because we also store important state in a shared database (next section), a user can survive landing on a different server — it is just slower. Stickiness makes the common case fast.

What the Load Balancer Actually Does

Beginners often think the load balancer "delivers messages." It does not. Its job is much narrower:

Admission — accept the incoming connection, terminate TLS (the s in wss), and pick which gateway this new connection should attach to.
Placement on reconnect — honor stickiness so a returning user goes back to a sensible server.

That is it. The load balancer is a receptionist at the front door — it points you to a desk. It does not carry messages between desks. Moving messages between servers is a totally different job, handled by the event bus (coming up).

Stage B Many Servers and Shared State

Situation: hundreds to ~10,000 users. One server is not enough, so we run multiple gateways behind a load balancer.

Why we are forced to do this:

One server cannot hold every socket forever (memory/socket limits).
You need to deploy new code without disconnecting everyone (rolling deploys — restart servers one at a time).
If one server dies, users on the other servers should be unaffected (failover).

But splitting across servers creates a knowledge problem: user Alice is on Gateway 1, user Bob is on Gateway 2, and neither server knows about the other's users. If presence ("who is online") lives only in each server's private memory, Gateway 1 has no idea Bob is online.

The fix: move shared knowledge out of any single server's memory into a shared store that all servers can read — commonly Redis (a very fast in-memory database).

What moves into the shared store:

Presence — who is online, last-seen times.
Routing metadata — which server currently holds which connections (so other servers can find them).

            +----------------+
 Gateway 1  |                |  Gateway 2
  (Alice)   |     Redis      |   (Bob)
     \      | shared memory  |    /
      \---> | presence,      | <--/
            | routing table  |
            +----------------+

Now any server can answer "is Bob online, and where is he connected?" by asking Redis. But we still have not solved delivery across servers. That is the event bus.

Fan Out Explained With Numbers

Let's make fan-out concrete, because it is the reason the rest of the architecture exists.

Fan-out = taking one incoming message and copying it out to every subscriber.

Imagine a channel with 10,000 members, and it is a busy channel getting 5 messages per second:

5 messages/sec  ×  10,000 subscribers  =  50,000 outbound deliveries/sec

One small input (5/sec) becomes a huge output (50,000/sec). Now imagine that channel's members are spread across 20 different gateways. Each of those 20 servers must push the message to its own slice of those 10,000 users.

So the message must somehow travel from the one server that received it, out to the other 19 servers, so each can deliver to its local users. How does a message hop from server to server? Through the event bus.

Analogy: fan-out is like a teacher making an announcement to a whole school. The teacher says it once (one input), but it must reach every classroom (many outputs). The PA system that carries it to every room is the event bus.

The Event Bus Explained

An event bus (also called pub/sub — publish/subscribe) is a central pipe that servers use to broadcast events to each other. The most common one is Kafka, but the idea is general.

Here is the whole point in one line:

A gateway that receives a message does not try to contact the other 19 gateways directly. It just publishes the message once to the event bus, and the bus takes care of getting it to whoever needs it.

Why this indirection is worth it:

Decoupling — the receiving server publishes once and moves on immediately. It does not need to know how many other servers exist or where they are. Servers can be added or removed freely.
Durability — Kafka writes events to a log on disk. If a server was briefly down, it can come back and replay the events it missed by reading the log from where it left off.
Buffering (backpressure) — if consumers are momentarily slow, events wait safely in the log instead of being lost.
Parallelism — the log is split into partitions (next section) so many servers can process different slices at the same time.

Gateway 1 receives Alice's message
        |
        |  publish ONCE
        v
   +-------------------+        every gateway that has
   |    Event Bus      | -----> subscribers for this channel
   |   (Kafka log)     |        reads it and delivers locally
   +-------------------+
        |        |        |
        v        v        v
   Gateway 1  Gateway 2  Gateway 3 ...  (each pushes to its own sockets)

Crucial detail beginners miss: the event bus does not know about individual browser sockets. Kafka just moves events between servers. The mapping of "which socket is on which server" still lives in the routing table (Redis). The bus carries the message near the right servers; the servers do the final push to the actual sockets.

Partitioning Explained

If every server had to read every message in the whole app, we would be back to one machine's worth of work on each machine — no real scaling. Partitioning is how we split the firehose into manageable lanes.

A partition is one ordered lane inside the event bus. The bus splits its log into many partitions, and each event is placed into a lane based on a partition key.

partition key = channelId

channel:engineering  --> always lane 3
channel:random       --> always lane 7
channel:design       --> always lane 3

Two big wins from choosing the channelId as the key:

Load spreads out. Different channels fall into different lanes, so 100 servers can each own a few lanes and work in parallel — no single server drowns.
Order is preserved within a channel. Because all of channel:engineering's events go into the same lane, and a lane is strictly ordered, messages in that channel are processed in the exact order they arrived. (This is why, later, we can promise "per-channel ordering" but not "global ordering across all channels" — different channels live in different lanes that move independently.)

Analogy: partitioning is like a post office sorting mail by zip code. Each zip code (channel) always goes to the same sorting bin (partition), so many workers can process different bins at once, and letters within one zip code stay in order.

Picking a good partition key matters:

Too coarse (e.g. key = workspaceId) → one giant workspace overloads a single lane.
Too fine (e.g. key = messageId) → you lose per-channel ordering.
channelId is usually the sweet spot for chat.

Stage C Putting It All Together

Situation: 10,000 to millions of users. Now we combine every tool above into one picture.

Users connect through a load balancer, which places them (stickily) onto a gateway in the nearest region (lower latency).
Each gateway keeps its local sockets and writes its routing info to the shared store (Redis).
When a message comes in, the gateway persists it and publishes once to the event bus (Kafka), keyed by channelId so it lands in the right partition.
A fan-out step reads that partition, looks up the routing table to see which gateways hold subscribers, and hands the message to those gateways.
Each of those gateways does the final push to its own local sockets.
Autoscaling watches connection count and outbound events/sec (plus CPU, memory, and how far behind the consumers are — "lag") and adds/removes gateways automatically.

Mental model to remember the whole journey:

Load balancer picks your desk. Redis remembers who sits where. Kafka carries messages between desks. Partitions keep each channel's mail in its own ordered lane. Fan-out copies the one message to everyone who wants it.

Hot Channels and Hot Connections

Even with all of the above, two things can still overwhelm you:

A hot connection — a single client sending or receiving way too much (a runaway bot, an abusive script, one power user).
A hot channel — one room with enormous fan-out (a company-wide all-hands channel where one message reaches everyone at once).

Protections:

Per-connection limits — rate-limit how fast one user can publish/subscribe (a "token bucket" gives each user a refilling allowance of actions).
Per-channel protection — cap burst fan-out per time window; coalesce high-frequency events (collapse many typing/presence updates into one).
Shard heavy channels — move a giant channel onto its own dedicated servers, so its storm cannot hurt normal channels.
Priority lanes — deliver critical events (real messages) first; delay or drop noisy ones (typing indicators) under stress.
Slow-consumer strategy — if one client cannot keep up, bound its buffer; when it overflows, drop low-priority events or force a replay resync instead of letting memory grow forever.

Migration Checklist

The practical order to actually evolve the system (do not build Stage C on day one):

Start with a single gateway and measure a baseline.
Add a second gateway plus a load balancer.
Introduce a shared presence/subscription store (Redis).
Add an event bus for inter-node fan-out (Kafka).
Partition channels by a stable key (channelId).
Add autoscaling rules from real traffic.
Add hot-channel isolation and rate limits.
Run chaos/failover tests (kill a node, drop a region, trigger a reconnect storm) and confirm recovery.

One-line summary of the whole journey:

1 node: easy and cheap.
10 nodes: shared state (Redis) + sticky routing.
100+ nodes: partitioning + event bus + regional strategy.

14.4 How Traffic Is Handled Safely

A real-time system does not usually die from average traffic — it dies from spikes: a viral moment, a reconnect storm after an outage, or one channel suddenly getting 100x its normal load. This section is about the safety valves that keep the system standing when traffic surges. Think of them as circuit breakers and pressure valves in plumbing: they trade a little quality (drop a typing indicator) to avoid a catastrophic burst (the whole pipe explodes).

There are five main techniques. We will explain each from scratch, then show how they work together.

Backpressure Explained

The problem: what happens when data arrives faster than it can be processed? Without a plan, queues grow forever until memory runs out and the process crashes.

Backpressure is the general idea of pushing back when a downstream part cannot keep up — slowing the producer, buffering with a limit, or dropping low-value data — instead of blindly accepting everything.

Analogy: backpressure is like a narrow funnel. If you pour water in faster than it drains, the funnel overflows. Backpressure is either pouring slower, using a bigger-but-still-limited funnel, or letting some water spill on purpose so the important flow continues.

Where it applies in our system:

On the client (rendering): the UI cannot repaint 500 times a second. So instead of re-rendering on every event, the client batches events and repaints once per animation frame (~60 times a second), and coalesces rapid updates (10 presence blinks for the same user collapse into one).
On the server (delivery): if a gateway is producing messages faster than a slow client's socket can drain, the server must not buffer infinitely — it bounds the buffer (see slow-consumer handling below).

Why it matters: backpressure is the difference between a system that degrades gracefully under load and one that falls over. The golden rule: bounded queues everywhere. No queue — client-side or server-side — is ever allowed to grow without a limit.

Rate Limiting Explained

The problem: one misbehaving client (a bug, a bot, an attacker) can flood the server with thousands of messages per second and starve everyone else.

Rate limiting caps how many actions a client is allowed in a time window. The most common mechanism is the token bucket:

Each user gets a bucket that holds, say, 20 tokens.
Every action (publish/subscribe) costs 1 token.
The bucket refills at, say, 10 tokens per second.

- Bucket has tokens?  -> allow the action, remove 1 token.
- Bucket empty?       -> reject or delay the action.

Analogy: a token bucket is like an arcade with a coin allowance. You get a handful of coins that slowly refill. You can spend a burst of coins fast (a quick flurry of messages), but once they run out you must wait for more. This allows normal bursts while blocking sustained abuse.

Apply limits at two levels:

Per-user — stops a single account from flooding.
Per-tenant / per-workspace — stops one organization's traffic from starving other tenants on shared infrastructure ("noisy neighbor" protection).

When a client is limited, respond with a clear signal (an error frame or a retry-after hint) so a well-behaved client backs off instead of hammering harder.

Fan Out Control Explained

The problem: recall from 14.3 that fan-out multiplies one message into many deliveries. A popular channel (say a 50,000-member announcements channel) can turn a single post into a burst of 50,000 deliveries all at once — a spike that can overwhelm gateways and the network.

Fan-out control smooths and spreads that burst so it does not hit all at once:

Queues + workers — instead of delivering to 50,000 sockets synchronously in one loop, push the delivery work into a queue and let a pool of workers drain it steadily. The burst becomes a fast-but-controlled stream rather than one giant spike.
Partitioning — (from 14.3) spread the channel's delivery work across many partitions/servers so no single server carries the whole 50,000-way fan-out.
Coalescing / batching — if several updates happen within a few milliseconds, combine them into one frame per subscriber instead of many.
Sharding a hot channel — for truly enormous channels, split the member list across multiple dedicated delivery groups so the fan-out is parallelized.

Analogy: fan-out control is like a stadium emptying through many exits with staggered timing instead of everyone stampeding one door at the same second.

Slow Consumer Handling Explained

The problem: not all clients drain data at the same speed. A user on weak mobile signal, a backgrounded tab, or an overloaded laptop reads its socket slowly. The server keeps producing events for them, and the unsent data piles up in a server-side buffer for that one connection. If unbounded, that buffer eats memory and can take the whole server down — one slow user hurting everyone.

Slow-consumer handling protects the server from its slowest clients:

Bound the per-socket buffer — each connection gets a maximum outbound buffer (e.g. 1 MB). It is never allowed to grow past that.
When the buffer fills, shed load intelligently:
- Drop low-value, transient events first (typing indicators, presence blinks) — nobody misses a stale "typing…".
- Keep critical, durable events (real messages, moderation actions).
If it still overflows, stop streaming and force a resync — disconnect or mark the client "behind," and let it recover via replay (next section) once it reconnects, rather than trying to push a huge backlog through a straw.

Analogy: slow-consumer handling is like a conveyor belt with a full bin at the end. Rather than letting boxes pile up and jam the whole line, you either divert the low-priority boxes or stop the belt and restart cleanly later.

Key principle: one slow client must never be able to degrade the experience of fast clients. Isolation is the goal.

Replay and Recovery Explained

The problem: disconnects are normal (Wi-Fi drops, tab sleeps, deploys). When a client comes back, it may have missed events. We must fill that gap without re-sending everything (wasteful) and without leaving holes (broken UI).

Replay and recovery solve this using the sequence numbers we attach to every event per channel:

Each event in a channel carries an increasing sequence (1, 2, 3, ...).
The client remembers the last sequence it successfully processed (its cursor).
On reconnect, the client asks: "give me everything after fromSeq" — only the missed slice, nothing more.
The server returns just those events; the client applies them and is caught up.

Client last saw sequence 1240, then disconnected.
While offline, the channel advanced to 1245.

Reconnect -> GET /replay?fromSeq=1240
Server    -> events 1241, 1242, 1243, 1244, 1245
Client    -> applies them, cursor now 1245, fully caught up.

Two safety nets make this robust:

Gap detection — if a live event arrives with a sequence that skips ahead (e.g. you have 1240 and suddenly get 1243), the client knows it missed 1241–1242 and triggers a replay to fill the hole.
Idempotent apply (dedupe by eventId) — replay may overlap with events the client already saw; deduping by eventId means applying the same event twice is harmless. The user still sees each message exactly once.

Analogy: replay is like catching up on a group chat after your phone was off — you do not re-read the whole history, you just scroll from the last message you saw. The sequence number is your "last read" bookmark.

How They Work Together

These five are layers of the same defense, from the moment traffic enters to the moment a client recovers:

incoming action
   |
   v
[Rate limiting]      -> block abusive senders at the door
   |
   v
[Fan-out control]    -> spread one message's delivery over queues/workers/partitions
   |
   v
[Backpressure]       -> bounded queues everywhere; batch + coalesce
   |
   v
[Slow-consumer]      -> protect the server from clients that read slowly
   |
   v
[Replay + recovery]  -> whatever got dropped is recovered cleanly on reconnect

The unifying philosophy: under stress, degrade gracefully. Drop the cheap stuff (typing, presence), protect the valuable stuff (messages), never let any queue grow unbounded, and rely on replay to make any drops invisible to the user.

14.5 Capacity Metrics to Track

Concurrent socket connections
Messages in/out per second
P95/P99 delivery latency
Reconnect rate
Replay request rate
Dropped/failed message count

Simple stress signal: if reconnect rate and replay rate spike together, your system is under stress.

14.6 Deep Theory Kafka Routing Table and Consumers

This answers the exact question interviewers love: the sender is connected to Server A, but the receiver is connected to Server B — how does the message get across?

A) The cross-node flow, step by step:

Sender is connected to Gateway Node A.
Receiver is connected to Gateway Node B.
Sender sends a frame to Node A.
Node A validates auth + publish permission.
Node A persists the message and publishes one event to Kafka (key usually = channelId).
A fan-out/routing component reads that event and checks the routing table.
The routing table returns the target gateway nodes for this channel (Node B, maybe Node A too).
Delivery tasks go to those target nodes.
Node B pushes the frame to the receiver's socket.
The receiver's UI renders it.

So the event bus (Kafka) is the bridge across nodes.

B) Why Kafka? Kafka is for backend event distribution and durability, not for talking to sockets directly. It gives you:

A durable log (survives restarts).
Decoupling (Node A publishes fast; delivery happens asynchronously).
A buffer for backpressure (consumers can lag and catch up).
Partitioned scale (parallel processing).
Replay by offsets.

Kafka does not know about live sockets — the socket-to-node mapping comes from the routing table, not Kafka.

C) The routing table — the "phone book" of who is connected where:

channelId -> set(gatewayNodeIds)
gatewayNodeId -> set(connectionIds)
connectionId -> userId / session / subscriptions

Who updates it: each gateway updates its local memory on connect/subscribe/unsubscribe/disconnect, and writes to a shared store (Redis) for cross-node visibility.
Who reads it: the fan-out router when it consumes a new event (in small systems, Node A may read it directly).

D) Consumer configuration patterns:

Pattern 1 — every gateway consumes everything (simple, wasteful): each node reads all events and throws away those with no local subscribers. Easy to start, poor at scale.
Pattern 2 — targeted fan-out (recommended): publish once, a fan-out service resolves target nodes via the routing table, then writes to per-node delivery streams so each gateway consumes only its own stream.

Sender on Node A
    |
    | 1) ws frame: message.send
    v
+-----------+      2) publish(channelId key)      +----------------+
| Gateway A | -----------------------------------> | Kafka Topic(s) |
+-----------+                                      +----------------+
                                                      |
                                                      | 3) consume
                                                      v
                                               +---------------+
                                               | Fanout Router |
                                               +---------------+
                                                      |
                                   4) read routing table: channel -> nodes
                                                      |
                       +------------------------------+-----------------------------+
                       |                                                            |
                       v                                                            v
              +-------------------+                                        +-------------------+
              | Node B delivery Q |                                        | Node A delivery Q |
              +-------------------+                                        +-------------------+
                       |                                                            |
                       | 5) consume only own queue                                 | (optional)
                       v                                                            v
                  +-----------+                                                +-----------+
                  | Gateway B |                                                | Gateway A |
                  +-----------+                                                +-----------+
                       |                                                            |
                       | 6) push to local sockets                                  | local subscriber(s)
                       v                                                            v
                   Receiver(s)                                                  Local receiver(s)

E) Can Node A also be a target? Yes — if Node A also has local subscribers for that channel, it is a valid target too. The distinction that matters: "Node A can be a target" is fine; "every node consumes every event" is what gets expensive.

F) Where does the load balancer fit? It handles connection admission (TLS + routing the handshake to a gateway) and reconnect placement (sticky/cookie/hash). It does not do cross-node message fan-out — that is Kafka + fan-out service + routing table.

G) Failure and correctness notes:

If Node B dies, the routing table must evict its stale entries (via TTL/heartbeat).
If a consumer lags, Kafka offsets let it catch up.
If the receiver is offline, the message stays durable and is delivered later via replay.
Ordering is guaranteed per partition key, so your keying strategy matters.

14.7 Ordering Policy

Be explicit about what order is guaranteed:

Per-channel ordering: guaranteed when all of a channel's events share one partition key.
Cross-channel ordering: not guaranteed.
Cross-region ordering: eventual — may be delayed or reordered.
Client rendering rule: sort by sequence within a channel.
Gap rule: if nextSequence != lastSequence + 1, trigger a replay.

Tie-break order when two events look equal: primary sequence, then server timestamp, then lexical eventId.

14.8 Observability SLOs and Alerts

An SLO is a target you promise to hit. Suggested SLOs:

Real-time delivery latency P99 < 2s
Socket connect success rate > 99.9%
Reconnect recovery under 30s for 99% of sessions
Replay success rate > 99.5%

Suggested alerts:

Reconnect spike — reconnect rate > 3× baseline for 5 min.
Replay spike — replay requests > 2× baseline for 10 min.
Consumer lag — lag exceeds threshold for 5 min.
Error burst — auth/subscribe errors exceed the normal percentile.

Minimal runbook when something fires:

Check regional gateway health.
Check broker lag and partition hot spots.
Check auth/token service latency.
If needed, turn on protective throttling and coalescing.

14.9 Testing Strategy and Validation Gates

Test before you ship:

Functional — connect, subscribe, publish, ack, replay, dedupe.
Resilience — node restart, broker restart, network partition, reconnect storm.
Scale — many concurrent sockets, fan-out stress, hot-channel stress.
Security — expired token, revoked token, unauthorized subscribe/publish.

Pass criteria examples:

No message loss in replay scenarios.
Duplicate rate within threshold and hidden by UI dedupe.
P99 latency under SLO at target load.
Recovery after a single-node failure meets the reconnect SLO.

⬆ Back to Top

15. Final Summary

If you can explain the design in these four lines, you understand it well enough for most interviews:

Open one live socket after login.
Subscribe only to the channels you need.
Update the UI instantly with the optimistic + ack flow.
Reconnect and replay missed events after a disconnect.

And the one deeper insight that separates a beginner from a strong answer:

The hard part of real-time is not opening a socket — it is fan-out at scale (delivering one message to many users across many servers) and recovering correctly after failures (dedupe by eventId, order by sequence, replay from a cursor).

More Details:

Get all articles related to system design
Hashtag: SystemDesignWithZeeshanAli

systemdesignwithzeeshanali

Git: https://github.com/ZeeshanAli-0704/front-end-system-design

Dynamic Programming Notes — Interview Cheat Sheet

ZeeshanAli-0704 — Mon, 04 May 2026 01:56:30 +0000

Dynamic Programming Notes — Interview Cheat Sheet

One-stop reference for DP: when to use, how to think, all major patterns
(linear, grid, knapsack, subsequence, interval, partition, tree, bitmask,
digit, state-machine, game-theory), templates, complexity, and decision tree.

0) Five Questions to Ask First

Your answers pick the pattern.

Optimal substructure? Can the answer be built from answers to smaller subproblems?
Overlapping subproblems? Does naive recursion recompute the same thing?
What is the state? What variables uniquely identify a subproblem?
What are the choices at each state? (take/skip, pick coin, partition, etc.)
What is the base case + final answer location?

If "yes" to 1 & 2 → DP. Otherwise consider greedy / divide & conquer / backtracking.

1) DP vs Other Paradigms

Pattern	Use when
Greedy	Locally optimal choice always leads to global optimum (Activity Selection, Huffman)
Divide & Conquer	Subproblems are independent (Merge Sort, Quick Sort)
Backtracking	Need all solutions / constraint satisfaction (N-Queens, Sudoku)
DP	Overlapping subproblems + optimal substructure (count/min/max/yes-no)
DP + Bitmask	Small N (≤ ~20) with subset state
DP on graph / tree	Dependency between subproblems given by graph/tree edges

2) Three Forms of DP

A) Recursion (brute force)

Direct translation of recurrence. Exponential time. Useful to derive the recurrence.

B) Top-Down (Memoization)

Recursion + cache. Computes only needed states.
Pros: matches recursion intuition, easy on tree/graph DPs.
Cons: recursion stack overhead.

C) Bottom-Up (Tabulation)

Iterative; fill table in dependency order.
Pros: no recursion, easier to space-optimize.
Cons: must know iteration order; sometimes unnatural.

	Top-Down	Bottom-Up
Style	Recursive + memo	Iterative table
Stack risk	Yes (deep recursion)	No
Easy to space-optimize	❌	✅
Best for graph/tree DP	✅	Often awkward
Best for linear/grid	OK	✅

Rule of thumb: start top-down to derive recurrence → convert to bottom-up → space-optimize.

3) Universal DP Recipe

Define state: dp[i], dp[i][j], dp[i][cap], dp[mask][i] …
Define meaning: e.g., "min cost to reach i", "ways to make sum j using first i items".
Write recurrence from the choices at state.
Base cases.
Iteration order (bottom-up): each state depends only on already-filled states.
Final answer: which cell holds it?
Space optimize if only previous row/col needed.

4) Master Decision Guide (Pattern Picker)

Problem flavor	Pattern
Steps with 1 / 2 / k jump options	Linear 1D (Fibonacci-style)
Pick non-adjacent for max sum	House Robber
Min/max path in grid	Grid 2D
"Pick items, capacity W, max value"	0/1 Knapsack
"Unlimited supply, min coins / ways"	Unbounded Knapsack
"Subset sum / partition equally"	Subset-sum knapsack
LCS / LIS / Edit Distance	Subsequence / String DP
Palindromic substring / subseq	Interval DP / Expand-around
Burst balloons / Matrix Chain Mult	Interval DP (`dp[i][j]` over range)
Palindrome / word break partitions	Partition DP
Tree path / rob house tree	Tree DP (postorder return tuple)
Shortest/longest path in DAG	DP on DAG (topo + relax)
TSP / assign N tasks to N people	Bitmask DP (N ≤ 20)
Count numbers ≤ N with property	Digit DP
Two-player optimal (Nim-style)	Game Theory DP (minimax)
Stock buy/sell variants	State-Machine DP
Count ways (paths, decodings, dice)	Counting DP
Probability over states	Probability DP

5) Pattern 1 — Linear 1D (Fibonacci Family)

State: dp[i] = answer ending at / using first i items.

// Climb Stairs (LC 70)
function climb(n) {
  let a = 1, b = 1;
  for (let i = 2; i <= n; i++) [a, b] = [b, a + b];
  return b;
}
// Time O(n), Space O(1)

Examples: Climbing Stairs, Min Cost Climbing Stairs, House Robber I/II, Decode Ways, Tribonacci, Delete & Earn.

Problem	Recurrence
Climb Stairs	`dp[i] = dp[i-1] + dp[i-2]`
Min Cost Climbing	`dp[i] = min(dp[i-1]+c[i-1], dp[i-2]+c[i-2])`
House Robber	`dp[i] = max(dp[i-1], dp[i-2] + nums[i])`
Decode Ways	`dp[i] = dp[i-1] + (valid two-digit ? dp[i-2] : 0)`

6) Pattern 2 — Grid 2D Paths

State: dp[i][j] = best value reaching cell (i,j).

// Min Path Sum (LC 64)
function minPathSum(g) {
  const m = g.length, n = g[0].length;
  const dp = g.map(r => r.slice());
  for (let i = 0; i < m; i++)
    for (let j = 0; j < n; j++) {
      if (i === 0 && j === 0) continue;
      const up   = i ? dp[i-1][j] : Infinity;
      const left = j ? dp[i][j-1] : Infinity;
      dp[i][j] += Math.min(up, left);
    }
  return dp[m-1][n-1];
}
// Time O(m*n), Space O(m*n) → can drop to O(n)

Examples: Unique Paths I/II, Min Path Sum, Triangle, Maximal Square, Min Falling Path Sum, Cherry Pickup (3D).

7) Pattern 3 — 0/1 Knapsack

Each item taken at most once.

State: dp[i][w] = best value using first i items, capacity w.

function knapsack01(wt, val, W) {
  const n = wt.length;
  const dp = Array.from({length: n+1}, () => new Array(W+1).fill(0));
  for (let i = 1; i <= n; i++)
    for (let w = 0; w <= W; w++) {
      dp[i][w] = dp[i-1][w];                              // skip
      if (w >= wt[i-1])
        dp[i][w] = Math.max(dp[i][w], dp[i-1][w-wt[i-1]] + val[i-1]);
    }
  return dp[n][W];
}
// Time O(n*W), Space O(n*W) → 1D rolling: iterate w from W down to wt[i-1]

Variants:
| Variant | Trick |
|---|---|
| Subset Sum | dp[i][s] boolean |
| Partition Equal Subset Sum | Subset sum to total/2 |
| Target Sum | Reduce to subset sum |
| Last Stone Weight II | Subset sum closest to total/2 |
| Count Subsets w/ Sum K | dp[i][s] = dp[i-1][s] + dp[i-1][s-a[i]] |
| Ones and Zeroes | 2-cap knapsack (dp[i][zeros][ones]) |

8) Pattern 4 — Unbounded Knapsack

Each item taken unlimited times.

State: dp[i][w] similar; transition uses dp[i][w-wt[i-1]] (same row).

// Coin Change — fewest coins (LC 322)
function coinChange(coins, amt) {
  const dp = new Array(amt+1).fill(Infinity);
  dp[0] = 0;
  for (let a = 1; a <= amt; a++)
    for (const c of coins)
      if (a >= c) dp[a] = Math.min(dp[a], dp[a-c] + 1);
  return dp[amt] === Infinity ? -1 : dp[amt];
}
// Time O(amt * coins), Space O(amt)

Examples: Coin Change, Coin Change II (count ways), Rod Cutting, Combination Sum IV, Perfect Squares.

Order matters!

Outer amount, inner coins → counts permutations (Combination Sum IV).

Outer coins, inner amount → counts unique combinations (Coin Change II).

9) Pattern 5 — Subsequence / String DP

State: dp[i][j] over indices of two strings (or one).

// Longest Common Subsequence (LC 1143)
function lcs(a, b) {
  const m = a.length, n = b.length;
  const dp = Array.from({length: m+1}, () => new Array(n+1).fill(0));
  for (let i = 1; i <= m; i++)
    for (let j = 1; j <= n; j++)
      dp[i][j] = a[i-1] === b[j-1]
        ? dp[i-1][j-1] + 1
        : Math.max(dp[i-1][j], dp[i][j-1]);
  return dp[m][n];
}
// Time O(m*n), Space O(m*n) → O(min(m,n)) rolling

Problem	Recurrence (match vs mismatch)
LCS	match: `1 + dp[i-1][j-1]`, else `max(dp[i-1][j], dp[i][j-1])`
Edit Distance	`1 + min(insert, delete, replace)`
Distinct Subsequences	`dp[i-1][j-1] + dp[i-1][j]` if match, else `dp[i-1][j]`
Shortest Common Supersequence	`m + n - LCS`
Min Insertions for Palindrome	`n - LPS(s)` where `LPS = LCS(s, reverse(s))`
Wildcard / Regex matching	match `*` as 0 or many

LIS (1D state, O(n log n) with binary search)

function lengthOfLIS(nums) {
  const tails = [];
  for (const x of nums) {
    let lo = 0, hi = tails.length;
    while (lo < hi) {
      const m = (lo + hi) >> 1;
      if (tails[m] < x) lo = m + 1; else hi = m;
    }
    tails[lo] = x;
  }
  return tails.length;
}
// Time O(n log n)

10) Pattern 6 — Palindromic DP

Problem	Approach
Longest Palindrome Substring	Expand around center O(n²), or DP `dp[i][j]`
Longest Palindrome Subseq	LCS(s, reverse(s))
Palindromic Substrings count	Expand around center / DP boolean
Palindrome Partitioning II (min cuts)	DP + palindrome table

// dp[i][j] = is s[i..j] palindrome?
for (let len = 1; len <= n; len++)
  for (let i = 0; i + len - 1 < n; i++) {
    const j = i + len - 1;
    if (s[i] !== s[j]) dp[i][j] = false;
    else dp[i][j] = len <= 2 ? true : dp[i+1][j-1];
  }

11) Pattern 7 — Interval DP

State: dp[i][j] = answer over interval [i..j]. Iterate by length.

// Matrix Chain Multiplication template
for (let len = 2; len <= n; len++)
  for (let i = 0; i + len - 1 < n; i++) {
    const j = i + len - 1;
    dp[i][j] = Infinity;
    for (let k = i; k < j; k++)
      dp[i][j] = Math.min(dp[i][j], dp[i][k] + dp[k+1][j] + cost(i,k,j));
  }

Examples: Matrix Chain Mult, Burst Balloons, Min Cost Tree from Leaf Values, Stone Game (interval), Strange Printer, Remove Boxes.

Time often O(n³). Space O(n²).
Always iterate shorter intervals first.

12) Pattern 8 — Partition DP

Split the array/string into pieces minimizing/counting something.

// Word Break (LC 139)
function wordBreak(s, dict) {
  const set = new Set(dict);
  const dp = new Array(s.length + 1).fill(false);
  dp[0] = true;
  for (let i = 1; i <= s.length; i++)
    for (let j = 0; j < i; j++)
      if (dp[j] && set.has(s.slice(j, i))) { dp[i] = true; break; }
  return dp[s.length];
}

Examples: Word Break I/II, Palindrome Partitioning II, Perfect Squares, Decode Ways.

13) Pattern 9 — Stock / State-Machine DP

State = (day, holding?, transactions_left, cooldown?).

// Best Time to Buy and Sell Stock (unlimited) — LC 122
function maxProfit(prices) {
  let hold = -Infinity, cash = 0;
  for (const p of prices) {
    const newHold = Math.max(hold, cash - p);
    cash = Math.max(cash, hold + p);
    hold = newHold;
  }
  return cash;
}

Variant	Extra state
At most 1 transaction	`dp[i][0/1]`, no `k`
Unlimited	same as above
At most `k` transactions	`dp[i][k][0/1]`
Cooldown	extra `cooldown` state
With fee	subtract fee on sell

14) Pattern 10 — Tree DP

DFS postorder; each node returns a tuple of states for its parent.

// House Robber III (LC 337)
function rob(root) {
  const dfs = (node) => {
    if (!node) return [0, 0];                 // [rob, notRob]
    const [lr, ln] = dfs(node.left);
    const [rr, rn] = dfs(node.right);
    return [node.val + ln + rn, Math.max(lr, ln) + Math.max(rr, rn)];
  };
  return Math.max(...dfs(root));
}
// Time O(n), Space O(h)

Examples: Diameter of Binary Tree, House Robber III, Binary Tree Max Path Sum, LIS in Tree, Tree Coloring.

15) Pattern 11 — DP on Graph / DAG

DAG → topological order → relax edges (shortest/longest path).
General graph + DP usually needs Bellman-Ford or BFS layering.

// Cheapest Flights Within K Stops (LC 787) — Bellman-Ford style
function findCheapestPrice(n, flights, src, dst, K) {
  let dist = new Array(n).fill(Infinity); dist[src] = 0;
  for (let i = 0; i <= K; i++) {
    const next = dist.slice();
    for (const [u, v, w] of flights)
      if (dist[u] + w < next[v]) next[v] = dist[u] + w;
    dist = next;
  }
  return dist[dst] === Infinity ? -1 : dist[dst];
}
// Time O(K * E)

16) Pattern 12 — Bitmask DP

Use when N ≤ ~20 and state needs subset of items.

State: dp[mask] or dp[mask][i] = best with subset mask, ending at i.

// Traveling Salesman (Held-Karp) sketch
const dp = Array.from({length: 1 << n}, () => new Array(n).fill(Infinity));
dp[1][0] = 0;
for (let mask = 1; mask < (1 << n); mask++)
  for (let u = 0; u < n; u++) {
    if (!(mask & (1 << u))) continue;
    for (let v = 0; v < n; v++) {
      if (mask & (1 << v)) continue;
      const next = mask | (1 << v);
      dp[next][v] = Math.min(dp[next][v], dp[mask][u] + cost[u][v]);
    }
  }
// Time O(2^n * n^2)

Examples: TSP, Assign Tasks to Workers, Partition to K Equal Subsets, Shortest Superstring, Min Cost to Connect Sticks.

17) Pattern 13 — Digit DP

Count numbers from 1 to N with some digit property.

State: dp[pos][tight][...properties].

function digitDP(N) {
  const s = String(N), n = s.length;
  const memo = new Map();
  function f(i, tight, ...props) {
    if (i === n) return /* base case */ 1;
    const key = `${i},${tight},${props.join(',')}`;
    if (memo.has(key)) return memo.get(key);
    const limit = tight ? +s[i] : 9;
    let res = 0;
    for (let d = 0; d <= limit; d++) {
      res += f(i + 1, tight && d === limit, /* update props */);
    }
    memo.set(key, res);
    return res;
  }
  return f(0, true);
}

Examples: Count numbers with no consecutive same digits, Numbers with K=1 digit, Sum of digit sums.

18) Pattern 14 — Game Theory DP

Two players, optimal play, minimax.

// Stone Game — pick from ends, max diff for current player
function stoneGameDP(piles) {
  const n = piles.length;
  const dp = Array.from({length: n}, () => new Array(n).fill(0));
  for (let i = 0; i < n; i++) dp[i][i] = piles[i];
  for (let len = 2; len <= n; len++)
    for (let i = 0; i + len - 1 < n; i++) {
      const j = i + len - 1;
      dp[i][j] = Math.max(piles[i] - dp[i+1][j], piles[j] - dp[i][j-1]);
    }
  return dp[0][n-1] > 0;
}

Examples: Stone Game, Predict the Winner, Nim Game, Can I Win, Soup Servings.

19) Pattern 15 — Counting DP

Problem	Recurrence
Unique Paths	`dp[i][j] = dp[i-1][j] + dp[i][j-1]`
Unique BST (Catalan)	`dp[n] = Σ dp[i] * dp[n-1-i]`
Number of Dice Rolls = Target	`dp[i][s] = Σ dp[i-1][s-f]` for f=1..k
Domino & Tromino Tilings	linear recurrence
Number of LIS	track count + length

20) Pattern 16 — Probability DP

dp[state] = probability of being in state.

// Knight Probability in Chessboard (LC 688)
function knightProbability(N, K, r, c) {
  const moves = [[-2,-1],[-2,1],[-1,-2],[-1,2],[1,-2],[1,2],[2,-1],[2,1]];
  let dp = Array.from({length: N}, () => new Array(N).fill(0));
  dp[r][c] = 1;
  for (let k = 0; k < K; k++) {
    const nx = Array.from({length: N}, () => new Array(N).fill(0));
    for (let i = 0; i < N; i++)
      for (let j = 0; j < N; j++)
        if (dp[i][j])
          for (const [di, dj] of moves) {
            const ni = i + di, nj = j + dj;
            if (ni >= 0 && ni < N && nj >= 0 && nj < N) nx[ni][nj] += dp[i][j] / 8;
          }
    dp = nx;
  }
  return dp.flat().reduce((a, b) => a + b, 0);
}

21) Space-Optimization Tricks

Pattern	Trick
`dp[i]` depends only on `dp[i-1], dp[i-2]`	Two scalars
`dp[i][j]` depends only on previous row	Roll to 1D
0/1 Knapsack 1D	iterate `w` descending
Unbounded Knapsack 1D	iterate `w` ascending
LCS 1D	keep prev row + diagonal temp
Interval DP	usually can't reduce dimensions

22) Master Complexity Table

Pattern	Time	Space (after opt)
Linear 1D (Fib family)	O(n)	O(1)
Grid 2D paths	O(m·n)	O(n)
0/1 Knapsack	O(n·W)	O(W)
Unbounded Knapsack	O(n·W)	O(W)
LCS / Edit Distance	O(m·n)	O(min(m,n))
LIS	O(n log n)	O(n)
Palindrome DP	O(n²)	O(n²)
Interval DP (MCM, Burst)	O(n³)	O(n²)
Partition DP (Word Break)	O(n²)	O(n)
Tree DP	O(n)	O(h)
DAG DP / Bellman-Ford	O(V+E) / O(V·E)	O(V)
Bitmask DP	O(2ⁿ · n) or O(2ⁿ · n²)	O(2ⁿ · n)
Digit DP	O(D · states)	O(D · states)
Game DP (range)	O(n²) – O(n³)	O(n²)
Probability DP (grid+steps)	O(K · m · n)	O(m · n)

23) Common Mistakes Checklist

Wrong state definition → if you can't write a clean recurrence, redefine state.
Wrong iteration order in tabulation (depends on already-computed cells).
0/1 vs Unbounded knapsack loop direction mixed up — descending vs ascending w.
Coin Change "ways" loops swapped → permutations vs combinations.
Forgetting base cases (especially dp[0] = 1 for "ways" problems).
Off-by-one in 1-indexed vs 0-indexed dp arrays.
Using memoization with mutable args (always pass primitives or stringify).
Tree DP returning wrong tuple shape — always document what each return slot means.
Bitmask iterating subsets wrong — for sub-subsets use for (sub = mask; sub; sub = (sub-1) & mask).
Game DP from wrong perspective — always model "current player's max diff".
Recursion stack overflow on deep DPs — convert to iterative.
Integer overflow in counting DPs (use BigInt or % MOD).
Floyd-style "all-pairs" reused for single source — wasteful, prefer Dijkstra/BF.

24) Recurrence Quick-Look

Goal	Template
Min cost to reach target	`dp[i] = min over choices c of dp[i-c] + cost(c)`
Count ways to reach target	`dp[i] = Σ dp[i-c]`
Yes/No reach target	`dp[i] = OR dp[i-c]`
0/1 pick item or not	`dp[i][w] = max(dp[i-1][w], dp[i-1][w-wt]+val)`
Unbounded pick	`dp[i][w] = max(dp[i-1][w], dp[i][w-wt]+val)`
Match strings (LCS-like)	match: `1 + dp[i-1][j-1]`, else `max(dp[i-1][j], dp[i][j-1])`
Interval split	`dp[i][j] = min over k of dp[i][k] + dp[k+1][j] + merge(i,k,j)`
Minimax game	`dp[i][j] = max over move of (gain - dp[opponent])`
Tree DP	`dfs(node)` returns tuple combining child tuples

25) One-Line Super Formula

Min/max cost to target → dp[i] = min(dp[i-c] + cost) for all choices c.
Count ways → sum over choices; watch loop order for combinations vs permutations.
Pick subset (cap) → 0/1 vs unbounded knapsack (loop direction matters).
Two-string compare → 2D dp[i][j] (LCS template).
Range merge → Interval DP, iterate by length, O(n³).
Subset state, small N → Bitmask DP.
Tree → postorder DFS returning tuple.
Optimal play → minimax: dp = max(value - dp[opponent]).
Probability → dp[state] summing weighted transitions.

26) Code Index (this repo)

Topic	File
Linear 1D	`Dynamic_Programming/minCostClimbingStairs.js`, `rob1.js`
Counting (Stairs/BST/Tilings)	`Dynamic_Programming/counting/climbStairs.js`, `numTrees.js`, `numTilings.js`, `numRollsToTarget.js`, `combinationSum4.js`
Grid paths	`Dynamic_Programming/grid-paths/minPathSum.js`, `minFallingPathSum.js`, `Triangle.js`, `maximalSquare.js`
0/1 Knapsack	`Dynamic_Programming/knapsack/canPartition.js`, `lastStoneWeightII.js`, `findTargetSumWays.JS`, `countSubsets.js`, `countPartionSubsetWithK.js`, `ones-and-zeroes.js`
Unbounded Knapsack	`Dynamic_Programming/knapsack/coinChange.js`, `rodLength.js`
Subsequence / String DP	`Dynamic_Programming/subsequence/longestCommonSubsequence.js`, `longestPalindromeSubseq.js`, `longestPalindromeSubString.js`, `countPalindromeSubstrings.js`, `findNumberOfLIS.js`, `minInsertions.js`, `shortestCommonSupersequence.js`
Stock / state-machine	`Dynamic_Programming/stock-problems/StockBuySell2.js`, `StockBuySell3.js`
Game theory / probability	`Dynamic_Programming/game-theory/getMoneyAmount.js`, `knightProbability.js`, `soupServings.js`
Interval DP	`Dynamic_Programming/mctFromLeafValues.js`
Misc	`Dynamic_Programming/mincostTickets.js`, `mostPoints.js`, `ninjaTraining.js`, `knightDialer.js`, `getMinOperations.js`, `deleteNearn.js`
Existing pattern doc	`Dynamic_Programming/DP_Patterns.md`, `Notes.md`

DSA Complexity : Master Cheat Sheet

ZeeshanAli-0704 — Sun, 03 May 2026 11:37:39 +0000

Time & Space Complexity Cheat Sheet

Arrays

Operation	Time	Space
Access by index	O(1)	O(1)
Search (unsorted)	O(n)	O(1)
Insert at end	O(1)	O(1)
Insert at start/middle	O(n)	O(1)
Delete at end	O(1)	O(1)
Delete at start/middle	O(n)	O(1)
Copy array	O(n)	O(n)
Reverse in-place	O(n)	O(1)
Nested loops	O(n²)	O(1)
Hash set lookup	O(1) avg	O(n)

Strings

Operation	Time	Space
`.length`	O(1)	O(1)
Concatenation `a + b`	O(n+m)	O(n+m)
Reverse with `+=` in loop	O(n²)	O(n)
Reverse with split/join	O(n)	O(n)
Anagram check (freq map)	O(n)	O(1)
Palindrome (two pointers)	O(n)	O(1)
All substrings	O(n³)	O(n³)

Note: Frequency map of characters is O(1) space — alphabet size is fixed (26 letters max).

Linked Lists

Operation	Time	Space
Access by index	O(n)	O(1)
Search	O(n)	O(1)
Insert at head	O(1)	O(1)
Insert at tail (no tail ptr)	O(n)	O(1)
Insert at tail (with tail ptr)	O(1)	O(1)
Delete at head	O(1)	O(1)
Delete at tail	O(n)	O(1)
Reverse	O(n)	O(1)
Detect cycle	O(n)	O(1)
Find middle	O(n)	O(1)
Merge two sorted lists	O(n+m)	O(1)

Recursion

Time  = depth × work per level
Space = depth (call stack frames only)

Branches affect TIME not space.
Space = depth regardless of branches.

Pattern	Time	Space
Linear — subtract 1 each call	O(n)	O(n)
Halving — divide by 2 each call	O(log n)	O(log n)
2 branches, depth n	O(2ⁿ)	O(n)
3 branches, depth n	O(3ⁿ)	O(n)
2 branches, halving input	O(n)	O(log n)
Merge sort (2 branches, halving, O(n) work/level)	O(n log n)	O(n)
Fast power (halving exponent)	O(log n)	O(log n)

Key Rule: Subtracting 1 → O(n) depth. Dividing by k → O(log n) depth.

Sorting Algorithms

Algorithm	Best	Average	Worst	Space
Bubble Sort	O(n)	O(n²)	O(n²)	O(1)
Selection Sort	O(n²)	O(n²)	O(n²)	O(1)
Insertion Sort	O(n)	O(n²)	O(n²)	O(1)
Merge Sort	O(n log n)	O(n log n)	O(n log n)	O(n)
Quick Sort	O(n log n)	O(n log n)	O(n²)	O(log n)
Heap Sort	O(n log n)	O(n log n)	O(n log n)	O(1)
Tim Sort (JS default)	O(n)	O(n log n)	O(n log n)	O(n)

Trees

h = height
Balanced tree → h = log n
Skewed tree   → h = n
Always state both cases in interviews.

Operation	Time	Space
DFS traversal (any)	O(n)	O(h)
BFS level order	O(n)	O(n)
BST search (balanced)	O(log n)	O(log n)
BST search (skewed)	O(n)	O(n)
BST insert (balanced)	O(log n)	O(log n)
BST insert (skewed)	O(n)	O(n)
Max depth	O(n)	O(h)
Lowest common ancestor	O(n)	O(h)

BFS space = O(n) because last level holds ~n/2 nodes (widest point).
DFS space = O(h) because only one root→leaf path is on stack at once.

Heap (Priority Queue)

Always balanced → height = log n
Insert  → add at bottom → bubble UP   → O(log n)
Remove  → swap root with last → bubble DOWN → O(log n)

Operation	Time	Space
Insert	O(log n)	O(1)
Remove top (min/max)	O(log n)	O(1)
Peek top	O(1)	O(1)
Search	O(n)	O(1)
Build heap from array	O(n)	O(1)
Top K elements	O(n log k)	O(k)

Top K pattern: Keep heap of size k → each insert/remove is O(log k) not O(log n).

Graphs

V = number of vertices (nodes)
E = number of edges

Storage

Structure	Space	Check edge	Get neighbors
Adjacency List	O(V+E)	O(degree)	O(degree)
Adjacency Matrix	O(V²)	O(1)	O(V)

Traversal & Algorithms

Algorithm	Time	Space
DFS	O(V+E)	O(V)
BFS	O(V+E)	O(V)
Grid DFS/BFS (m×n grid)	O(m×n)	O(m×n)
Cycle detection (Union Find)	O(E)	O(V)
Connected components (Union Find)	O(E)	O(V)
Dijkstra (min heap)	O(E log V)	O(E)

Union Find (Disjoint Set)

Operation	Time	Space
find (with path compression)	O(α(n)) ≈ O(1)	O(V)
union (with rank)	O(α(n)) ≈ O(1)	O(V)

α(n) = inverse Ackermann — practically constant for all real inputs.

Graph traversal rule: Time = O(V+E) because every node visited once (V) and every edge processed once (E).

Data Structures — Quick Reference

Structure	Access	Search	Insert	Delete	Space
Array	O(1)	O(n)	O(n)	O(n)	O(n)
Linked List	O(n)	O(n)	O(1) head	O(1) head	O(n)
Hash Map	O(1) avg	O(1) avg	O(1) avg	O(1) avg	O(n)
BST (balanced)	O(log n)	O(log n)	O(log n)	O(log n)	O(n)
Heap	—	O(n)	O(log n)	O(log n)	O(n)
Stack / Queue	O(n)	O(n)	O(1)	O(1)	O(n)

Dynamic Programming

DP = Recursion + Memoization (top-down) OR Iteration + Tabulation (bottom-up)

Time  = number of unique subproblems × work per subproblem
Space = number of unique subproblems (memo/dp table)

Pattern	Time	Space	Space (optimized)
1D DP (fibonacci, climbing stairs)	O(n)	O(n)	O(1)
2D DP (grid, strings)	O(n×m)	O(n×m)	O(n) or O(m)
Knapsack (0/1)	O(n×W)	O(n×W)	O(W)
Longest Common Subsequence	O(n×m)	O(n×m)	O(min(n,m))
Longest Increasing Subsequence	O(n²)	O(n)	—
LIS (binary search)	O(n log n)	O(n)	—
Matrix chain / interval DP	O(n³)	O(n²)	—
Coin change	O(n×amount)	O(amount)	—

Key Rule: Without memoization, exponential. With memoization, each subproblem solved once → polynomial.
Space optimization: 2D DP can often use a single row/column if only previous row is needed.

Backtracking

Backtracking = DFS on decision tree + pruning

Time  = O(branches^depth) — worst case explores all paths
Space = O(depth) — call stack + current path

Problem	Time	Space
Subsets (power set)	O(2ⁿ)	O(n)
Permutations	O(n!)	O(n)
Combinations (nCk)	O(2ⁿ)	O(n)
N-Queens	O(n!)	O(n)
Sudoku solver	O(9^(n²))	O(n²)
Word search in grid	O(m×n×4^L)	O(L)

L = word length, n = board size
Pruning reduces actual runtime significantly but worst case stays the same.

Two Pointers & Sliding Window

Pattern	Time	Space
Two pointers (sorted array)	O(n)	O(1)
Two pointers (linked list)	O(n)	O(1)
Sliding window (fixed size)	O(n)	O(1)
Sliding window (variable size)	O(n)	O(k)
Sliding window (with freq map)	O(n)	O(k)

Key Rule: Sliding window converts O(n²) brute force to O(n) by avoiding recomputation.

Binary Search

Always applied on SORTED input or monotonic condition.
Cuts search space in HALF each step → O(log n).

Pattern	Time	Space
Classic binary search	O(log n)	O(1)
Binary search (recursive)	O(log n)	O(log n)
Search in rotated array	O(log n)	O(1)
Binary search on answer	O(log n × f(n))	O(1)
Find peak element	O(log n)	O(1)

Binary search on answer: When you binary search on the result range, multiply by cost of checking each candidate f(n).

Stack & Queue

Operation	Time	Space
Push / Pop / Peek (stack)	O(1)	O(n)
Enqueue / Dequeue (queue)	O(1)	O(n)
Monotonic stack (next greater)	O(n) amortized	O(n)
Valid parentheses	O(n)	O(n)
Min stack (get min in O(1))	O(1) per op	O(n)
Largest rectangle in histogram	O(n)	O(n)

Monotonic stack: Each element pushed/popped at most once → O(n) total even with inner loop.

Trie (Prefix Tree)

Each node = one character
n = number of words, L = average word length

Operation	Time	Space
Insert word	O(L)	O(n×L) total
Search word	O(L)	O(1)
Search prefix	O(L)	O(1)
Delete word	O(L)	O(1)

Bit Manipulation

Operation	Time	Space
Check bit i	O(1)	O(1)
Set / clear / toggle bit	O(1)	O(1)
Count set bits (naive)	O(log n)	O(1)
Count set bits (Brian Kernighan)	O(set bits)	O(1)
XOR all elements (find unique)	O(n)	O(1)
Power of 2 check (`n & n-1 == 0`)	O(1)	O(1)

Mental Model — Quick Lookup

Halving input each step?              → O(log n)
One loop?                             → O(n)
Loop inside loop?                     → O(n²)
Branching recursion (2 branches)?     → O(2ⁿ) time, O(n) space
Hash map lookup?                      → O(1)
Sorting?                              → at best O(n log n)
Tree/graph traversal?                 → O(n) or O(V+E)
Heap insert/remove?                   → O(log n)
Top K with heap?                      → O(n log k)
Dijkstra?                             → O(E log V)
DP (unique subproblems)?              → O(states × work per state)
Backtracking (permutations)?          → O(n!)
Backtracking (subsets)?               → O(2ⁿ)
Sliding window?                       → O(n)
Monotonic stack?                      → O(n) amortized
Trie insert/search?                   → O(L) where L = word length

Frontend System Design: Virtualization & Handling Large Data Sets

ZeeshanAli-0704 — Sun, 15 Mar 2026 17:27:03 +0000

Virtualization & Handling Large Data Sets

Render only what's visible — lists, tables, infinite scroll, canvas grids, and architecture patterns.

Why Virtualization
How Virtualization Works
Library Comparison and Decision Guide
Infinite Scrolling Patterns
Large Table Rendering
Canvas Based Rendering (Extreme Data)
Performance Optimization
Accessibility (A11y)
Architecture Decision Guide
Real World Case Studies
Common Pitfalls
Interview Questions
Quick Reference Card

⬆ Back to Top

Why Virtualization

Modern web applications routinely deal with large data sets — product catalogs with 50K items, analytics dashboards with 100K rows, chat logs spanning years. The natural instinct is to render everything into the DOM and let the browser handle it. But the browser's rendering pipeline was never designed for tens of thousands of nodes simultaneously. Every DOM node passes through style calculation → layout → paint → composite on every frame. When you have 50,000 nodes, the browser spends more time on off-screen elements than on what the user actually sees. Virtualization exists to solve this fundamental mismatch between data size and rendering capacity.

The Problem — DOM Is Expensive

10,000 rows × ~5 DOM nodes each = 50,000 DOM nodes

Each node costs:
  ├── Memory:  ~0.5–1 KB per node
  ├── Layout:  Browser calculates position for ALL nodes
  ├── Paint:   Renders ALL visible + off-screen nodes
  └── GC:      Tracks all references

Result: 50 MB+ memory, 2–5s initial render, scroll jank, input lag

Without vs With Virtualization

Without Virtualization              With Virtualization
┌──────────────┐                    ┌──────────────┐
│ Row 1        │ ← rendered         │              │ ← padding-top (spacer)
│ Row 2        │ ← rendered         │╔════════════╗│
│ Row 3        │ ← rendered         │║ Row 5      ║│ ← rendered (visible)
│ ...          │                    │║ Row 6      ║│ ← rendered (visible)
│ Row 9999     │ ← rendered         │║ Row 7      ║│ ← rendered (visible)
│ Row 10K      │ ← rendered         │╚════════════╝│
└──────────────┘                    │              │ ← padding-bottom (spacer)
                                    └──────────────┘
DOM: 10,000 nodes                   DOM: ~10 nodes + spacers
Memory: O(n)                        Memory: O(viewport) — constant!

Performance Numbers

Rows	DOM Nodes	Render Time	Scroll FPS	Memory
100	500	~20ms	60 fps	~5 MB
10,000	50,000	~2,000ms	20-30 fps	~80 MB
100,000	500,000	~15,000ms+	< 10 fps	~500 MB+
100K virtualized	~500	~50ms	60 fps	~10 MB

Key Insight: Virtualization keeps DOM node count near-constant regardless of data size.

⬆ Back to Top

How Virtualization Works

Virtualization (also called windowing) is the technique of only rendering elements currently visible in the viewport, plus a small overscan buffer, while maintaining the illusion of a full scrollable list. The browser's native scrollbar still behaves as if all items exist — the trick is that a tall "phantom" container (set to the total height of all items) creates the scrollbar, but actual DOM nodes are only created for the ~20–30 items the user can see.

This is conceptually similar to how a movie projector works: the audience sees a continuous stream of images, but only one frame is displayed at any given moment. The rest of the film reel exists but isn't being projected.

Core Math (Fixed Height)

The core algorithm is surprisingly simple for fixed-height items. Since every item has the same height, we can compute the exact position of any item with basic arithmetic — no measurement needed. The virtualizer listens to the scroll event, reads scrollTop, divides by itemHeight to find which item the user is looking at, then renders only a small window around that index.

Given:
  containerHeight = 600px,  itemHeight = 40px
  totalItems = 50,000,      scrollTop = 8,000px,  overscan = 5

Calculate:
  totalHeight = 50,000 × 40 = 2,000,000px       ← virtual scroll height
  startIndex  = floor(8000 / 40) = 200
  visibleCount = ceil(600 / 40) = 15
  endIndex    = 200 + 15 = 215

With overscan:
  renderStart = max(0, 200 - 5) = 195
  renderEnd   = min(50000, 215 + 5) = 220

→ Render items[195..220] = 25 DOM nodes instead of 50,000

Fixed vs Variable Height

Fixed-height virtualization is straightforward because offset = index × height gives O(1) random access to any item's position. Variable-height items are significantly harder. Since each item can be a different height (think tweets with images vs text-only), you can't use simple multiplication. Instead, you must maintain a prefix sum array — a running total of heights — so that offset[i] = sum of heights from item 0 to i-1. Finding which item is at a given scroll position then requires a binary search on this prefix sum array, giving O(log n) lookup.

The additional challenge with variable heights is that you often don't know the height until the item renders. Libraries solve this with an estimate-then-measure approach: provide an estimateSize for initial layout, render the items, measure their actual DOM height via getBoundingClientRect() or ResizeObserver, then correct the offsets.

Fixed Height:                       Variable Height:
┌────────────────┐  40px           ┌────────────────┐  30px
├────────────────┤  40px           ├────────────────┤  80px  ← expanded
├────────────────┤  40px           ├────────────────┤  120px ← has image
├────────────────┤  40px           ├────────────────┤  30px

offset = index × height            offset = prefixSum[index]
O(1) lookup                         O(log n) binary search on prefix sums

Architecture of a Virtualizer

Every virtualizer has the same fundamental structure: an outer scroll container (with overflow: auto) that detects scroll events, an inner container sized to the total virtual height of all items (creating the scrollbar), and a small set of rendered items positioned within that inner container. The space above and below rendered items is filled by spacers (padding, empty divs, or CSS transforms) to maintain the correct scroll position.

┌───────────────────────────────────────────────────────┐
│                  Scroll Container                     │
│  ┌─────────────────────────────────────────────────┐  │
│  │         Inner Container (total height)          │  │
│  │                                                 │  │
│  │  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐          │  │
│  │    Spacer Top (padding / transform)             │  │
│  │  └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘          │  │
│  │  ┌─────────────────────────────────────────┐    │  │
│  │  │  Rendered Item (startIndex)             │    │  │
│  │  │  Rendered Item (startIndex + 1)         │    │  │
│  │  │  ...                                    │    │  │
│  │  │  Rendered Item (endIndex)               │    │  │
│  │  └─────────────────────────────────────────┘    │  │
│  │  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐          │  │
│  │    Spacer Bottom                                │  │
│  │  └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘          │  │
│  └─────────────────────────────────────────────────┘  │
│                   ▲ scrollTop                         │
└───────────────────────────────────────────────────────┘

Three Positioning Strategies

Once the virtualizer knows which items to render, it needs to position them at the correct scroll offset. There are three approaches, each with different performance characteristics. The key insight is about which phase of the rendering pipeline each approach triggers:

Layout phase (expensive): Browser recalculates geometry of all affected elements
Paint phase (moderate): Browser redraws pixels for affected areas
Composite phase (cheap): GPU moves already-painted layers — no CPU recalculation

transform: translateY() wins because it only triggers compositing — the browser promotes the element to its own GPU layer and just repositions it, skipping layout and paint entirely.

Strategy	How	Used By	Why
Padding	`paddingTop` / `paddingBottom` on inner container	Simple custom builds	Easy, but triggers layout on change
Absolute	`position: absolute; top: offset` per item	react-window	Precise, each item independently placed
Transform	`translateY(offset)` on wrapper	react-virtuoso	GPU-accelerated, no layout — only compositing

Positioning comparison:

Padding:                  Absolute:                  Transform:
┌────────────┐           ┌────────────┐             ┌────────────┐
│ paddingTop │           │ relative   │             │ relative   │
│╔══════════╗│           │   abs top:0│             │ translateY │
│║ items    ║│           │   abs top:X│             │  ┌──────┐  │
│╚══════════╝│           │   abs top:Y│             │  │items │  │
│ paddingBot │           │            │             │  └──────┘  │
└────────────┘           └────────────┘             └────────────┘
Triggers layout          Triggers layout            GPU compositing only ✅

Core Principles Summary

Principle	What It Means	Why It Matters
Viewport-only rendering	Only items visible (± overscan) exist in DOM	Keeps DOM node count constant O(viewport), regardless of data size — eliminates the root cause of slowness
Spacer/padding trick	Total scroll height preserved using padding or a sentinel div	Creates the native scrollbar illusion — browser thinks all items are rendered, user sees correct scroll thumb size and position
Scroll sync	`scrollTop / itemHeight` → data index mapping	Connects the physical scroll position to the logical data index — this is the core calculation that drives which items get rendered
Overscan	Extra items rendered above/below visible area	Prevents blank flashes during fast scrolling — items are pre-rendered just off-screen so they appear instantly when scrolled into view
Recycling	Some implementations reuse DOM nodes instead of creating/destroying	Reduces garbage collection pressure — instead of creating 20 new nodes and destroying 20 old ones per scroll, the same nodes get new content

⬆ Back to Top

Library Comparison and Decision Guide

Choosing a virtualization library is one of the most impactful architectural decisions for data-heavy UIs. The core trade-off is between simplicity (less control, more opinions) and flexibility (more control, more boilerplate). There are two fundamental API philosophies:

Component-based (react-window, react-virtuoso): You render a <FixedSizeList> or <Virtuoso> component that owns the scroll container, the positioning logic, and the rendering. You just provide an itemContent renderer. Less code, but the library controls the DOM structure.
Headless (TanStack Virtual): The library gives you a hook (useVirtualizer) that returns mathematical calculations — which items are visible, what their offsets are, total height. You own 100% of the markup and styling. More boilerplate, but total flexibility.

The right choice depends on your constraints: Do you need to match a custom design system? Use headless. Do you need grouped headers and infinite scroll working in 10 minutes? Use batteries-included.

Library Evolution

react-virtualized (2015) ← Legacy, large bundle, feature-rich
       │
react-window (2018)      ← Lighter rewrite by same author
       │
@tanstack/react-virtual  ← Framework-agnostic, headless, modern
       │
react-virtuoso (2019+)   ← Zero-config, dynamic heights, batteries-included

Comparison Table

Feature	react-window	react-virtuoso	TanStack Virtual
Bundle	~6 KB	~16 KB	~4 KB
API Style	Component	Component	Headless hook
Fixed-size items	✅	✅	✅
Variable-size	⚠️ must know sizes	✅ auto-measured	✅ via `measureElement`
Infinite scroll	Via addon	✅ built-in	Manual
Sticky headers	❌	✅ built-in	Manual
Table support	Grid component	✅ `TableVirtuoso`	Manual (headless)
Horizontal	✅ Grid	❌	✅
Bidirectional (chat)	❌	✅	Manual
SSR	⚠️ Limited	✅	✅
Frameworks	React only	React only	React, Vue, Solid, Svelte
Maintained (2024+)	Low	Active	Very active

Decision Flowchart

Need list virtualization?
│
├─ Fixed-height items, simple list?
│  └─ react-window ✅ (smallest, simplest)
│
├─ Dynamic heights, zero-config needed?
│  ├─ Need infinite scroll, grouped headers, tables?
│  │  └─ react-virtuoso ✅ (batteries included)
│  └─ Just simple dynamic list?
│     └─ react-virtuoso or TanStack Virtual
│
├─ Need full markup/styling control?
│  └─ @tanstack/react-virtual ✅ (headless)
│
├─ Not using React? (Vue, Solid, Svelte)
│  └─ @tanstack/virtual ✅ (framework-agnostic)
│
├─ Custom table with column virtualization?
│  └─ TanStack Virtual + TanStack Table ✅
│
└─ Chat UI with bidirectional scroll?
   └─ react-virtuoso ✅ (reversed mode)

Usage Syntax At a Glance

react-window — Component-based, sizes upfront:

<FixedSizeList height={600} itemCount={items.length} itemSize={50} overscanCount={5}>
  {({ index, style }) => <div style={style}>{items[index].name}</div>}
</FixedSizeList>

react-virtuoso — Zero-config, auto-measures:

<Virtuoso
  style={{ height: '600px' }}
  totalCount={items.length}
  itemContent={(index) => <div>{items[index].name}</div>}
/>

TanStack Virtual — Headless hook, you own the markup:

const virtualizer = useVirtualizer({
  count: items.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 50,
});

// You render: virtualizer.getVirtualItems().map(row => ...)
// You position: transform: `translateY(${row.start}px)`

⬆ Back to Top

Infinite Scrolling Patterns

Infinite scrolling is a UX pattern where new data loads automatically as the user scrolls, eliminating explicit "next page" buttons. But it introduces two fundamental challenges:

When to fetch: The app must detect that the user is approaching the end of loaded content and trigger a network request before they see blank space. Too late and users see a loading spinner; too early and you waste bandwidth.
DOM growth: Without virtualization, infinite scroll creates an ever-growing DOM. A user who scrolls through 500 pages has 25,000 DOM nodes in memory. Combining infinite scroll with virtualization solves this — the data grows in memory but the DOM stays constant.

The gold standard in production is: cursor-based pagination on the API + useInfiniteQuery for caching + virtualization for rendering. This gives you bounded DOM, efficient network usage, and a seamless user experience.

Pattern Overview

Infinite Scroll Approaches:

1. Intersection Observer (Modern ✅ Recommended)
   └─ Sentinel element at bottom → fires callback when visible

2. Scroll Position (Legacy)
   └─ scrollTop + clientHeight >= scrollHeight - threshold

3. Virtualized + Infinite Scroll (Best for Large Lists ✅)
   └─ Combine virtualization + data fetching

4. Bidirectional (Chat UIs)
   └─ Load older messages at top, new at bottom
   └─ Maintain scroll position when prepending

Pattern 1: Intersection Observer

The Intersection Observer API is a browser-native mechanism for efficiently detecting when an element enters or exits the viewport (or any ancestor scroll container). Unlike scroll event listeners — which fire synchronously on every pixel of scroll and require manual math to determine element visibility — Intersection Observer is asynchronous and batched by the browser. The browser itself determines when elements cross visibility thresholds during its rendering cycle, making it significantly cheaper than polling scroll positions.

The pattern uses a sentinel element — a tiny 1px div placed after the last item. The observer watches this sentinel. The rootMargin property extends the detection zone (e.g., 200px below the viewport), so the fetch triggers before the user reaches the end — giving the network request time to complete before the user sees empty space.

How it works:

  ┌─────────────────────────┐
  │     Scroll Container     │
  │  ┌───────────────────┐  │
  │  │   Item 1          │  │
  │  │   ...             │  │  Visible Viewport
  │  │   Item 20         │  │
  │  └───────────────────┘  │
  │  ╔═══════════════════╗  │ ← rootMargin: 200px (pre-trigger zone)
  │  ╚═══════════════════╝  │
  │  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ┐  │
  │    Sentinel (1px div)   │ ← When enters rootMargin → fetchMore()
  │  └ ─ ─ ─ ─ ─ ─ ─ ─ ┘  │
  └─────────────────────────┘

Approach: Watch a 1px sentinel div. When it enters rootMargin zone, trigger fetch.

// Hook: useInfiniteScroll
const observer = new IntersectionObserver(
  ([entry]) => { if (entry.isIntersecting) fetchMore(); },
  { rootMargin: '200px', threshold: 0 }
);
observer.observe(sentinelRef.current);

// Component: Just place sentinel after items
{items.map(item => <div key={item.id}>{item.name}</div>)}
<div ref={sentinelRef} style={{ height: 1 }} />  {/* ← trigger */}

Why better than scroll events? No event listener overhead, no manual scroll math, built-in thresholding, more performant.

Pattern 2: Virtualized + Infinite Scroll (Gold Standard)

Approach: Virtualization for DOM + cursor-based pagination for data.

Data Flow:

  API (cursor-paginated)
       ↓
  useInfiniteQuery({ queryKey, queryFn, getNextPageParam })
       ↓
  allItems = pages.flatMap(p => p.data)
       ↓
  Virtualizer (only renders ~20-30 visible items)
       ↓
  When last virtual item visible → fetchNextPage()

react-virtuoso — Built-in:

<Virtuoso
  data={items}
  endReached={loadMore}   // ← fires when scrolled near bottom
  itemContent={(index, item) => <Item data={item} />}
  components={{ Footer: () => loading ? <Spinner /> : null }}
/>

TanStack Virtual + TanStack Query — Manual wiring:

const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({ ... });
const allItems = data?.pages.flatMap(p => p.data) ?? [];

const virtualizer = useVirtualizer({
  count: hasNextPage ? allItems.length + 1 : allItems.length, // +1 loader row
  ...
});

// In useEffect: when last virtualItem.index >= allItems.length → fetchNextPage()

Pattern 3: Bidirectional Scroll (Chat UIs)

Bidirectional scrolling is the hardest infinite scroll pattern. In a chat app, old messages load at the top when the user scrolls up, while new messages appear at the bottom in real-time. The critical challenge is scroll position stability: when you prepend 50 older messages above the current viewport, the browser naturally shifts everything down by the combined height of those new items, causing the viewport to "jump" — the message the user was reading disappears.

The solution is the firstItemIndex pattern: instead of array indices starting at 0, you start with a large synthetic index (like 10,000). When older messages are prepended, you decrement firstItemIndex. The virtualizer uses this to compute stable offsets, effectively "inserting" items above the viewport without shifting visible content.

Challenge — Prepending messages without scroll jump:

  Before prepend:               After prepend (WRONG):
  ┌─────────────────┐          ┌─────────────────┐
  │  Message 50     │ ← here   │  Message -49 ▲  │ ← viewport jumps!
  │  Message 51     │          │  Message -48    │
  └─────────────────┘          └─────────────────┘

  After prepend (CORRECT — scroll position preserved):
  ┌─────────────────┐
  │  Message -49     │ ← added above (off-screen)
  │  ...             │
  │  Message 50      │ ← still visible ✅
  └─────────────────┘

Approach: Use firstItemIndex pattern — start with large index, decrement on prepend:

<Virtuoso
  data={messages}
  firstItemIndex={firstItemIndex}           // Start at 10000, decrement on prepend
  initialTopMostItemIndex={messages.length - 1}  // Start at bottom
  startReached={loadOlderMessages}          // Called when scrolled to top
  followOutput="smooth"                     // Auto-scroll on new messages
/>

Cursor-Based vs Offset-Based Pagination

How you paginate your API directly affects the reliability of infinite scroll. Offset-based (?offset=200&limit=50) is simple but fragile — if items are inserted or deleted between requests, items get skipped or duplicated because the offset now points to a different position. Cursor-based (?cursor=abc123&limit=50) uses an opaque pointer (typically the last item's ID or a timestamp) to resume exactly where the previous page left off, regardless of insertions or deletions. For any real-time feed (social, chat, notifications), cursor-based is essential.

Aspect	Cursor-Based	Offset-Based
Consistency	✅ Stable with real-time data	❌ Skips/duplicates on insert/delete
Performance	✅ O(1) seek with index	❌ O(n) for large offsets
Jump to page	❌ Not possible	✅ Easy
Use when	Infinite scroll, feeds	Paginated tables

Cursor: GET /items?cursor=abc123&limit=50  → { data, nextCursor }
Offset: GET /items?offset=200&limit=50     → { data, total }

⬆ Back to Top

Large Table Rendering

Tables amplify the virtualization problem because data is two-dimensional. A list with 100K items has one axis to virtualize; a table with 100K rows × 50 columns has two axes. The cell count grows multiplicatively, not additively. This means you often need both a row virtualizer (vertical, based on scrollTop) and a column virtualizer (horizontal, based on scrollLeft) working simultaneously, rendering only the rectangular intersection of visible rows and visible columns.

Additionally, tables have unique UX requirements: sticky headers must remain visible while scrolling vertically, sticky columns (like an ID or name column) must remain visible while scrolling horizontally, and the corner cell where both sticky axes meet needs the highest z-index so it sits above everything.

The Challenge — 2D Virtualization

100,000 rows × 50 columns = 5,000,000 cells!

With Row Virtualization only (20 visible rows):
  20 × 50 = 1,000 cells → manageable

With Row + Column Virtualization (20 rows × 10 cols):
  200 cells → fast! ✅

Row Virtualization

┌──────────────────────────────────────────────────────┐
│  Col A    │  Col B    │  Col C    │  ...  │  Col Z   │
├───────────┼───────────┼───────────┼───────┼──────────┤
│  (padding-top: from hidden rows above)               │
├───────────┼───────────┼───────────┼───────┼──────────┤
│  Row 45   │  data     │  data     │  ...  │  data    │ ← Rendered
│  Row 46   │  data     │  data     │  ...  │  data    │ ← Rendered
│  ...      │  ...      │  ...      │  ...  │  ...     │
│  Row 64   │  data     │  data     │  ...  │  data    │ ← Rendered
├───────────┼───────────┼───────────┼───────┼──────────┤
│  (padding-bottom: from hidden rows below)            │
└──────────────────────────────────────────────────────┘

Column Virtualization

Full table: │ Col 1 │ Col 2 │ Col 3 │ ··· │ Col 50 │

Viewport (columns 5–15 visible):
              ┌─────────────────────────────┐
  padding-left│ Col 5 │ Col 6 │ ··· │Col 15│ padding-right
              └─────────────────────────────┘
                        ▲
                  scrollLeft

Approach: TanStack Table + TanStack Virtual

The modern standard for building production virtualized tables is to separate table logic from rendering logic. TanStack Table handles column definitions, sorting state, filtering, row selection, column resizing — all the data operations. TanStack Virtual handles which rows and columns are visible given the current scroll position. Neither library renders any DOM — they both return data/calculations that you render yourself. This separation gives you full control over markup, styling, and behavior while letting each library focus on what it does best.

Architecture:

  TanStack Table → column defs, sorting, filtering, selection
       ↓
  rows = table.getRowModel().rows
       ↓
  Row Virtualizer  → which rows to render (based on scrollTop)
  Col Virtualizer  → which cols to render (based on scrollLeft)
       ↓
  Render intersection: visible rows × visible columns
  + padding cells for unrendered columns
  + spacer rows for unrendered rows

// Two virtualizers working together
const rowVirtualizer = useVirtualizer({
  count: rows.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 40,
});

const colVirtualizer = useVirtualizer({
  horizontal: true,
  count: visibleColumns.length,
  getScrollElement: () => parentRef.current,
  estimateSize: (i) => visibleColumns[i].getSize(),
});

// Render: only intersection of virtualRows × virtualCols
// + paddingLeft/paddingRight cells for hidden columns
// + spacer <tr> for hidden rows above/below

Sticky Headers & Columns

Sticky positioning is one of CSS's most powerful features for data grids. position: sticky creates an element that behaves like relative positioning until it reaches a scroll threshold, then switches to behaving like fixed — all without JavaScript. The key implementation detail is z-index layering: the sticky header needs z-index: 2 (above scrolling rows), sticky columns need z-index: 1, and the corner cell (where sticky header meets sticky column) needs z-index: 3 so it sits above both. All sticky elements must have an opaque background — otherwise scrolling content bleeds through underneath them.

Normal scroll:                     Sticky header:
┌─────────────────┐               ┌─────────────────┐
│  Header Row     │ ← scrolls up  │  Header Row     │ ← stays fixed ✅
├─────────────────┤               ├─────────────────┤
│  Row 1          │               │  Row 50         │
│  Row 2          │               │  Row 51         │
└─────────────────┘               └─────────────────┘

Sticky column (horizontal scroll):
┌──────────┬──────────┬──────────┬──────────┐
│ Name     │ Col 5    │ Col 6    │ Col 7    │
│ (sticky) │          │          │          │  ← Col 1-4 scrolled out
├──────────┼──────────┼──────────┼──────────┤
│ Alice    │ data     │ data     │ data     │
│ Bob      │ data     │ data     │ data     │
└──────────┴──────────┴──────────┴──────────┘
  ▲ stays fixed

CSS approach:

/* Sticky header */
thead th { position: sticky; top: 0; z-index: 2; background: white; }

/* Sticky first column */
td:first-child, th:first-child { position: sticky; left: 0; z-index: 1; background: white; }

/* Corner cell (both axes) */
thead th:first-child { z-index: 3; }  /* Above both sticky header & column */

⬆ Back to Top

Canvas Based Rendering (Extreme Data)

When even virtualized DOM can't keep up — millions of cells, real-time streaming updates, complex conditional formatting — canvas rendering bypasses the DOM entirely. Instead of creating DOM nodes that the browser must manage through its rendering pipeline (style → layout → paint → composite), you draw pixels directly onto a <canvas> element using its 2D drawing API (fillRect, fillText, strokeRect).

The trade-off is fundamental: you gain raw speed (the browser doesn't track individual cells, no layout recalculation, no style resolution) but you lose everything the DOM provides for free — text selection, accessibility, event delegation, CSS styling, form elements, and SEO. You must manually implement hit-testing ("which cell did the user click?"), keyboard navigation, clipboard operations, and accessibility overlays. This is why canvas grids are reserved for extreme cases where DOM virtualization is genuinely insufficient.

When DOM vs Canvas

DOM Rendering (Virtualized)         Canvas Rendering
├── < 100K cells                    ├── > 100K cells
├── Rich interactions (forms)       ├── Display-heavy (read-only)
├── A11y required                   ├── Real-time data (trading, monitoring)
├── SEO needed                      ├── High update frequency
└── Standard table features         └── GPU-accelerated drawing

How Canvas Grids Work

A canvas grid treats the entire visible area as a single <canvas> element and draws cell content as pixels using the Canvas 2D API (ctx.fillText, ctx.fillRect, ctx.strokeRect). On scroll, the grid reads the new scroll position, calculates which rows/columns are visible (the same math as DOM virtualization), clears the canvas, and redraws only the visible cells in a single requestAnimationFrame callback.

The key architectural challenges are: event handling (canvas receives a single click event with clientX/clientY coordinates that must be translated to (row, col) via math), text editing (an invisible <input> element is overlaid on the canvas, positioned over the active cell), and accessibility (an ARIA grid overlay with visually hidden DOM nodes must mirror the visible canvas content for screen readers).

┌──────────────────────────────────────────┐
│          Canvas Grid Architecture         │
│                                           │
│  ┌────────────────────────────────────┐  │
│  │          <canvas>                   │  │
│  │   Painted pixels (NOT DOM nodes)    │  │
│  │   ┌─────┬─────┬─────┬─────┐       │  │
│  │   │ A1  │ B1  │ C1  │ D1  │       │  │
│  │   ├─────┼─────┼─────┼─────┤       │  │
│  │   │ A2  │ B2  │ C2  │ D2  │       │  │
│  │   └─────┴─────┴─────┴─────┘       │  │
│  └────────────────────────────────────┘  │
│                                           │
│  Events: Manual hit-testing               │
│    (clientX, clientY) → (row, col)        │
│  Scroll: requestAnimationFrame repaint    │
│  Edit:   Overlay <input> over cell        │
└──────────────────────────────────────────┘

Approach: Calculate visible range from scroll position → draw only visible cells on canvas → manual hit-testing for interactions → overlay native <input> for editing.

Canvas Libraries

Library	Use Case	Scale
Glide Data Grid	React canvas grid	1M+ cells
AG Grid (Enterprise)	Hybrid DOM/Canvas	Enterprise apps
Handsontable	Excel-like grid	Spreadsheets
PixiJS / Konva	Custom visualizations	Custom

Canvas vs DOM Trade-offs

Aspect	DOM (Virtualized)	Canvas
Max cells	~100K	Millions
Accessibility	Native	Must implement manually
Text selection	Native	Manual clipboard
Rich content	Any HTML/CSS	Must paint everything
Event handling	DOM events	Manual hit testing
Complexity	Low-Medium	High

⬆ Back to Top

Performance Optimization

Virtualization alone gets you 80% of the way to a smooth experience, but the remaining 20% comes from fine-tuning the rendering pipeline. The core issue: even though the virtualizer limits DOM nodes to ~20–30, each scroll event can still trigger re-renders, layout recalculations, and garbage collection. These micro-costs accumulate at 60fps (one frame every 16.6ms), and a single slow frame causes visible jank.

The optimization strategy is to minimize work at every level: (1) reduce how often React re-renders (memoization), (2) reduce what the browser recalculates per frame (CSS containment, transform positioning), (3) reduce GC pressure (stable keys, avoid inline allocations), and (4) move expensive work off the main thread (Web Workers for sorting/filtering).

Overscan Tuning

Overscan is the number of extra items rendered above and below the visible area. It's a direct trade-off: more overscan means fewer blank flashes during fast scrolling (items are pre-rendered off-screen), but too much overscan defeats the purpose of virtualization by keeping too many DOM nodes alive. The sweet spot depends on row complexity — simple text rows need less overscan than rows with images and interactive controls.

Too little (0):              Right (3-10):              Too much (50):
┌──────────────┐            ┌──────────────┐           ┌──────────────┐
│              │ ← blank!   │▒▒▒▒▒▒▒▒▒▒▒▒│ ← buffer  │▒▒▒▒▒▒▒▒▒▒▒▒│
│╔════════════╗│            │╔════════════╗│            │▒▒▒▒▒▒▒▒▒▒▒▒│
│║  Visible   ║│            │║  Visible   ║│            │╔════════════╗│
│╚════════════╝│            │╚════════════╝│            │╚════════════╝│
│              │ ← blank!   │▒▒▒▒▒▒▒▒▒▒▒▒│ ← buffer  │▒▒▒▒▒▒▒▒▒▒▒▒│
└──────────────┘            └──────────────┘           └──────────────┘
Fast but flickers           Smooth scrolling ✅        Defeats purpose

Scenario	Recommended Overscan
Simple text rows	3–5 items
Complex row renderers	5–10 items
Fast scroll (mobile)	10–20 items or 200–400px

Key Optimization Techniques

These techniques are ordered by impact-to-effort ratio. The first few are simple CSS/React changes that provide large gains; the later ones require more effort but handle edge cases.

Technique	Impact	Approach
`React.memo` on row components	High	Prevent re-renders on scroll
`useMemo` for data transforms	Medium	Avoid recomputing filtered/sorted data
`transform: translateY()` not `top`	Medium	GPU compositing, no layout trigger
`contain: layout style paint`	High	Isolate layout recalc per row
Reserve space for images	High	Set explicit `width`/`height` to avoid layout shift
`{ passive: true }` scroll listeners	Medium	Prevent scroll jank
`requestAnimationFrame` scroll batching	Medium	Batch scroll state updates
Web Worker for data processing	High	Offload filtering/sorting from main thread
`content-visibility: auto`	High	Browser-native lazy rendering (non-virtualized)
Avoid inline objects/functions in render	Medium	Prevents child re-renders

Scroll Performance Pattern

Scroll events fire at 60+ times per second. If each event calls setState, React schedules a re-render for every event — potentially 60+ re-renders per second. requestAnimationFrame batching ensures only one state update per visual frame, matching the browser's actual repaint rate. Production libraries like TanStack Virtual handle this internally using observeElementOffset, so you typically don't need to implement this yourself.

// ❌ Bad: setState on every scroll → re-render every frame
const handleScroll = (e) => setScrollTop(e.currentTarget.scrollTop);

// ✅ Better: Batch with requestAnimationFrame
const rafRef = useRef(null);
const handleScroll = useCallback((e) => {
  if (rafRef.current) cancelAnimationFrame(rafRef.current);
  rafRef.current = requestAnimationFrame(() => {
    setScrollTop(e.currentTarget.scrollTop);
  });
}, []);

// ✅ Best: Libraries (TanStack Virtual) handle this internally

⬆ Back to Top

Accessibility (A11y)

Virtualization creates a fundamental tension with accessibility. Screen readers rely on the DOM to understand content — they traverse DOM nodes to announce content, count items, and navigate. But virtualization removes most items from the DOM to improve performance. A screen reader visiting a virtualized list with 10,000 items would only "see" 20–30 DOM nodes and have no knowledge of the other 9,970+.

The solution is ARIA attributes that communicate the logical structure of the list (total count, each item's position) without requiring all items to be in the DOM. Combined with keyboard navigation that programmatically scrolls to items on arrow key presses, screen reader users can navigate the full list even though most items aren't rendered.

Challenge

Screen readers can only see items currently in the DOM. Off-screen virtualized items are invisible.

ARIA Attributes Approach

aria-rowcount on the container tells the screen reader the total number of items in the list, even though most aren't in the DOM. aria-rowindex on each rendered item tells the screen reader where this item sits in the full list (using 1-based indexing). Together, these attributes let the screen reader announce things like "Item 156 of 10,000" — giving the user full positional awareness despite only ~20 items existing in the DOM.

Container:
  role="list"
  aria-label="Search results"
  aria-rowcount={totalItems}           ← total count

Each item:
  role="listitem"
  aria-rowindex={index + 1}            ← 1-based position
  aria-setsize={totalItems}            ← total count
  aria-posinset={index + 1}            ← position in set

Keyboard Navigation

Keyboard navigation in virtualized lists requires extra work because the target item might not exist in the DOM yet. When the user presses Arrow Down to move to the next item, you must: (1) update the focused index in state, (2) tell the virtualizer to scrollToIndex so the target item gets rendered, and (3) set focus on the newly rendered DOM node. This three-step process — state update, scroll, focus — must happen in sequence, and the focus step often needs a requestAnimationFrame delay to wait for the item to actually render.

Key	Action
`↓` Arrow Down	Move focus to next item + `scrollToIndex`
`↑` Arrow Up	Move focus to prev item + `scrollToIndex`
`Home`	Jump to first item
`End`	Jump to last item
`Page Up/Down`	Scroll by page

A11y Checklist

The key principle is: tell the screen reader what it can't see. Use ARIA to communicate the full logical structure, keyboard handlers to enable navigation, and live regions to announce dynamic changes.

Requirement	How
Total count announced	`aria-rowcount` on container
Item position	`aria-rowindex`, `aria-posinset`, `aria-setsize`
Keyboard navigation	Arrow keys + `scrollToIndex`
Focus management	`tabIndex`, scroll-to-focused
Loading states	`aria-live="polite"` region
Table semantics	`<table>`, `<thead>`, `role="grid"`

⬆ Back to Top

Architecture Decision Guide

The biggest mistake teams make is reaching for virtualization too early (adding complexity to a 100-item list) or too late (discovering at scale that their non-virtualized table is unusable). The thresholds below are based on real-world measurements across typical React applications. Below ~200 items, the browser handles rendering efficiently and virtualization adds unnecessary complexity. Between 200-5K, simple virtualization provides a massive improvement. Beyond 5K, you need to combine virtualization with strategic data fetching. Beyond 100K in a table context, you need 2D virtualization. And at 1M+ cells, even virtualized DOM may not keep up — that's canvas territory.

Choosing the Right Pattern

How many items?

  < 200 items
  └─ Plain rendering. No virtualization needed.
     (CSS content-visibility: auto can help)

  200 – 5,000 items
  └─ Simple virtualization
     ├─ Fixed heights → react-window
     └─ Dynamic heights → react-virtuoso

  5,000 – 100,000 items
  └─ Virtualization + infinite scroll
     ├─ react-virtuoso (built-in endReached)
     └─ TanStack Virtual + TanStack Query

  100,000+ items (tables)
  └─ Row + Column virtualization
     ├─ TanStack Table + TanStack Virtual
     └─ AG Grid, Glide Data Grid

  1,000,000+ cells (extreme)
  └─ Canvas-based rendering
     └─ Glide Data Grid, custom canvas

Full Architecture for Data-Heavy App

The modern production stack for data-heavy applications follows a clear separation of concerns: data fetching (TanStack Query manages caching, pagination, and deduplication), data operations (TanStack Table handles sorting, filtering, column state), rendering optimization (TanStack Virtual calculates which items to render), and DOM output (your components render only the visible intersection). Each layer is independently testable and replaceable.

┌─────────────────────────────────────────────────────────┐
│                 Frontend Architecture                    │
│                                                          │
│  Search/Filter (debounced 300ms) + Sort Controls         │
│           │                                              │
│           ▼                                              │
│  ┌─────────────────────────────────────┐                │
│  │  TanStack Query (useInfiniteQuery)  │                │
│  │  Pages loaded on demand             │  Cursor-based  │
│  │  maxPages: 10 (memory limit)        │  pagination    │
│  └──────────────┬──────────────────────┘                │
│                 │ allItems = pages.flatMap(p => p.data)  │
│                 ▼                                        │
│  ┌─────────────────────────────────────┐                │
│  │  TanStack Table                     │                │
│  │  (columns, sorting, filtering)      │                │
│  └──────────────┬──────────────────────┘                │
│                 │ rows = table.getRowModel().rows        │
│                 ▼                                        │
│  ┌─────────────────────────────────────┐                │
│  │  TanStack Virtual                   │                │
│  │  Row virtualizer + Col virtualizer  │                │
│  │  Renders ~20-30 visible rows        │                │
│  └──────────────┬──────────────────────┘                │
│                 ▼                                        │
│  ┌─────────────────────────────────────┐                │
│  │  DOM: <table>                       │                │
│  │  Sticky <thead> (position: sticky)  │                │
│  │  Virtualized <tbody> (translateY)   │                │
│  └─────────────────────────────────────┘                │
└─────────────────────────────────────────────────────────┘

⬆ Back to Top

Real World Case Studies

These case studies show how real products solve virtualization challenges. The common thread is that each product hit a specific scale threshold where naive DOM rendering failed, and their solution was tailored to their specific constraints — dynamic heights for feeds, bidirectional scroll for chat, canvas for real-time finance.

Twitter/X Feed

Problem: Infinite feed with variable-height tweets
Solution:
  ├── Virtualized list (dynamic height measurement)
  ├── Intersection Observer for infinite loading
  ├── Cursor-based pagination (tweet ID as cursor)
  ├── Height pre-estimation + correction after paint
  └── Scroll position restoration on back-nav

Google Sheets

Problem: 1M+ cells, real-time collaboration, complex formatting
Solution:
  ├── Canvas-based rendering (only way at 1M+ scale)
  ├── Overlay <input> for cell editing
  ├── Only repaints dirty regions (not full canvas)
  ├── Web Worker for formula calculation
  └── ARIA grid overlay for screen readers

Slack Messages

Problem: Bidirectional scroll (old up, new down)
Solution:
  ├── react-virtuoso with reversed mode
  ├── firstItemIndex pattern for prepend stability
  ├── Auto-scroll on new messages (followOutput)
  └── "Jump to latest" button when scrolled up

Bloomberg Terminal

Problem: Real-time streaming data, thousands of instruments
Solution:
  ├── Canvas grid (DOM can't handle per-second updates)
  ├── Cell-level dirty tracking (repaint only changed cells)
  ├── WebSocket for streaming prices
  ├── Double-buffering canvas (avoid flicker)
  └── requestAnimationFrame batching

⬆ Back to Top

Common Pitfalls

Virtualization looks straightforward in demos but has subtle failure modes in production. Most pitfalls fall into three categories: measurement errors (wrong heights cause scroll position drift), React rendering issues (unnecessary re-renders kill scroll performance), and memory management (data grows unbounded). Understanding these patterns saves hours of debugging.

Pitfall	Symptom	Fix
Wrong item heights	Scroll jumping, gaps	Accurate `estimateSize`, use `measureElement`
Array index as key	Items swap/flash on scroll	Use stable IDs (`item.id`)
Unbounded data growth	Memory grows over time	Page eviction, `maxPages` in TanStack Query
No overscan	Blank flashes on fast scroll	Set overscan to 5–10
Inline functions in render	Unnecessary re-renders	`React.memo`, extract components
`overflow: hidden` parent	Scroll doesn't work	Ensure `overflow: auto` on scroll container
Dynamic content (images)	Layout shift after render	Reserve space with explicit dimensions
SSR mismatch	Hydration errors	`initialItemCount`, server render first N items

Memory Management for Infinite Scroll

Virtualization solves the DOM problem (only ~20 nodes in the DOM at any time) but doesn't solve the data problem. If a user scrolls through 500 pages of results, all 25,000 items are still in JavaScript memory even though only 20 are rendered. For most applications this is fine — JavaScript objects are lightweight compared to DOM nodes. But for very long sessions or memory-constrained devices, you need page eviction: keep only N pages of data in memory (e.g., maxPages: 10 in TanStack Query), and re-fetch evicted pages if the user scrolls back to them. This adds complexity but bounds total memory usage.

Problem: items array grows unbounded as user scrolls

  Page 1:   50 items   → fine
  Page 50:  2,500      → acceptable
  Page 500: 25,000     → memory problem!

Solutions:
  1. Virtualization handles DOM ✅ (only ~20 nodes)
  2. Limit data in memory:
     - TanStack Query: maxPages: 10
     - Custom: keep pages [current-5, current+2], evict rest
     - Re-fetch evicted pages if user scrolls back

⬆ Back to Top

Interview Questions

Virtualization is a common system design interview topic because it tests multiple skills simultaneously: understanding of browser rendering (why the DOM is expensive), algorithmic thinking (prefix sums, binary search for variable heights), API design (cursor vs offset pagination), and architectural judgment (when to use what tool). The questions below progress from conceptual understanding to system design.

Q1: What is virtualization and why is it needed?

Virtualization (windowing) = render only visible items + small overscan buffer. Needed because DOM is expensive — 10K+ nodes cause high memory, slow render, scroll jank. Keeps DOM count near-constant (~20–50 nodes) regardless of data size → O(1) render cost.

Q2: How does a virtualizer calculate which items to render?

Fixed height: startIndex = floor(scrollTop / itemHeight), visibleCount = ceil(containerHeight / itemHeight), add overscan. Total height = totalItems × itemHeight.

Variable height: Maintain prefix sum array of heights. Binary search on prefix sum to find startIndex for given scrollTop. Measure items post-render, update sizes dynamically.

Q3: How would you implement infinite scroll with virtualization?

Cursor-based API (?cursor=abc&limit=50)
useInfiniteQuery manages paginated cache
Flatten pages → single items array
Virtualizer renders visible items only
When last virtual item visible → fetchNextPage()
maxPages to limit memory

Q4: How do you handle column virtualization?

Two separate virtualizers:

Row virtualizer (vertical): which rows based on scrollTop
Column virtualizer (horizontal): which cols based on scrollLeft

Render only the intersection. Padding cells for non-rendered columns. TanStack Table + TanStack Virtual is the standard approach.

Q5: What are the accessibility challenges?

Screen readers can't see off-screen items. Solutions: aria-rowcount (total), aria-rowindex / aria-posinset (position), keyboard nav with scrollToIndex, aria-live for loading states, semantic <table> elements.

Q6: When would you use canvas over DOM virtualization?

Canvas when: 1M+ cells, real-time streaming data, high update frequency, read-only display.
Avoid canvas when: rich interactions, accessibility required, SEO needed, team lacks canvas expertise.

Q7: How do you prevent scroll position jumping?

Reserve space for media (explicit width/height)
Accurate estimateSize close to actual
Use measureElement to correct post-render
CSS contain: layout style paint on rows
Skeleton loading matching expected height

Q8: Design a virtualized grid — 100K rows, 50 columns, sortable, filterable.

API (cursor-paginated) → TanStack Query (cache + fetch)
  ↓
TanStack Table (column defs, sorting, filtering)
  ↓
Row Virtualizer + Column Virtualizer (TanStack Virtual)
  ↓
DOM <table>: sticky <thead>, virtualized <tbody>

Key decisions:
  - Server-side sort/filter (100K too much for client)
  - Row virtualizer: ~20-30 visible rows
  - Col virtualizer: ~8-10 visible columns
  - Fixed row height (40px) for predictability
  - Sticky header + sticky first column
  - Debounced filter (300ms) → new query
  - maxPages for memory management

Q9: How does "scroll to item" work with variable heights?

Virtualizer maintains offset map (prefix sum). To scroll to index N:

scrollTop = prefixSum[N] (start align)
Center: scrollTop = prefixSum[N] - containerHeight/2 + itemHeight/2
If unmeasured, use estimates → render → measure → correct position

APIs:
  react-window:   listRef.current.scrollToItem(index, 'center')
  react-virtuoso: virtuosoRef.current.scrollToIndex({ index, align: 'center' })
  TanStack:       virtualizer.scrollToIndex(index, { align: 'center' })

Q10: Compare `transform: translateY()` vs `position: absolute; top:`

Aspect	`translateY()`	`absolute + top`
Rendering	GPU compositing only	Triggers layout
Performance	Faster ✅	Slower
Used by	react-virtuoso, TanStack Virtual	react-window
Why better	Skips layout & paint phases, only compositing step

⬆ Back to Top

Quick Reference Card

Virtualization = render only visible items + overscan buffer
  ├── Math: startIndex = floor(scrollTop / itemHeight)
  ├── Position: translateY (GPU) > absolute top > padding
  └── DOM stays O(viewport), never O(n)

Libraries:
  react-window   → simple, fixed-size, ~6KB
  react-virtuoso → zero-config, dynamic, batteries, ~16KB
  TanStack Virtual → headless, any framework, ~4KB

Infinite Scroll:
  Intersection Observer + sentinel div (simple)
  Virtualized + useInfiniteQuery (production)
  Bidirectional + firstItemIndex (chat)

Tables:
  Row + Column virtualization for 2D
  TanStack Table (logic) + TanStack Virtual (rendering)
  Sticky: position: sticky + z-index layering

Canvas: 1M+ cells, real-time, read-only heavy
When NOT to virtualize: < 200 items

⬆ Back to Top

More Details:

Get all articles related to system design
Hashtag: SystemDesignWithZeeshanAli

systemdesignwithzeeshanali

Git: https://github.com/ZeeshanAli-0704/front-end-system-design

⬆ Back to Top

Frontend System Design: Performance Monitoring & Observability

ZeeshanAli-0704 — Sun, 15 Mar 2026 17:24:41 +0000

Performance Monitoring & Observability

A Complete Frontend System Design Guide — Theory, Patterns & Interview Focus

You can build the most elegant UI in the world, but if it takes 5 seconds to load or janks on every scroll, users leave. Performance monitoring isn't a one-time audit — it's a continuous feedback loop that tells you when things are slow, why they're slow, and for whom.

This guide covers Core Web Vitals, identifying and fixing bottlenecks, monitoring strategies, error tracking, performance budgets, and the tools & techniques (Chrome DevTools, Lighthouse, RUM) that make all of it actionable — all from a conceptual, interview-ready perspective.

Core Web Vitals What They Are and Why They Matter
Identifying Performance Bottlenecks
Fixing Performance Issues A Systematic Approach
Chrome DevTools and Available Tools
Real User Monitoring (RUM) vs Synthetic Monitoring
Error Tracking and Logging
Performance Budgets
The Three Pillars of Observability
Tradeoffs Gotchas and Common Pitfalls
Interview Questions and Answers ⬆ Back to Top

Core Web Vitals What They Are and Why They Matter

Core Web Vitals are a set of user-centric performance metrics defined by Google. Since June 2021, they are Google ranking signals, making them critical for both UX and SEO. They answer three fundamental questions about user experience:

┌─────────────────────────────────────────────────────────┐
│                   Core Web Vitals                       │
│                                                         │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   │
│   │     LCP     │   │     INP     │   │     CLS     │   │
│   │  (Loading)  │   │(Responsive) │   │ (Stability) │   │
│   │             │   │             │   │             │   │
│   │ "How fast   │   │ "How fast   │   │ "How stable │   │
│   │  does the   │   │  does it    │   │  is the     │   │
│   │  main       │   │  react to   │   │  visual     │   │
│   │  content    │   │  my input?" │   │  layout?"   │   │
│   │  appear?"   │   │             │   │             │   │
│   └─────────────┘   └─────────────┘   └─────────────┘   │
└─────────────────────────────────────────────────────────┘

The 75th Percentile Rule

Google evaluates Core Web Vitals at the 75th percentile of all page visits. This means 75% of your users must have a "good" experience for you to pass. If your median LCP is 2.0s but your p75 is 3.5s, you fail the assessment.

LCP — Largest Contentful Paint

What it measures: The time from page load start to when the largest visible content element (hero image, heading text, video poster) finishes rendering in the viewport.

Rating	Time
Good	≤ 2.5s
Needs Improvement	2.5s – 4.0s
Poor	> 4.0s

LCP candidate elements: <img>, <video> poster, elements with background-image, and block-level text elements like <h1>, <p>.

What causes poor LCP and how to fix it:

Cause	Why It's Slow	Fix
Slow server response (high TTFB)	Server takes too long to return HTML	CDN, edge caching, optimize backend queries
Render-blocking CSS/JS	Large CSS/JS files block the parser and delay paint	Inline critical CSS, defer non-critical CSS/JS
Slow resource loading	Hero image is unoptimized (2MB PNG)	Compress images, use WebP/AVIF, responsive `srcset`
Client-side rendering	SPA waits for JS → API → render cycle	Use SSR/SSG, stream HTML from server
Lazy-loaded LCP element	Hero image has `loading="lazy"` — browser delays it	Never lazy-load above-the-fold content
No resource prioritization	Browser treats LCP image same as everything else	Use `fetchpriority="high"` on the LCP image, `<link rel="preload">`
Redirect chains	Multiple 301/302 redirects before actual page	Minimize redirects — each adds a full round trip

INP — Interaction to Next Paint

What it measures: INP measures the latency of all user interactions (clicks, taps, key presses) throughout the page's lifetime, and reports a value representing the worst interaction latency. It replaced FID in March 2024.

Rating	Time
Good	≤ 200ms
Needs Improvement	200ms – 500ms
Poor	> 500ms

Why INP replaced FID:

Aspect	FID (Deprecated)	INP (Current)
What's measured	Delay of first input only	All interactions throughout page life
Scope	Single event	Full session
Includes processing time?	No — only input delay	Yes — input delay + processing + presentation delay
Real-world coverage	Misses 99% of interactions	Comprehensive

The three phases of an interaction:

┌───────────────┬─────────────────────┬──────────────────────┐
│  Input Delay  │  Processing Time    │  Presentation Delay  │
│  (main thread │  (event handlers    │  (render, layout,    │
│   was busy)   │   executing)        │   paint, composite)  │
└───────────────┴─────────────────────┴──────────────────────┘
               ← ──── Total INP Latency ──── →

Input Delay: User clicked but the main thread was blocked by another task — the event handler is queued.
Processing Time: How long your event handler code takes to execute.
Presentation Delay: After handler finishes, how long until the browser paints the visual update.

What causes poor INP and how to fix it:

Cause	Why It's Slow	Fix
Long tasks on main thread	Heavy JS blocks the thread during interaction	Break tasks with `scheduler.yield()` or `setTimeout` chunking
Large DOM size	10,000+ nodes — layout/style recalculation is expensive	Virtualize long lists, simplify DOM structure
Expensive re-renders	Framework re-renders entire component tree	Memoize components, colocate state, use selectors
Forced synchronous layout	Reading layout props after writes causes "layout thrashing"	Batch DOM reads before writes
Third-party scripts	Ad/analytics scripts competing for main thread	Load async, defer, or move to Web Workers
No yielding in long handlers	Single handler runs 300ms without breaks	Yield to browser between chunks of work

CLS — Cumulative Layout Shift

What it measures: CLS quantifies how much visible content shifts unexpectedly during the page's lifetime. It measures visual stability — content jumping around without user interaction.

Rating	Score
Good	≤ 0.1
Needs Improvement	0.1 – 0.25
Poor	> 0.25

How CLS is calculated:

Layout Shift Score = Impact Fraction × Distance Fraction

Impact Fraction: Percentage of viewport affected by the shift
Distance Fraction: Greatest distance any element moved (as fraction of viewport)

CLS groups shifts into session windows (bursts within 1 second, max 5-second window). The largest session window is reported.

What causes poor CLS and how to fix it:

Cause	Why It Shifts	Fix
Images without dimensions	Image loads and pushes content down	Always set `width`/`height` or use CSS `aspect-ratio`
Ads/embeds without reserved space	Ad slot loads a 300px banner, pushing everything	Reserve space with min-height/aspect-ratio placeholders
Dynamically injected content	Cookie banner or notification pushes page down	Use `transform` animations, fixed/sticky positioning
Web font swap (FOUT)	Fallback font renders → web font loads → text reflows	Use `font-display: optional`, preload fonts, use `size-adjust`
Client-side rendering	Skeleton loads, then real content arrives with different dimensions	SSR/SSG, skeleton screens with correct dimensions
CSS animations using layout properties	Animating `top`/`left`/`width`/`height` triggers layout	Use `transform` (`translateY`, `scale`) — no layout cost

Supplementary Metrics Worth Knowing

Beyond the three Core Web Vitals, these metrics provide additional context:

Metric	What It Measures	Good Threshold
TTFB (Time to First Byte)	Server responsiveness — time until first byte of HTML arrives	≤ 800ms
FCP (First Contentful Paint)	Time until first text/image is painted on screen	≤ 1.8s
TTI (Time to Interactive)	Time until page is fully interactive (no long tasks blocking)	≤ 3.8s
TBT (Total Blocking Time)	Total time the main thread was blocked between FCP and TTI	≤ 200ms
Speed Index	How quickly visible content is populated (visual completeness)	≤ 3.4s

Interview insight: TTFB is not a Core Web Vital, but it's the root cause of most LCP issues. If TTFB is 2 seconds, your LCP can never be below 2 seconds. Always check TTFB first when debugging LCP.

⬆ Back to Top

Identifying Performance Bottlenecks

The hardest part of performance work isn't fixing issues — it's finding them. Here's a systematic approach to identifying bottlenecks across the loading, rendering, and interaction lifecycle.

The Performance Investigation Funnel

Step 1: What's the symptom?
         │
         ├── Page loads slowly        → Focus on loading metrics (LCP, TTFB, FCP)
         ├── Page feels janky/laggy   → Focus on interaction metrics (INP, TBT)
         ├── Content jumps around     → Focus on stability metrics (CLS)
         └── Specific action is slow  → Focus on that interaction's trace
         │
Step 2: Where is the bottleneck?
         │
         ├── Server response (TTFB)   → Backend/CDN issue
         ├── Resource downloading     → Large assets, no compression, no CDN
         ├── Render blocking          → CSS/JS blocking first paint
         ├── Main thread busy         → Heavy JS execution, long tasks
         ├── Layout thrashing         → DOM reads/writes interleaved
         └── Memory leaks             → Memory growing over time
         │
Step 3: Why is it slow?
         │
         Use Chrome DevTools to profile and trace the root cause

The Six Categories of Frontend Bottlenecks

┌──────────────────────────────────────────────────────────────────┐
│                Frontend Performance Bottlenecks                   │
│                                                                   │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐  │
│  │  Network   │ │  Parsing   │ │  Rendering │ │  JavaScript  │  │
│  │            │ │  & Loading │ │  & Layout  │ │  Execution   │  │
│  │ • TTFB     │ │ • Large    │ │ • Complex  │ │ • Long tasks │  │
│  │ • Large    │ │   HTML     │ │   selectors│ │ • Unoptimized│  │
│  │   payloads │ │ • Render-  │ │ • Forced   │ │   frameworks │  │
│  │ • No CDN   │ │   blocking │ │   sync     │ │ • Memory     │  │
│  │ • No       │ │   resources│ │   layout   │ │   leaks      │  │
│  │   compress │ │ • Too many │ │ • Excessive│ │ • No code    │  │
│  │ • DNS/TLS  │ │   requests │ │   repaints │ │   splitting  │  │
│  └────────────┘ └────────────┘ └────────────┘ └──────────────┘  │
│                                                                   │
│  ┌────────────┐ ┌──────────────────────────────────────────────┐ │
│  │  Memory    │ │           Third-Party Scripts                 │ │
│  │            │ │                                               │ │
│  │ • Detached │ │ • Analytics, ads, chat widgets, tag managers │ │
│  │   DOM nodes│ │ • Competing for main thread time             │ │
│  │ • Event    │ │ • Blocking critical rendering                │ │
│  │   listener │ │ • Uncontrolled payload sizes                 │ │
│  │   leaks    │ │                                               │ │
│  └────────────┘ └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

How to Identify Each Bottleneck Type

1. Network Bottlenecks

Symptoms: High TTFB, slow resource loading, waterfalls with large gaps.

How to find:

Chrome DevTools → Network panel → Sort by "Time" column → Look for requests > 1s
Check the Waterfall column — see if resources are loading sequentially instead of parallel
Look at TTFB (green bar in waterfall) — if it's large, the problem is server-side
Check Size column — large uncompressed assets are a red flag
Filter by "JS" or "CSS" — check if too many files are being loaded

Signs in the waterfall:
| Pattern | What It Means |
|---|---|
| Long green bar (TTFB) | Server is slow to respond |
| Long blue bar (download) | Asset is too large |
| Resources loading one after another | No parallelism — likely dependency chain or HTTP/1.1 |
| Many small requests | Consider bundling or using HTTP/2 multiplexing |
| Resources from many different domains | High DNS/TLS overhead per domain |

2. Render-Blocking Resources

Symptoms: Long gap between TTFB and FCP. Page is white for too long.

How to find:

Lighthouse audit → "Eliminate render-blocking resources" — lists every CSS/JS file that blocks rendering
DevTools → Performance panel → Record → Look for long "Parse HTML" → "Recalculate Style" → "Layout" before first paint
DevTools → Coverage tab (Ctrl+Shift+P → "Show Coverage") — shows what percentage of each CSS/JS file is actually used on this page

Key insight: A CSS file is render-blocking by default. A <script> tag without async/defer is parser-blocking. Both delay first paint.

3. Main Thread / JavaScript Bottlenecks

Symptoms: Poor INP, janky scrolling, slow interactions, high TBT.

How to find:

DevTools → Performance panel → Record an interaction → Look for Long Tasks (red-flagged bars > 50ms)
The "Main" thread flame chart shows exactly which functions are consuming time
Bottom-Up tab → Sort by "Self Time" to find the most expensive individual functions
Call Tree tab → Shows the call hierarchy, find root causes
Check for "Recalculate Style" and "Layout" entries — signs of layout thrashing

What Long Tasks look like:

Main Thread Timeline
─────────────────────────────────────────────
│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│ 120ms Long Task (red flag!)
│   ▓▓▓│ 20ms task
│ ▓▓▓▓▓▓▓▓▓│ 60ms Long Task
│▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│ 200ms Long Task (very bad!)
─────────────────────────────────────────────
Any task > 50ms is a "Long Task" that blocks interactions

4. Layout & Rendering Bottlenecks

Symptoms: CLS issues, janky animations, slow scroll.

How to find:

DevTools → Performance panel → Look for frequent "Layout" entries (purple bars) — each is a forced reflow
DevTools → Rendering tab → Enable "Layout Shift Regions" — flashes blue on areas that shift
DevTools → Rendering tab → Enable "Paint flashing" — green flashes show what's being repainted
DevTools → Layers panel — shows which elements have their own compositing layer

Layout thrashing pattern: Reading then writing to DOM repeatedly forces the browser to recalculate layout between each read-write pair. The fix is to batch all reads first, then all writes.

5. Memory Issues

Symptoms: Page gets slower over time, eventually crashes. Tab's memory in Task Manager keeps growing.

How to find:

DevTools → Memory panel → Take heap snapshots at different points → Compare for growing objects
DevTools → Performance Monitor (real-time) → Watch "JS heap size" and "DOM Nodes" over time
Chrome Task Manager (Shift+Esc) → Check if your tab's memory keeps growing

Common causes:
| Cause | What Happens | Fix |
|---|---|---|
| Detached DOM nodes | Removed elements still referenced in JS | Null references when removing elements |
| Event listeners not cleaned up | Each re-render adds new listeners without removing old ones | Use removeEventListener, or cleanup in React's useEffect return |
| Growing arrays/maps | Data accumulates without bounds | Set limits, use LRU eviction |
| Closures retaining large scope | Functions hold references to outer scope variables | Be mindful of what closures capture |
| setInterval without clearInterval | Timers keep running even after component unmounts | Always clear in cleanup/teardown |

6. Third-Party Script Issues

Symptoms: Everything seems optimized but Lighthouse still shows poor scores. Long Tasks you don't recognize.

How to find:

DevTools → Performance panel → Look at Long Tasks → Check if the source URL is a third-party domain
DevTools → Network panel → Filter by "Third-party" → Check sizes and timing
Lighthouse → "Reduce the impact of third-party code" audit
Use the web-vitals attribution build to see if third-party scripts cause poor INP/LCP
Chrome → chrome://inspect/#devices → Check Service Workers for third-party scripts

⬆ Back to Top

Fixing Performance Issues A Systematic Approach

Once you've identified the bottleneck, here's a structured approach to fixing each category:

Loading Performance Fixes (Improve LCP, TTFB, FCP)

Problem	Fix	Impact
High TTFB	Deploy CDN, enable edge caching, optimize backend queries, use streaming SSR	High
Large JS bundles	Code splitting (route-based), tree shaking, lazy imports for below-fold features	High
Large images	Compress, use WebP/AVIF, responsive `srcset`, proper sizing	High
Render-blocking CSS	Inline critical CSS (above-fold styles), defer rest with `media="print"` hack or async loading	High
Render-blocking JS	Add `defer` or `async` attribute, move scripts to bottom of body	Medium
No resource hints	`<link rel="preload">` for LCP image, `<link rel="preconnect">` for critical origins	Medium
Too many HTTP requests	Bundle small files, use HTTP/2 (automatic multiplexing), use image sprites or SVG sprites	Medium
No compression	Enable Brotli or Gzip on server/CDN	Medium
Redirect chains	Eliminate unnecessary 301/302 redirects	Low-Medium

Interaction Performance Fixes (Improve INP, TBT)

Problem	Fix	Impact
Long event handlers	Break into async chunks with `scheduler.yield()` or `setTimeout(fn, 0)`	High
Heavy computation	Move to Web Worker (runs off main thread)	High
Framework over-rendering	Memoize components (`React.memo`, `useMemo`), colocate state closer to where it's used	High
Large DOM	Virtualize long lists (react-window, TanStack Virtual), simplify nested structures	Medium
Layout thrashing	Batch DOM reads before writes, use `requestAnimationFrame` for DOM mutations	Medium
Frequent forced reflows	Avoid reading layout properties (`offsetHeight`, `getBoundingClientRect`) inside write loops	Medium
Third-party scripts	Load non-essential scripts with `defer`/`async`, use `Partytown` to run them in a Web Worker	Medium

Visual Stability Fixes (Improve CLS)

Problem	Fix	Impact
Images without dimensions	Always set `width`/`height` attributes or CSS `aspect-ratio`	High
Dynamic content insertion	Reserve space with placeholders, use `min-height` on containers	High
Font swapping	Use `font-display: optional` (no shift) or `size-adjust` to match fallback metrics	Medium
Injected ads/embeds	Reserve exact space with aspect-ratio containers	Medium
CSS animations using layout properties	Use `transform` and `opacity` only — they skip layout and paint phases	Medium
Late-loading above-fold content	Prioritize critical content loading, SSR/SSG	Medium

The Fix Priority Framework

When multiple issues exist, prioritize by impact × effort:

                        High Impact
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
         │   QUICK WINS     │   BIG PROJECTS   │
         │   (Do first)     │   (Plan & do)    │
         │                  │                  │
         │  • Preload LCP   │  • SSR/SSG       │
Low ─────│  • Image formats │  • Code splitting│───── High
Effort   │  • Add defer/    │  • Web Workers   │  Effort
         │    async         │  • Virtualization │
         │  • Set img dims  │  • Architecture  │
         │                  │    changes       │
         │   FILL-INS       │   AVOID          │
         │   (Do if time)   │   (Low ROI)      │
         │                  │                  │
         │  • DNS prefetch  │  • Rewriting in  │
         │  • Minor CSS     │    new framework │
         │    cleanup       │  • Over-          │
         │                  │    optimization  │
         └──────────────────┼──────────────────┘
                            │
                        Low Impact

⬆ Back to Top

Chrome DevTools and Available Tools

Chrome DevTools — Your Primary Performance Tool

Chrome DevTools has several panels specifically designed for performance investigation. Understanding which panel to use for which problem is crucial.

DevTools Panel	What It Shows	When to Use
Performance	Flame chart of main thread activity, Long Tasks, network waterfall, screenshots	Profiling specific interactions, diagnosing INP/TBT, finding expensive functions
Network	All network requests, waterfall timing, sizes, headers	Debugging loading issues, finding large assets, checking compression/caching
Lighthouse	Full page audit — Performance, Accessibility, SEO, Best Practices scores	Quick overall health check, getting actionable recommendations
Memory	Heap snapshots, allocation timelines, garbage collection	Debugging memory leaks, finding detached DOM nodes
Coverage	Shows how much of each CSS/JS file is actually used	Finding dead code to remove or defer
Rendering	Layout shift visualization, paint flashing, layer borders, FPS meter	Debugging CLS, finding unnecessary repaints, checking compositing
Application	Storage (Cache, IndexedDB, localStorage), Service Workers	Debugging caching strategies, checking storage usage
Performance Monitor	Real-time CPU, heap size, DOM nodes, event listeners, style recalculations	Quick live overview of performance health

How to Use the Performance Panel (Step by Step)

The Performance panel is the most powerful tool for diagnosing bottlenecks:

Open DevTools → Performance tab
Click Record (or Ctrl+E) → Perform the slow action → Stop recording
Read the flame chart top-down:
- Network row — shows when resources loaded
- Frames row — shows frame rate (red = dropped frames)
- Main row — the flame chart of all main thread activity
- Red corners on tasks = Long Tasks (> 50ms) — these are your targets
Click on a Long Task → See the call stack in the Bottom-Up / Call Tree tabs
Bottom-Up tab (sort by Self Time) → Find which functions consumed the most time
Summary tab → Shows time breakdown: Scripting, Rendering, Painting, Idle

What to look for in the flame chart:

Pattern	Meaning	Fix
Wide yellow blocks	Long JavaScript execution	Break up tasks, optimize algorithm, Web Worker
Wide purple blocks	Layout/style recalculation	Reduce DOM complexity, batch DOM writes
Wide green blocks	Paint/composite	Reduce painted area, promote to GPU layer
Many narrow purple + yellow alternating	Layout thrashing	Batch reads before writes
Large red-cornered blocks	Long Tasks blocking interactions	Yield to browser between chunks

How to Use the Network Panel Effectively

Technique	How	What It Reveals
Sort by Size	Click "Size" column header	Largest assets to optimize
Sort by Time	Click "Time" column header	Slowest requests
Check Waterfall	Look at the colored bars	Where time is spent (DNS, TLS, TTFB, download)
Use Throttling	Change "No throttling" to "Slow 3G" or "Fast 3G"	How your site feels on slow networks
Check Disable cache	Tick the checkbox	See first-visit experience
Filter by type	Click JS, CSS, Img, Font, etc.	Focus on specific resource types
Check gzip/Brotli	Compare "Size" vs "Content" columns	Is compression enabled?
Right-click → "Block request URL"	Block specific scripts	Test impact of removing third-party scripts

How to Use the Coverage Tab

Ctrl+Shift+P → Type "Show Coverage" → Enter
Click the reload button in the Coverage panel
See a list of all CSS/JS files with percentage used

Usage	What It Means	Action
< 30% used	Heavy dead code	Extract critical portion, lazy-load the rest
30-70% used	Some dead code	Consider code splitting per route
> 70% used	Mostly needed	Focus optimization elsewhere

How to Use the Rendering Tab for CLS

Ctrl+Shift+P → "Show Rendering"
Enable "Layout Shift Regions" — blue rectangles flash where layout shifts occur
Slowly scroll and interact with the page — watch for unexpected blue flashes
Enable "Paint Flashing" — green rectangles show what's being repainted (excessive repaints = performance drain)

The Full Toolkit Beyond Chrome DevTools

Tool	Type	Best For
Lighthouse (in DevTools or CLI)	Lab / Synthetic	Quick audit, actionable recommendations, scores
PageSpeed Insights	Lab + Field (CrUX)	Checking real-user data alongside lab results
WebPageTest	Lab (real devices)	Detailed waterfall analysis, filmstrip view, multi-step testing
Chrome UX Report (CrUX)	Field (28-day rolling)	Google's official real-user performance data per origin
Google Search Console	Field (CrUX)	SEO impact of Core Web Vitals, URL-level reports
`web-vitals` JS library	Field (RUM)	Custom RUM collection in your own analytics pipeline
Bundle analyzers (`webpack-bundle-analyzer`, `source-map-explorer`)	Build-time	Visualizing what's in your JS bundles, finding bloat
`size-limit` / `bundlesize`	CI/CD	Enforcing bundle size budgets in pull requests
Sentry Performance	RUM + Tracing	Real-user performance monitoring with error correlation
Datadog RUM / New Relic Browser	RUM	Enterprise-grade real-user monitoring with dashboards
DebugBear / SpeedCurve / Calibre	Synthetic + Field	Continuous monitoring with historical trends

Lab vs Field Data — Critical Distinction

Aspect	Lab Data	Field Data
Source	Simulated on controlled device	Real users in production
Tools	Lighthouse, WebPageTest, DevTools	CrUX, web-vitals, Datadog, Sentry
Reproducible	Yes — same conditions every run	No — varies per user
Covers real diversity	No — fixed device/network	Yes — all devices, networks, locations
When available	Anytime (dev, CI/CD)	Only after deployment with real traffic
Use for debugging	Yes — drill into specific issues	Harder — aggregated data
Use for Google ranking	No — Google uses field data only	Yes — CrUX field data drives ranking

Interview insight: Google uses field data (CrUX) for ranking, not lab data. Lighthouse can be 100/100 but if real users on slow phones have poor LCP, your ranking still suffers. That's why RUM matters.

⬆ Back to Top

Real User Monitoring (RUM) vs Synthetic Monitoring

Synthetic Monitoring

Runs automated tests against your site from controlled environments — specific devices, networks, and locations — on a scheduled basis or in CI/CD.

┌──────────────────────────────────────────────────┐
│              Synthetic Monitoring                  │
│                                                   │
│  Scheduled Agent ──→ Load Page ──→ Collect Metrics│
│  (headless browser)  (controlled    (LCP, FCP,    │
│                       conditions)    waterfall)    │
│                                                   │
│  ✅ Same device, network, location every time      │
│  ✅ Reproducible — great for regression detection  │
│  ❌ Doesn't represent real user diversity          │
└──────────────────────────────────────────────────┘

When it runs: Scheduled intervals (hourly/daily), CI/CD pipeline (every PR), or on-demand audits.

Real User Monitoring (RUM)

Collects performance data from actual users as they interact with your site. Every page load, every interaction, every error — from real devices, networks, and locations.

┌──────────────────────────────────────────────────┐
│           Real User Monitoring (RUM)              │
│                                                   │
│  Real User ──→ Loads Page ──→ Browser APIs        │
│  (varied device,  (real network   collect data    │
│   location,        conditions)    automatically)  │
│   browser)              │                         │
│                         ▼                         │
│               Beacon/Fetch ──→ Analytics Backend  │
│               (send data home)  (aggregate, dash) │
│                                                   │
│  ✅ Represents EVERY real user's experience        │
│  ✅ Catches long-tail issues (slow 3G in India)   │
│  ❌ Noisy data — requires percentile analysis     │
└──────────────────────────────────────────────────┘

Head-to-Head Comparison

Dimension	Synthetic	RUM
Data source	Simulated agents	Real users in production
Environment	Controlled (fixed device/network)	Diverse (every user's real conditions)
Consistency	Highly reproducible	Noisy, varies per user
Coverage	Only pages/flows you configure	Every page every user visits
Catches regressions	Proactively (before users see them)	Reactively (after deployment)
Third-party impact	May miss real behavior	Captures actual third-party impact
Geographic coverage	Limited test locations	Global (wherever users are)
Cost	Fixed per test run	Scales with traffic volume

When to Use Which

Scenario	Best Approach	Why
Pre-deployment regression check	Synthetic	Catch issues before users see them
Understand p75/p95 user experience	RUM	Real data from real users
Monitor uptime & availability	Synthetic	Runs even when no users are online
Debug by region/device/connection	RUM	Segment by real user dimensions
A/B test performance impact	RUM	Measure real-world impact
CI/CD quality gate	Synthetic	Automated, deterministic pass/fail
Catch long-tail issues (5% on slow 3G)	RUM	Won't show in synthetic at all

The Ideal Strategy — Use Both

Development ──→ CI/CD Pipeline ──→ Production

Lighthouse        Lighthouse CI       RUM (all users)
in DevTools       assertions          │
(manual)          (fail build if      ├─ Dashboards (p75/p95)
                   LCP > 2.5s)       ├─ Segment by region, device
                                      ├─ Alerts on regressions
                  Scheduled           └─ Correlate with errors
                  Synthetic
                  (hourly)

Key insight: Synthetic catches regressions early (before users see them). RUM shows the real impact on actual users. Together, they provide complete visibility.

How RUM Data Collection Works (Conceptual)

The core pattern for collecting real user performance data:

Instrument the page — add the web-vitals library (or equivalent) to every page
Collect metrics — CWV values fire when available (LCP on navigation, CLS on page hide, INP on page hide)
Buffer events — batch multiple metrics together to reduce network calls
Send via sendBeacon — navigator.sendBeacon() is the recommended method because it survives page unload (the user leaving the page). Regular fetch() might be cancelled.
Enrich with context — attach user agent, connection type (navigator.connection.effectiveType), device memory, geographic info (from server), and page URL
Aggregate on the backend — compute p50, p75, p95 per route, per device type, per connection speed, per region
Alert on threshold breaches — if p75 LCP crosses 2.5s, alert the team

Why sendBeacon? When a user clicks a link or closes the tab, the browser cancels pending fetch() requests. sendBeacon() is specifically designed to survive page transitions — it queues the request and the browser completes it even after navigation.

⬆ Back to Top

Error Tracking and Logging

Errors in production are inevitable. The difference between a minor issue and a catastrophe is how quickly you detect, diagnose, and resolve them.

Why Frontend Error Tracking Matters

90% of frontend errors go unreported by users — they just leave
JavaScript errors can completely break an SPA's functionality
Silent failures (API errors swallowed by catch blocks) go unnoticed without tracking
Cross-browser issues — an error in Safari might not reproduce in Chrome
Third-party scripts throw errors outside your control

Without error tracking, you're flying blind — relying on user complaints to discover issues that may have been happening for days.

Types of Frontend Errors

Error Type	Example	How It's Caught
Unhandled exceptions	`TypeError: Cannot read property 'x' of undefined`	`window.onerror` or `window.addEventListener('error')`
Unhandled promise rejections	Failed `fetch()` without `.catch()`	`window.addEventListener('unhandledrejection')`
Network errors	API returns 500, CORS failure, timeout	`fetch` wrapper or Axios interceptor
Resource load failures	CSS/JS/image 404	`window.addEventListener('error', fn, true)` (capture phase — resource errors don't bubble)
Framework/render errors	Error during React render crashes component tree	Error Boundaries (React), `Vue.config.errorHandler` (Vue)
Custom business logic	User can't checkout, payment fails	Manual error capture call in application logic

How Error Tracking Tools Work (Conceptual)

Error Occurs in Browser
         │
         ▼
┌──────────────────────┐
│  Error Tracking SDK  │
│  (e.g., Sentry)      │
│                       │
│  1. Capture the error │
│  2. Extract stack     │
│     trace             │
│  3. Collect context:  │
│     • Breadcrumbs     │
│       (user actions   │
│       leading up)     │
│     • Browser/OS/     │
│       device info     │
│     • User identity   │
│     • Current URL     │
│     • Console logs    │
│  4. Apply source maps │
│     (minified →       │
│      readable code)   │
│  5. Send to backend   │
└──────────┬────────────┘
           │
           ▼
┌──────────────────────┐
│  Error Tracking       │
│  Backend              │
│                       │
│  1. Deduplicate —     │
│     group similar     │
│     errors into one   │
│     "issue"           │
│  2. Link to release/  │
│     commit that       │
│     introduced it     │
│  3. Track frequency   │
│     and affected      │
│     user count        │
│  4. Send alerts       │
│     (Slack, PagerDuty)│
└──────────────────────┘

Key Error Tracking Concepts

Concept	What It Means	Why It Matters
Issue grouping	Thousands of the same `TypeError` get grouped into one "issue"	Without grouping, you'd see 10,000 separate errors instead of one issue affecting 10,000 users
Breadcrumbs	Automatic trail of user actions before the error (clicks, navigations, API calls, console logs)	Shows you what the user did that led to the error — like a flight recorder
Source maps	Map minified production code back to original source	Without them, stack traces show `a.js:1:42305` instead of `CartTotal.tsx:42`
Release tracking	Tag errors with the deployment version (`v1.2.3`)	Know exactly which deploy introduced the regression
Suspect commits	Tool identifies which Git commit likely caused the error	Go from "we have a bug" to "this commit changed the broken code" in seconds
Session replay	Video-like recording of the user's session (DOM changes, clicks, scrolls)	See exactly what the user experienced — invaluable for reproducing bugs
Sampling	Only capture a percentage of events (e.g., 10% of performance traces)	Control costs — you don't need 100% of identical errors

Error Tracking Tools Comparison

Feature	Sentry	LogRocket	Datadog
Primary focus	Error tracking & alerting	Session replay & debugging	Full-stack observability
Error grouping	Excellent	Basic	Good
Session replay	Yes (built-in)	Best-in-class	Yes
Source maps	Yes	No	Yes
Release tracking	Yes (suspect commits)	No	Yes
Performance (RUM)	Yes	Basic	Yes
Alerting	Advanced (Slack, PagerDuty, rules)	Basic	Advanced
Best for	Error detection & alerting	Understanding user experience	Full-stack teams

Practical recommendation: Use an error tracker (like Sentry) with session replay for error-specific sessions. The combination of "what broke" (stack trace) + "what the user saw" (replay) is the fastest path to diagnosing production issues.

Alert Tiers — The Traffic Light System

Not all errors are equal. Structure your alerts to avoid alert fatigue:

Tier	Condition	Alert Channel	Response
P0 — Critical	Error rate > 5% of sessions, payment/auth flow broken	PagerDuty → On-call engineer	< 15 min
P1 — High	New error in critical flow, > 100 events/hour	Slack #incidents	< 1 hour
P2 — Medium	New error in non-critical flow, < 100 events/hour	Slack #frontend-errors	< 1 day
P3 — Low	Cosmetic errors, third-party script errors	Weekly digest email	Next sprint

Structured Logging Principles

Effective frontend logging follows these principles:

Always include context — timestamp, URL, user ID, session ID, error severity
Use structured format — JSON objects, not string concatenation. Structured logs are searchable and aggregatable.
Include breadcrumbs — log navigation events, API calls, and user actions so you can reconstruct what happened
Sanitize sensitive data — never log passwords, tokens, credit card numbers, or PII
Use sendBeacon for delivery — survives page unload, won't block the main thread
Set severity levels — debug, info, warn, error, fatal — filter by level in production
Sample in production — you don't need 100% of logs. Sample info at 10%, capture all error and fatal.

⬆ Back to Top

Performance Budgets

A performance budget is an agreed-upon set of limits on metrics that affect user experience. Like a financial budget, it forces trade-off conversations and prevents the gradual performance degradation that happens in every growing project.

The Boiling Frog Problem

Without budgets, performance degrades invisibly:

Sprint 1:   Bundle = 150 KB   ← "Fast enough"
Sprint 5:   Bundle = 220 KB   ← "Just one more library..."
Sprint 10:  Bundle = 380 KB   ← "When did this get slow?"
Sprint 15:  Bundle = 550 KB   ← "We need a performance sprint"

With a budget (200 KB limit):
Sprint 5:   Bundle = 195 KB   ← ⚠️ Warning: approaching budget
Sprint 6:   PR adds 15 KB    ← ❌ BUILD FAILS — exceeds 200 KB
            → Developer must optimize or justify before merging

Types of Performance Budgets

Budget Type	What It Limits	Examples
Quantity-based	Number/size of resources	Max 170 KB JS (gzipped), max 50 KB CSS, max 5 third-party scripts
Timing-based	User-centric timing metrics	LCP ≤ 2.5s, FCP ≤ 1.5s, TTI ≤ 3.5s
Score-based	Audit tool scores	Lighthouse Performance ≥ 90, Accessibility ≥ 95

Recommended Budget Template

Category	Metric	Budget	Enforcement
Loading	LCP	≤ 2.5s	Lighthouse CI assertion
Interactivity	INP	≤ 200ms	RUM alerting
Stability	CLS	≤ 0.1	Lighthouse CI assertion
JS bundle	Main bundle (gzipped)	≤ 170 KB	CI size check tool
CSS	Total CSS (gzipped)	≤ 50 KB	CI size check tool
Images	Hero/LCP image	≤ 100 KB	CI check or manual review
Fonts	Total web fonts	≤ 75 KB, max 2 families	Manual review
Third-party	Total third-party JS	≤ 50 KB	Lighthouse audit
Total page	Total page weight	≤ 500 KB	Lighthouse CI
Lighthouse	Performance score	≥ 90	Lighthouse CI assertion

How to Enforce Performance Budgets

Level	Tool / Method	What It Does
IDE	"Import Cost" VS Code extension	Shows bundle size impact of every import inline as you code
Build	Webpack `performance.hints: 'error'` / Vite `chunkSizeWarningLimit`	Fails build if bundles exceed configured size
CI/CD	`bundlesize` or `size-limit`	Checks gzipped bundle sizes against budgets on every PR
CI/CD	Lighthouse CI assertions	Runs Lighthouse on every PR, fails if metrics exceed thresholds
Production	RUM alerting	Alerts when real-user p75 metrics cross budget thresholds

How to Set Performance Budgets

Benchmark current state — run Lighthouse and record your current metrics
Check competitors — benchmark 2-3 competitors for the same metrics
Set goals 20% better than current — or match Google's "Good" thresholds as minimum
Get team buy-in — budgets without enforcement are just wishes
Enforce in CI/CD — automated enforcement removes debates on every PR
Review quarterly — adjust budgets as the app evolves

⬆ Back to Top

The Three Pillars of Observability

Frontend observability goes beyond performance — it's about having complete visibility into what your application is doing in production.

The Three Pillars

Pillar	What It Captures	Frontend Examples
Metrics	Numeric measurements over time	LCP values, error rates, API latency, JS heap size
Logs	Discrete events with context	Errors, user actions, state changes, API responses
Traces	End-to-end request flow across services	User click → API call → backend processing → response → UI update

Why all three matter — they answer different questions:

Metrics tell you SOMETHING is wrong:
  → "Error rate spiked to 5% at 14:30"

Logs tell you WHAT went wrong:
  → "TypeError: Cannot read property 'price' of null in CartTotal.tsx:42"

Traces tell you WHERE in the chain it broke:
  → "User click → /api/cart (200 OK, but price=null) → CartTotal render → crash"

The Frontend Observability Pipeline

┌───────────────────────────────────────────────────────────┐
│                        Browser                             │
│                                                            │
│  Performance APIs ──→ web-vitals ──→ RUM Collector         │
│  Error events     ──→ Sentry SDK ──→ Error Tracker         │
│  User actions     ──→ Session Replay ──→ Replay Store      │
│  Custom events    ──→ Analytics SDK ──→ Event Stream        │
│                                                            │
└────────────────────────┬──────────────────────────────────┘
                         │ (sendBeacon / fetch)
                         ▼
┌───────────────────────────────────────────────────────────┐
│                   Ingestion Layer                          │
│            (API Gateway / Event Queue)                     │
└──────┬──────────────┬──────────────┬──────────────────────┘
       │              │              │
┌──────▼─────┐ ┌──────▼─────┐ ┌─────▼────────┐
│  Metrics   │ │   Logs     │ │   Traces     │
│  Store     │ │   Store    │ │   Store      │
└──────┬─────┘ └──────┬─────┘ └──────┬───────┘
       │              │              │
┌──────▼──────────────▼──────────────▼───────────────────────┐
│              Visualization & Alerting                       │
│                                                             │
│  • Dashboards (p75/p95 by route, device, region)           │
│  • Alerts (Slack/PagerDuty on threshold breaches)          │
│  • SLO tracking (99.5% of loads with LCP < 2.5s)          │
└─────────────────────────────────────────────────────────────┘

Distributed Tracing for Frontend

Distributed tracing connects a user interaction in the browser to all the backend services involved. It works by propagating a trace ID across service boundaries:

Browser (frontend span)
  └─→ trace-id header ──→ API Gateway (span)
      └─→ Order Service (span)
          └─→ Payment Service (span)
              └─→ Database query (span)

Full trace: Click → Validate → API → Payment → DB → Response → UI Update

This is how you answer "why was this checkout call slow for this user?" — you see the entire chain with timing for each step. Tools like Sentry Tracing, Datadog APM, and OpenTelemetry enable this.

⬆ Back to Top

Tradeoffs Gotchas and Common Pitfalls

Common Mistakes

Pitfall	What Goes Wrong	Prevention
Optimizing without measuring	Guessing where slowness is → wasting effort on wrong things	Always profile first — measure, then optimize
Measuring median instead of p75	Median hides long-tail issues that affect 25%+ of users	Google uses p75. Always track p75 and p95.
Lab-only testing	Lighthouse is 100 but real users on slow phones have poor experience	Combine Lighthouse (lab) with RUM (field)
No performance budget	Performance degrades gradually with every sprint	Set budgets, enforce in CI/CD
Alert fatigue	Too many alerts → team ignores all of them	Tier alerts (P0-P3), filter known noise
Not uploading source maps	Production stack traces are unreadable minified code	Upload source maps to your error tracker on every deploy
Over-sampling in RUM	Sending every metric from every user = high cost, no extra value	Sample performance traces at 10-20%, capture all errors at 100%
Ignoring third-party scripts	Your code is fast but GTM + ads + chat widgets add 500ms	Audit third-party impact regularly, use Lighthouse's third-party audit
Testing on developer machines only	Fast MacBook Pro ≠ budget Android phone on 3G	Use CPU/network throttling in DevTools, test on real devices
Chasing Lighthouse score	100/100 Lighthouse doesn't mean real users are happy	Lighthouse is a starting point. RUM is the truth.

Platform-Specific Considerations

Platform	Consideration
Mobile (general)	Always test with CPU throttling (4x–6x slowdown). Median phones are much slower than dev machines.
iOS Safari	No Background Sync, no Periodic Sync, limited Service Worker support. Test on real iOS devices — simulators don't accurately reflect performance.
Low-end Android	2-4 GB RAM, slow CPUs. These are your p75/p95 users. Budget Android phones represent the majority of global web traffic.
Slow networks	Always test on "Fast 3G" and "Slow 3G" throttling. Most of the world isn't on fast broadband.
High-DPI displays	Serving 2x/3x images without responsive sizing burns bandwidth and hurts LCP.

⬆ Back to Top

Interview Questions and Answers

Q1: What are Core Web Vitals and why do they matter?

A: Core Web Vitals are three Google-defined metrics that measure real-world user experience:

LCP (Largest Contentful Paint) — loading speed. Measures when the largest content element is rendered. Target: ≤ 2.5s.
INP (Interaction to Next Paint) — responsiveness. Measures how quickly the page responds to user interactions. Target: ≤ 200ms.
CLS (Cumulative Layout Shift) — visual stability. Measures unexpected layout shifts. Target: ≤ 0.1.

They matter because: (1) Google uses them as SEO ranking signals since June 2021, (2) they're measured at the 75th percentile of real user data, and (3) they directly correlate with user engagement metrics like bounce rate and conversion.

Q2: Why did INP replace FID?

A: FID (First Input Delay) only measured the delay of the first interaction, and it only captured input delay (not processing or presentation time). This meant:

It missed slow interactions later in the page lifecycle (e.g., a button that becomes slow after data loads)
A page could have great FID but terrible responsiveness on the 10th interaction
It didn't account for how long event handlers took to execute

INP measures all interactions throughout the entire page lifecycle and captures the full latency (input delay + processing time + presentation delay). It reports the worst interaction, giving a much more comprehensive picture of responsiveness.

Q3: How would you improve LCP on a slow-loading page?

A: I'd follow a systematic approach:

Check TTFB first — if the server takes 2s to respond, LCP can never be under 2s. Fix with CDN, caching, backend optimization.
Identify the LCP element — use DevTools Performance panel or web-vitals attribution to find which element is the LCP candidate.
Preload the LCP resource — if it's an image, add <link rel="preload"> and fetchpriority="high". If it's text, ensure fonts are preloaded.
Remove render-blocking resources — inline critical CSS, defer non-critical CSS/JS.
Never lazy-load the LCP element — loading="lazy" on the hero image is a common mistake.
Optimize the resource itself — compress images to WebP/AVIF, use responsive srcset, proper sizing.
Consider SSR/SSG — if the page is client-side rendered, the LCP has to wait for JS → fetch → render. Server rendering eliminates that chain.

Q4: How would you improve INP?

A: INP issues come from three phases — I'd diagnose which phase is the problem:

Input Delay is high → The main thread was busy when the user interacted. Break up Long Tasks, defer non-critical work, reduce third-party script impact.
Processing Time is high → Event handlers take too long. Optimize the handler, yield to the browser with scheduler.yield() between chunks, move heavy computation to a Web Worker.
Presentation Delay is high → The visual update after the handler is expensive. Reduce DOM complexity, avoid layout thrashing, simplify CSS selectors.

I'd use the web-vitals attribution build to identify which interaction is the slowest and which phase dominates, then profile that specific interaction in DevTools Performance panel.

Q5: How do you prevent CLS?

Always set dimensions on images/videos — use width/height attributes or CSS aspect-ratio so the browser reserves space before loading
Reserve space for dynamic content — ads, embeds, cookie banners should have min-height or aspect-ratio containers
Use font-display: optional for web fonts — prevents font swap layout shifts entirely (or use size-adjust to match fallback font metrics)
Use transform for animations — never animate top, left, width, height (layout triggers). transform and opacity skip layout and paint entirely.
SSR/SSG — avoid the client-side rendering pattern where skeleton → data → layout shift

Q6: What's the difference between RUM and Synthetic monitoring?

A: Synthetic monitoring runs automated tests from controlled environments (fixed device, network, location). It's reproducible, proactive (catches issues before users see them), and great for CI/CD quality gates. But it doesn't represent real user diversity.

RUM (Real User Monitoring) collects data from actual users in production — real devices, real networks, real locations. It catches long-tail issues (the 5% of users on slow 3G in India), captures third-party script impact, and shows actual user experience. But it's reactive (data only after deployment) and noisy (requires percentile analysis).

Best practice: Use both together. Synthetic in CI/CD to prevent regressions. RUM in production to validate real impact. Google uses field data (RUM/CrUX) for ranking, not lab data.

Q7: What is a performance budget and how do you enforce it?

A: A performance budget is an agreed-upon threshold for metrics that a page must not exceed — like a financial budget for performance. Examples: max 170 KB JS (gzipped), LCP ≤ 2.5s, Lighthouse Performance ≥ 90.

Without budgets, performance degrades gradually as features are added — the "boiling frog" problem.

Enforcement happens at multiple levels:

IDE level — "Import Cost" extension shows bundle size impact while coding
Build level — Webpack/Vite config fails the build on oversized bundles
CI/CD level — bundlesize or size-limit checks bundle sizes on every PR; Lighthouse CI asserts metric thresholds
Production level — RUM dashboards alert when p75 metrics cross budgets

The key is automated enforcement — budgets without CI/CD checks are just suggestions that get ignored.

Q8: How would you investigate a report that "the app is slow"?

A: I'd follow the investigation funnel:

Quantify "slow" — which metric is poor? Check RUM dashboards for LCP/INP/CLS p75. Is it a loading problem, interaction problem, or visual stability problem?
Segment the data — is it slow for all users or specific segments? Filter by device type, connection speed, geographic region, browser, OS. Often "slow" affects budget phones on 3G, not developer MacBooks.
Reproduce locally — try to reproduce with DevTools throttling (CPU 4x slowdown + Fast 3G). Record a Performance trace.
Analyze the trace — look for Long Tasks (red flags), heavy Layout/Style recalculations (purple), large network requests. Use Bottom-Up view to find expensive functions.
Check third-parties — are third-party scripts (analytics, ads, chat widgets) contributing to main thread blocking?
Prioritize fixes — use the impact × effort matrix. Quick wins first (preload LCP, add image dimensions, defer scripts), then bigger architectural changes (code splitting, SSR, Web Workers).
Validate the fix — deploy, monitor RUM for p75 improvement, confirm with users.

Q9: What are the three pillars of observability and how do they apply to frontend?

Metrics — numeric measurements over time. Frontend: Core Web Vitals (LCP, INP, CLS), error rates, API latency, JS heap size. Used for dashboards and alerting.
Logs — discrete events with context. Frontend: error stack traces with breadcrumbs, user action logs, API request/response details. Used for debugging specific issues.
Traces — end-to-end request flows across services. Frontend: tracing from user click → API call → backend processing → database → response → UI update, with timing at each step. Used for diagnosing latency in distributed systems.

Metrics tell you something is wrong. Logs tell you what went wrong. Traces tell you where in the chain it broke.

In practice: web-vitals + analytics for metrics, Sentry for logs + errors, Sentry Tracing or OpenTelemetry for traces.

Q10: How do you prevent cache from growing unbounded in a Service Worker?

A: Three approaches:

Entry limit — keep max N items per cache (e.g., 100 images). Evict oldest on overflow (FIFO/LRU).
TTL (Time-to-Live) — add a timestamp when caching. On read, check age and delete expired entries.
Version cleanup — on Service Worker activate, delete all caches not in the current version's allow-list.

Q11: What's the difference between lab data and field data?

A: Lab data (Lighthouse, WebPageTest) runs on a simulated device with fixed conditions. It's reproducible and great for debugging, but doesn't represent real user diversity. Field data (CrUX, RUM) is collected from actual users in production — real devices, networks, and locations. It's noisy but represents the truth.

Critical distinction: Google uses field data (CrUX) for SEO ranking, not lab data. You can score 100 on Lighthouse but still fail Google's assessment if real users on slow phones have poor metrics.

Q12: How would you set up error tracking for a production React app?

A: The core components:

Global error handlers — window.onerror for uncaught exceptions, unhandledrejection listener for promise rejections, capture-phase error listener for resource failures
React Error Boundaries — wrap critical routes/features with Error Boundaries to catch render errors and show fallback UI
Error tracking service (e.g., Sentry) — captures errors with full context: stack trace, breadcrumbs (user actions leading to error), user info, browser/OS, release version
Source maps — upload on every deploy so stack traces show original source, not minified code
Alert tiers — P0 (critical flows broken → PagerDuty), P1 (new error in important flow → Slack), P2-P3 (lower severity → digest)
Noise filtering — ignore known harmless errors (ResizeObserver loop limit exceeded, browser extension errors)
Session replay on errors — automatically record sessions where errors occur for easy reproduction

Q13: What tools would you use for a complete frontend performance monitoring strategy?

Stage	Tool	Purpose
Development	Chrome DevTools (Performance, Network, Lighthouse panels)	Profile and debug locally
IDE	Import Cost extension	See bundle size impact of imports
Build	Bundle analyzer (webpack-bundle-analyzer)	Visualize what's in the bundle
CI/CD	Lighthouse CI + `size-limit`/`bundlesize`	Automated regression prevention
Production — RUM	`web-vitals` library + analytics backend	Real user Core Web Vitals
Production — Errors	Sentry (with session replay)	Error tracking, alerting, debugging
Production — Field data	CrUX / PageSpeed Insights	Google's official field data
Ongoing	Scheduled synthetic tests (WebPageTest, DebugBear)	Baseline monitoring, competitor benchmarking

Q14: A page has good lab scores but poor field metrics. Why?

A: This is a very common scenario. Possible reasons:

User diversity — lab tests on fast machines; real users on budget phones with slow CPUs and 3G connections
Third-party scripts — lab might not fully load all third-party scripts (analytics, ads, chat widgets) that compete for main thread time in production
Geographic distance — lab test from a server close to CDN; real users far from CDN edge nodes experience high TTFB
Caching state — lab tests with warm cache; many real users are first-time visitors with cold cache
Dynamic content — lab tests might get different content (fewer ads, no personalization, no A/B test variants)
Long-tail interactions — lab tests the initial load; real users interact for minutes, hitting slow INP interactions later
Browser/OS diversity — lab uses latest Chrome; real users include older Safari, Firefox, webviews with different JS engines

Fix: Segment RUM data by device type, connection speed, and geography to find which user cohorts have poor experience, then optimize for those conditions.

For related topics, see companion articles: **Critical-Rendering-Path.md, **css-js-ui-optimization.md, **network-optimization.md, **image-optimization.md, and **Web_Worker_SharedWorker_and_Service_Worker.md.

⬆ Back to Top

More Details:

Get all articles related to system design
Hashtag: SystemDesignWithZeeshanAli

systemdesignwithzeeshanali

Git: https://github.com/ZeeshanAli-0704/front-end-system-design

⬆ Back to Top

Frontend System Design: Logging, Analytics & Feature Flags

ZeeshanAli-0704 — Sun, 15 Mar 2026 17:22:11 +0000

Logging, Analytics & Feature Flags — A Complete Frontend Guide

"If you can't observe it, you can't improve it. Logging, analytics, and feature flags form the operational backbone of every production frontend — they tell you what users do, when things break, and how to ship safely."

This guide covers analytics architecture (event tracking, funnel tracking), A/B testing infrastructure, feature flag systems (LaunchDarkly, Unleash), session replay & heatmaps, frontend error tracking & debugging, and where / how to store and ship logs at scale.

Analytics Architecture
A B Testing Infrastructure
Feature Flag Systems
Session Replay and Heatmaps
Frontend Error Tracking and Debugging
Frontend Logging Where to Hold Logs and How
Putting It All Together Unified Observability
Decision Matrix and Quick Reference
Key Interview Takeaways
Further Reading and Resources

⬆ Back to Top

Analytics Architecture

1.1 Why Frontend Analytics Matter

Analytics answer three critical questions in system design:

Question	What It Drives
What are users doing?	Product decisions, UX improvements
Where are users dropping off?	Funnel optimization, revenue impact
Is the new feature working?	A/B test evaluation, rollout decisions

Without analytics, every product decision is a guess. In a frontend system design interview, analytics is the feedback loop that validates your design choices.

1.2 Event Tracking — Design & Implementation

Event Taxonomy

A well-designed event taxonomy is the foundation of good analytics. Every event should answer: Who did what, where, and when?

┌──────────────────────────────────────────────────────┐
│                Event Schema                           │
│                                                       │
│  {                                                    │
│    "event":      "product_added_to_cart",             │
│    "timestamp":  "2026-03-13T10:30:00.000Z",          │
│    "userId":     "u_abc123",                          │
│    "sessionId":  "s_xyz789",                          │
│    "properties": {                                    │
│      "productId":    "SKU-1234",                      │
│      "productName":  "Wireless Headphones",           │
│      "price":        79.99,                           │
│      "currency":     "USD",                           │
│      "category":     "Electronics",                   │
│      "quantity":     1                                │
│    },                                                 │
│    "context": {                                       │
│      "page":         "/product/SKU-1234",             │
│      "referrer":     "/search?q=headphones",          │
│      "device":       "mobile",                        │
│      "browser":      "Chrome 120",                    │
│      "os":           "Android 14",                    │
│      "viewport":     "390x844",                       │
│      "network":      "4g",                            │
│      "locale":       "en-US"                          │
│    }                                                  │
│  }                                                    │
└──────────────────────────────────────────────────────┘

Naming Convention

Use a consistent object_action pattern:

✅ Good (consistent, greppable):
  page_viewed
  product_added_to_cart
  checkout_started
  payment_completed
  search_performed
  filter_applied

❌ Bad (inconsistent, hard to query):
  viewPage
  AddToCart
  user clicked checkout
  pay_done

Analytics Service Implementation

// src/analytics/analyticsService.ts

interface EventProperties {
  [key: string]: string | number | boolean | null;
}

interface EventContext {
  page: string;
  referrer: string;
  device: 'mobile' | 'tablet' | 'desktop';
  sessionId: string;
  userId?: string;
}

interface AnalyticsEvent {
  event: string;
  timestamp: string;
  properties: EventProperties;
  context: EventContext;
}

class AnalyticsService {
  private queue: AnalyticsEvent[] = [];
  private flushInterval: number;
  private maxQueueSize: number;
  private endpoint: string;

  constructor(config: {
    endpoint: string;
    flushIntervalMs?: number;
    maxQueueSize?: number;
  }) {
    this.endpoint = config.endpoint;
    this.flushInterval = config.flushIntervalMs ?? 5000;  // Flush every 5s
    this.maxQueueSize = config.maxQueueSize ?? 20;

    // Periodic flush
    setInterval(() => this.flush(), this.flushInterval);

    // Flush on page unload
    window.addEventListener('visibilitychange', () => {
      if (document.visibilityState === 'hidden') {
        this.flush();
      }
    });
  }

  track(event: string, properties: EventProperties = {}): void {
    const analyticsEvent: AnalyticsEvent = {
      event,
      timestamp: new Date().toISOString(),
      properties,
      context: this.getContext(),
    };

    this.queue.push(analyticsEvent);

    // Auto-flush if queue is full
    if (this.queue.length >= this.maxQueueSize) {
      this.flush();
    }
  }

  private async flush(): Promise<void> {
    if (this.queue.length === 0) return;

    const batch = [...this.queue];
    this.queue = [];

    try {
      // Use sendBeacon for reliability (survives page unload)
      const blob = new Blob([JSON.stringify(batch)], { type: 'application/json' });
      const sent = navigator.sendBeacon(this.endpoint, blob);

      if (!sent) {
        // Fallback to fetch with keepalive
        await fetch(this.endpoint, {
          method: 'POST',
          body: JSON.stringify(batch),
          headers: { 'Content-Type': 'application/json' },
          keepalive: true,
        });
      }
    } catch (error) {
      // Put events back in queue (with limit to prevent memory leak)
      this.queue = [...batch.slice(-this.maxQueueSize), ...this.queue];
      console.warn('Analytics flush failed, events re-queued', error);
    }
  }

  private getContext(): EventContext {
    return {
      page: window.location.pathname,
      referrer: document.referrer,
      device: this.getDeviceType(),
      sessionId: this.getSessionId(),
      userId: this.getUserId(),
    };
  }

  private getDeviceType(): 'mobile' | 'tablet' | 'desktop' {
    const w = window.innerWidth;
    if (w < 768) return 'mobile';
    if (w < 1024) return 'tablet';
    return 'desktop';
  }

  private getSessionId(): string {
    let sid = sessionStorage.getItem('analytics_sid');
    if (!sid) {
      sid = crypto.randomUUID();
      sessionStorage.setItem('analytics_sid', sid);
    }
    return sid;
  }

  private getUserId(): string | undefined {
    // Pull from your auth layer
    return (window as any).__AUTH_USER__?.id;
  }
}

// Singleton
export const analytics = new AnalyticsService({
  endpoint: '/api/analytics/events',
  flushIntervalMs: 5000,
  maxQueueSize: 20,
});

React Integration — Custom Hook

// src/analytics/useTrack.ts
import { useEffect, useCallback } from 'react';
import { analytics } from './analyticsService';

// Automatic page-view tracking
export function usePageView(pageName: string) {
  useEffect(() => {
    analytics.track('page_viewed', { page_name: pageName });
  }, [pageName]);
}

// Manual event tracking
export function useTrack() {
  return useCallback(
    (event: string, properties?: Record<string, any>) => {
      analytics.track(event, properties ?? {});
    },
    []
  );
}

// Usage in a component
function ProductPage({ product }) {
  usePageView('product_detail');
  const track = useTrack();

  const handleAddToCart = () => {
    track('product_added_to_cart', {
      productId: product.id,
      price: product.price,
    });
    addToCart(product);
  };

  return <button onClick={handleAddToCart}>Add to Cart</button>;
}

Declarative Tracking with Data Attributes

For large apps, declarative tracking reduces boilerplate:

// Attach tracking metadata to any element
<button
  data-track="product_added_to_cart"
  data-track-product-id={product.id}
  data-track-price={product.price}
  onClick={addToCart}
>
  Add to Cart
</button>

// Global click listener (set up once)
document.addEventListener('click', (e) => {
  const target = (e.target as HTMLElement).closest('[data-track]');
  if (!target) return;

  const event = target.getAttribute('data-track')!;
  const properties: Record<string, string> = {};

  // Collect all data-track-* attributes
  for (const attr of target.attributes) {
    if (attr.name.startsWith('data-track-') && attr.name !== 'data-track') {
      const key = attr.name.replace('data-track-', '').replace(/-/g, '_');
      properties[key] = attr.value;
    }
  }

  analytics.track(event, properties);
});

1.3 Funnel Tracking

A funnel tracks a sequence of user steps toward a goal (e.g., purchase). Drop-off at any step represents lost revenue or engagement.

E-Commerce Funnel Example

Step 1: page_viewed        (page: /products)         100% ████████████████████
Step 2: product_viewed     (productId: SKU-123)       60% ████████████
Step 3: product_added_to_cart                          25% █████
Step 4: checkout_started                               15% ███
Step 5: payment_info_entered                           12% ██▌
Step 6: order_completed                                 8% █▋

Drop-off analysis:
  Step 1→2: 40% lose interest (improve recommendations)
  Step 2→3: 58% don't add to cart (improve product page, pricing)
  Step 3→4: 40% abandon cart (add urgency, simplify UX)
  Step 4→5: 20% hesitate at payment (add trust signals, payment options)
  Step 5→6: 33% fail to complete (optimize payment flow, error handling)

Funnel Tracking Implementation

// src/analytics/funnel.ts

interface FunnelStep {
  name: string;
  event: string;
  timestamp?: number;
}

class FunnelTracker {
  private funnels: Map<string, FunnelStep[]> = new Map();

  /**
   * Define a funnel with named steps
   */
  defineFunnel(funnelName: string, steps: string[]) {
    this.funnels.set(
      funnelName,
      steps.map((event) => ({ name: event, event }))
    );
  }

  /**
   * Record a funnel step completion
   */
  recordStep(funnelName: string, eventName: string, properties: Record<string, any> = {}) {
    const funnel = this.funnels.get(funnelName);
    if (!funnel) return;

    const stepIndex = funnel.findIndex((s) => s.event === eventName);
    if (stepIndex === -1) return;

    analytics.track('funnel_step_completed', {
      funnel_name: funnelName,
      step_name: eventName,
      step_index: stepIndex,
      total_steps: funnel.length,
      ...properties,
    });
  }
}

// Usage
const funnelTracker = new FunnelTracker();

funnelTracker.defineFunnel('checkout', [
  'cart_viewed',
  'checkout_started',
  'shipping_entered',
  'payment_entered',
  'order_completed',
]);

// In your component:
funnelTracker.recordStep('checkout', 'checkout_started', { cartTotal: 149.99 });

1.4 Analytics Pipeline Architecture

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│   Browser     │    │   Ingestion   │    │   Stream      │    │   Storage     │
│               │    │   Layer       │    │   Processing  │    │   & Query     │
│ analytics.js  │───>│              │───>│              │───>│              │
│               │    │  API Gateway  │    │  Kafka /     │    │  ClickHouse  │
│ sendBeacon()  │    │  or Collector │    │  Kinesis     │    │  BigQuery    │
│ fetch()       │    │  Endpoint     │    │              │    │  Snowflake   │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
                                              │
                                              ▼
                                     ┌──────────────┐    ┌──────────────┐
                                     │  Real-time    │    │  Dashboard    │
                                     │  Aggregation  │───>│  & Alerts     │
                                     │  (Flink/      │    │  (Grafana,    │
                                     │   Spark)      │    │   Amplitude)  │
                                     └──────────────┘    └──────────────┘

Key design decisions:

Decision	Recommendation	Why
Transport	`navigator.sendBeacon` + `fetch` fallback	Survives page unload
Batching	Batch events, flush every 5s or 20 events	Reduces network requests
Schema	Strict typed schema with validation	Prevents garbage data
Sampling	100% for critical events, 10–50% for high-volume	Cost management
Buffering	Queue in memory; IndexedDB for offline	No data loss
Backend	Kafka/Kinesis → ClickHouse/BigQuery	Handles billions of events

1.5 Popular Analytics Platforms Compared

Platform	Type	Strengths	Weaknesses	Cost Model
Google Analytics 4	Full-stack	Free, deep Google integration	Complex setup, data sampling	Free / GA360 paid
Amplitude	Product analytics	Best funnel & cohort analysis	Expensive at scale	Event volume
Mixpanel	Product analytics	Great UX, real-time	Limited raw data access	Event volume
Segment	Customer Data Platform	Unified tracking, 300+ integrations	Expensive, adds latency	Monthly tracked users
PostHog	All-in-one (open-source)	Self-hostable, feature flags + analytics	Younger ecosystem	Events or self-host
Plausible	Privacy-first	No cookies, GDPR-compliant, simple	Limited features	Pageviews
Custom (ClickHouse)	Build-your-own	Full control, no vendor lock-in	Engineering cost	Infrastructure

⬆ Back to Top

A B Testing Infrastructure

2.1 How A/B Tests Work on the Frontend

User visits page
      │
      ▼
┌─────────────────────┐
│ Experiment SDK       │
│ evaluates user into  │
│ variant              │
│                      │
│ hash(userId +        │
│   experimentId)      │
│   % bucketCount      │──── Deterministic: same user always
│                      │     gets same variant
│ → Variant A (50%)    │
│ → Variant B (50%)    │
└──────┬──────────────┘
       │
       ▼
┌──────────────────┐        ┌──────────────────┐
│ Variant A        │        │ Variant B        │
│ (Control)        │        │ (Treatment)      │
│                  │        │                  │
│ Blue "Buy" btn   │        │ Green "Buy" btn  │
│                  │        │                  │
│ Track: exposure  │        │ Track: exposure  │
│ Track: clicks    │        │ Track: clicks    │
│ Track: purchase  │        │ Track: purchase  │
└──────────────────┘        └──────────────────┘
       │                           │
       └─────────┬─────────────────┘
                 ▼
      ┌──────────────────┐
      │ Analytics         │
      │                   │
      │ Compare metrics   │
      │ per variant with  │
      │ statistical       │
      │ significance      │
      └──────────────────┘

2.2 Client-Side vs Server-Side A/B Testing

Aspect	Client-Side	Server-Side
Where it runs	Browser (JS SDK)	Server / Edge / CDN
Flicker risk	Yes — content shifts after JS loads	No — correct variant served
Performance	Extra JS + SDK overhead	Zero client-side cost
Personalization	Limited (must wait for JS)	Full (server has all user data)
Ease of setup	Easy (drop-in SDK)	Requires backend integration
SEO impact	Can cause CLS issues	None
Examples	Google Optimize, Optimizely (client)	LaunchDarkly, Unleash, Statsig

Modern Trend: Server-side / Edge-side evaluation with a lightweight client SDK that receives the decision — no flicker, no performance cost.

2.3 Implementation Patterns

Pattern 1: Feature-Flag-Driven A/B Tests

The cleanest approach — A/B tests are just feature flags with analytics:

// Uses the same feature flag system (Section 3)
import { useFeatureFlag } from '@org/feature-flags';
import { analytics } from '@org/analytics';
import { useEffect } from 'react';

function CheckoutButton() {
  const variant = useFeatureFlag('checkout_button_experiment');
  // Returns: 'control' | 'green_button' | 'urgency_copy'

  // Track exposure (user saw the experiment)
  useEffect(() => {
    analytics.track('experiment_exposure', {
      experiment: 'checkout_button_experiment',
      variant,
    });
  }, [variant]);

  // Track conversion
  const handleClick = () => {
    analytics.track('experiment_conversion', {
      experiment: 'checkout_button_experiment',
      variant,
      action: 'checkout_clicked',
    });
    proceedToCheckout();
  };

  switch (variant) {
    case 'green_button':
      return <button className="btn-green" onClick={handleClick}>Buy Now</button>;
    case 'urgency_copy':
      return <button className="btn-blue" onClick={handleClick}>Buy Now — Only 3 Left!</button>;
    default:
      return <button className="btn-blue" onClick={handleClick}>Buy Now</button>;
  }
}

Pattern 2: Component-Level Experiments

// src/experiments/Experiment.tsx
interface ExperimentProps {
  name: string;
  children: Record<string, React.ReactNode>;  // variant → component
}

function Experiment({ name, children }: ExperimentProps) {
  const variant = useFeatureFlag(name);

  useEffect(() => {
    analytics.track('experiment_exposure', { experiment: name, variant });
  }, [name, variant]);

  return <>{children[variant] ?? children['control']}</>;
}

// Usage
<Experiment name="hero_redesign">
  {{
    control: <HeroV1 />,
    variant_a: <HeroV2WithVideo />,
    variant_b: <HeroV3Minimal />,
  }}
</Experiment>

2.4 Avoiding Flicker (FOOC)

Flash of Original Content (FOOC): User briefly sees the control variant before the experiment SDK assigns them to the treatment.

Timeline WITHOUT anti-flicker:
  0ms: HTML loads → shows control
  200ms: Experiment SDK loads
  300ms: SDK assigns variant B
  301ms: Page re-renders with variant B  ← USER SEES FLICKER ⚠️

Timeline WITH anti-flicker:
  0ms: HTML loads → body is hidden (opacity: 0)
  200ms: Experiment SDK loads
  300ms: SDK assigns variant, reveals body
  301ms: User sees correct variant from the start  ✅

Anti-flicker snippet (in <head>):

<script>
  // Hide body until experiment SDK resolves (max 2 seconds)
  document.documentElement.style.opacity = '0';
  setTimeout(() => {
    document.documentElement.style.opacity = '1';
  }, 2000); // Safety timeout — never block rendering forever
</script>

⚠️ Better approach: Use server-side or edge-side evaluation so the correct variant is served from the start — zero flicker, zero CLS impact.

2.5 Statistical Considerations

Concept	What It Means	Implication
Sample size	Enough users to detect a meaningful difference	Don't call experiments early
Statistical significance	p-value < 0.05 (95% confidence)	Avoid false positives
Minimum Detectable Effect (MDE)	Smallest improvement worth detecting	Drives sample size calculation
Duration	Run for at least 1–2 full business cycles (weeks)	Captures weekday/weekend variance
Multiple comparisons	Testing 5 variants inflates false positive rate	Use Bonferroni correction
Novelty effect	Users interact more with "new" things	Wait for effect to stabilize

⬆ Back to Top

Feature Flag Systems

3.1 What Are Feature Flags?

Feature flags (also called feature toggles) are runtime switches that control which features are visible/enabled without deploying new code.

Traditional deploy:
  Code change → Build → Deploy → Feature is live for ALL users

With feature flags:
  Code change → Build → Deploy → Feature is OFF by default
                                       │
                                       ▼
                              Enable for 5% of users (canary)
                              Enable for internal team (dogfood)
                              Enable for beta users
                              Enable for 100% (full rollout)
                              Instantly disable if buggy (kill switch)

3.2 Types of Feature Flags

Type	Lifetime	Purpose	Example
Release flag	Days–Weeks	Gate unfinished features	`new_checkout_flow`
Experiment flag	Weeks	A/B tests	`hero_redesign_experiment`
Ops flag	Permanent	Kill switches, load shedding	`disable_recommendations`
Permission flag	Permanent	Entitlement/plan gating	`premium_feature_export`

3.3 Feature Flag Architecture

┌───────────────────────────────────────────────────────────────────┐
│                    Feature Flag System                             │
│                                                                    │
│  ┌──────────────┐    ┌──────────────────┐    ┌─────────────────┐  │
│  │  Admin UI /   │    │  Flag Evaluation  │    │  Client SDKs    │  │
│  │  Dashboard    │───>│  Service (API)    │───>│  (JS, React,    │  │
│  │              │    │                   │    │   Node, etc.)   │  │
│  │ Create flags  │    │ Rules engine:     │    │                 │  │
│  │ Set targeting │    │ - User segments  │    │ Evaluates flags  │  │
│  │ Define rules  │    │ - % rollout      │    │ locally or via   │  │
│  │ Kill switch   │    │ - Env (prod/stg) │    │ SSE stream       │  │
│  └──────────────┘    │ - Custom attrs   │    └─────────────────┘  │
│                       └──────────────────┘                         │
│                              │                                     │
│                              ▼                                     │
│                    ┌──────────────────┐                            │
│                    │  Flag Store       │                            │
│                    │  (Redis / DB)     │                            │
│                    │                   │                            │
│                    │  Caches evaluated │                            │
│                    │  flag values for  │                            │
│                    │  fast reads       │                            │
│                    └──────────────────┘                            │
└───────────────────────────────────────────────────────────────────┘

Evaluation Flow:

1. App starts → SDK fetches all flag definitions (bootstrap)
2. SDK caches flags in memory
3. SDK opens SSE / WebSocket connection for real-time updates
4. Component calls useFeatureFlag('new_checkout')
5. SDK evaluates locally:
   - Is user in target segment? (e.g., country === 'US')
   - Does user fall within rollout percentage?
   - Is the flag enabled for this environment?
6. Returns boolean / string variant
7. On flag change → SSE pushes update → SDK re-evaluates → component re-renders

3.4 LaunchDarkly — Deep Dive

LaunchDarkly is the market-leading feature flag platform. Here's how it works:

Architecture

┌───────────────┐     ┌──────────────────────┐     ┌────────────────┐
│  LaunchDarkly  │     │  Streaming edge       │     │  Your App       │
│  Dashboard     │────>│  (LD Relay / CDN)     │────>│  (LD SDK)       │
│                │     │                       │     │                 │
│  Flag config   │     │  SSE stream delivers  │     │  Local eval,    │
│  is pushed to  │     │  flag changes in      │     │  no latency     │
│  edge in ~200ms│     │  real-time             │     │  per flag check │
└───────────────┘     └──────────────────────┘     └────────────────┘

React SDK Integration

// src/index.tsx
import { LDProvider } from 'launchdarkly-react-client-sdk';

const ldConfig = {
  clientSideID: 'YOUR_CLIENT_SIDE_ID',
  context: {
    kind: 'user',
    key: 'user-123',
    name: 'Jane Doe',
    email: 'jane@example.com',
    custom: {
      plan: 'premium',
      company: 'Acme Inc',
      country: 'US',
    },
  },
};

function Root() {
  return (
    <LDProvider {...ldConfig}>
      <App />
    </LDProvider>
  );
}

// src/components/Feature.tsx
import { useFlags, useLDClient } from 'launchdarkly-react-client-sdk';

function DashboardPage() {
  const { newDashboardLayout, enableExport, darkModeExperiment } = useFlags();
  const ldClient = useLDClient();

  // Track custom event for experiments
  const handleExport = () => {
    ldClient?.track('export_clicked', { format: 'csv' });
    exportData();
  };

  return (
    <div className={darkModeExperiment === 'dark' ? 'dark-theme' : 'light-theme'}>
      {newDashboardLayout ? <DashboardV2 /> : <DashboardV1 />}
      {enableExport && <button onClick={handleExport}>Export</button>}
    </div>
  );
}

Targeting Rules Examples

Flag: new_checkout_flow
  Default: false

  Rules (evaluated top-to-bottom):
    1. IF user.email ENDS WITH "@mycompany.com"  →  true   (internal dogfood)
    2. IF user.plan == "beta"                     →  true   (beta testers)
    3. IF user.country IN ["US", "CA"]            →  true (25% rollout)
    4. ELSE                                       →  false  (everyone else)

3.5 Unleash — Open-Source Alternative

Unleash is the leading open-source feature flag system. Self-hostable, API-compatible, and great for teams that want full control.

Setup

# Docker Compose for self-hosting
docker compose up -d  # Runs Unleash server + PostgreSQL

# Or use hosted: Unleash Cloud

React Integration

// src/index.tsx
import { FlagProvider } from '@unleash/proxy-client-react';

const config = {
  url: 'https://your-unleash-proxy.com/api/frontend',
  clientKey: 'your-proxy-client-key',
  refreshInterval: 15,  // seconds
  appName: 'my-web-app',
  context: {
    userId: 'user-123',
    properties: { plan: 'premium', country: 'US' },
  },
};

function Root() {
  return (
    <FlagProvider config={config}>
      <App />
    </FlagProvider>
  );
}

// src/components/Feature.tsx
import { useFlag, useVariant } from '@unleash/proxy-client-react';

function ProductPage() {
  const isNewLayout = useFlag('new_product_layout');
  const priceVariant = useVariant('price_experiment');

  return (
    <div>
      {isNewLayout ? <ProductLayoutV2 /> : <ProductLayoutV1 />}
      {priceVariant.name === 'show_discount' && <DiscountBadge />}
    </div>
  );
}

3.6 LaunchDarkly vs Unleash vs Custom

Aspect	LaunchDarkly	Unleash	Custom (DIY)
Hosting	SaaS only	Self-host or Cloud	Self-host
Cost	$$$$ (per seat + MAU)	Free (OSS) / $$ (Cloud)	Engineering time
Real-time updates	SSE (< 200ms)	Polling (15s default)	Build it
Targeting rules	Rich UI, segments, % rollout	Good, extensible	Build it
A/B experiments	Built-in (Experimentation add-on)	Via Unleash Analytics	Build it
SDKs	25+ (best-in-class)	15+ (good quality)	Build it
Audit log	Full	Full	Build it
TypeScript types	Auto-generated	Manual	Manual
Best for	Enterprise, large teams	Mid-size, privacy-conscious	Simple needs

3.7 Best Practices & Flag Hygiene

┌──────────────────────────────────────────────────────────┐
│                  Feature Flag Lifecycle                    │
│                                                           │
│  CREATE   →   DEVELOP   →   ROLLOUT   →   CLEANUP        │
│  Name it      Gate code     Canary (5%)   Remove flag     │
│  Document     Write tests   Expand (25%)  Remove dead     │
│  Set owner    Ship behind   Full (100%)   code paths      │
│               flag          Monitor       Archive in DB   │
└──────────────────────────────────────────────────────────┘

Rules:

Rule	Why
Every flag has an owner	Someone is responsible for cleanup
Set expiry dates	Flags lingering for months become tech debt
Limit active flags	> 50 active flags = cognitive overload
Test both paths	Flag on AND flag off must work
No nested flags	`if (flagA && flagB && !flagC)` → unmaintainable
Monitor flag usage	Alert on stale flags (not evaluated in 30 days)
Use naming conventions	`release_`, `experiment_`, `ops_`, `perm_`

// Bad: flag cleanup debt
if (useFeatureFlag('new_checkout_v2')) {
  if (useFeatureFlag('checkout_experiment_q3')) {
    if (!useFeatureFlag('disable_stripe_v4')) {
      return <CheckoutV2WithStripeV5 />;
    }
  }
}

// Good: single flag, clean code
const checkoutVersion = useFeatureFlag('checkout_version'); // 'v1' | 'v2' | 'v3'
return <Checkout version={checkoutVersion} />;

⬆ Back to Top

Session Replay and Heatmaps

4.1 How Session Replay Works

Session replay tools record DOM mutations, mouse movements, scroll events, and network requests to recreate a user's session as a video — without actually recording a video.

Browser (User's session)
  │
  ├── MutationObserver → captures DOM changes
  ├── mousemove / click / scroll → captures interactions
  ├── Performance Observer → captures resource timing
  ├── Console proxy → captures console.log / console.error
  ├── Network proxy → captures XHR / fetch requests & responses
  │
  ▼
┌──────────────────────────┐
│  Serialized Event Stream  │
│                           │
│  [                        │
│    { type: 'snapshot',    │   // Initial full DOM snapshot
│      data: <DOM tree> },  │
│    { type: 'mutation',    │   // Incremental DOM change
│      data: <diff> },      │
│    { type: 'mouse',       │   // Mouse position
│      data: {x, y} },      │
│    { type: 'input',       │   // User typed (masked)
│      data: '****' },      │
│    ...                    │
│  ]                        │
└──────────┬───────────────┘
           │
           ▼  Compressed & batched
┌──────────────────────┐
│  Replay Backend       │
│  (stores as events,   │
│   replays by          │
│   re-applying events  │
│   to a virtual DOM)   │
└──────────────────────┘

Key Library: rrweb — the open-source engine behind most session replay tools.

// Using rrweb directly
import { record } from 'rrweb';

const events: any[] = [];

const stopRecording = record({
  emit(event) {
    events.push(event);

    // Batch and send every 50 events
    if (events.length >= 50) {
      sendToBackend(events.splice(0));
    }
  },
  maskAllInputs: true,            // Mask password, email, etc.
  blockSelector: '.pii-block',    // Don't capture these elements
  maskTextSelector: '.pii-mask',  // Replace text with ***
});

4.2 Heatmaps — Click, Scroll, Move

Type	What It Shows	Use Case
Click heatmap	Where users click (hot = frequent)	Find dead clicks, misclicked areas
Scroll heatmap	How far users scroll (% visible)	Determine fold line, content priority
Move heatmap	Where mouse hovers (≈ attention)	Eye-tracking proxy
Rage click map	Repeated rapid clicks on same element	Find broken UI, frustration

Click Heatmap Visualization:

  ┌────────────────────────────────┐
  │  HEADER / NAV BAR              │  🔴🔴🔴 (nav links heavily clicked)
  ├────────────────────────────────┤
  │                                │
  │  Hero Banner                   │  🟡 (moderate clicks)
  │  [CTA Button]                  │  🔴🔴🔴🔴 (highest clicks)
  │                                │
  ├────────────────────────────────┤
  │                                │
  │  Product Grid                  │  🟡🟡 (moderate)
  │  Card 1  Card 2  Card 3       │
  │                                │
  ├────────────────────────────────┤
  │                                │
  │  Footer                        │  🔵 (few clicks — most users
  │                                │       don't scroll this far)
  └────────────────────────────────┘

  Scroll depth:  ███████████████  100% (top)
                 ████████████     80%
                 █████████        60%
                 ██████           40%
                 ███              20%  (only 20% reach footer)

4.3 Privacy & PII Concerns

Risk	Mitigation
Passwords / CC numbers	`maskAllInputs: true` — replaces with `***`
Sensitive text	Apply `.pii-mask` CSS class or selector-based masking
PII in URLs	Strip query params before recording
GDPR / CCPA	Get user consent before recording; honor Do Not Track
Data retention	Auto-delete replays after 30–90 days
Employee data	Exclude internal users from recording

4.4 Tools Compared

Tool	Session Replay	Heatmaps	Analytics	Error Tracking	Pricing
Hotjar	✅	✅ Click, Scroll, Move	Basic	❌	Free tier / $$
FullStory	✅ (best)	✅	✅	✅	$$$$
LogRocket	✅	❌	✅	✅ (Redux, network)	$$$
PostHog	✅	✅	✅	❌	Free (self-host) / $$
Microsoft Clarity	✅	✅ Click, Scroll	Basic	❌	Free
Mouseflow	✅	✅ Full suite	✅ Funnels	❌	$$
Heap	✅	❌	✅ (auto-capture)	❌	$$$

💡 Microsoft Clarity is a great free option for session replay + heatmaps. It uses rrweb under the hood and integrates with Google Analytics.

⬆ Back to Top

Frontend Error Tracking and Debugging

5.1 Types of Frontend Errors

┌──────────────────────────────────────────────────────────────┐
│                  Frontend Error Taxonomy                      │
│                                                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │ JavaScript       │  │ Network          │  │ Resource     │ │
│  │ Runtime Errors   │  │ Errors           │  │ Errors       │ │
│  │                  │  │                  │  │              │ │
│  │ TypeError        │  │ API 4xx/5xx      │  │ Image 404    │ │
│  │ ReferenceError   │  │ Timeout          │  │ Script fail  │ │
│  │ RangeError       │  │ Network offline  │  │ CSS fail     │ │
│  │ SyntaxError      │  │ CORS blocked     │  │ Font fail    │ │
│  │ Unhandled        │  │ SSL errors       │  │ Chunk load   │ │
│  │ Promise reject   │  │                  │  │ error        │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
│                                                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │ Framework        │  │ Performance      │  │ User         │ │
│  │ Errors           │  │ Errors           │  │ Errors       │ │
│  │                  │  │                  │  │              │ │
│  │ React render     │  │ Memory leak      │  │ Rage clicks  │ │
│  │ error            │  │ Long task (>50ms)│  │ Dead clicks  │ │
│  │ Hydration        │  │ Layout thrashing │  │ Form errors  │ │
│  │ mismatch         │  │ Jank (dropped    │  │ Navigation   │ │
│  │ State mismatch   │  │ frames)          │  │ frustration │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└──────────────────────────────────────────────────────────────┘

5.2 Capturing Errors — The Complete Picture

Global Error Handlers

// src/errorTracking/globalHandlers.ts

// 1. Uncaught JS errors
window.addEventListener('error', (event) => {
  // event.error    → Error object
  // event.message  → Error message
  // event.filename → Script URL
  // event.lineno   → Line number
  // event.colno    → Column number

  reportError({
    type: 'uncaught_error',
    message: event.message,
    stack: event.error?.stack,
    source: event.filename,
    line: event.lineno,
    column: event.colno,
  });
});

// 2. Unhandled Promise rejections
window.addEventListener('unhandledrejection', (event) => {
  reportError({
    type: 'unhandled_promise_rejection',
    message: event.reason?.message || String(event.reason),
    stack: event.reason?.stack,
  });
});

// 3. Resource loading errors (images, scripts, stylesheets)
window.addEventListener('error', (event) => {
  const target = event.target as HTMLElement;
  if (target.tagName) {
    reportError({
      type: 'resource_error',
      tag: target.tagName.toLowerCase(),
      src: (target as HTMLImageElement).src || (target as HTMLScriptElement).src,
    });
  }
}, true);  // ← Must use capture phase for resource errors

// 4. Console error proxy
const originalConsoleError = console.error;
console.error = (...args) => {
  reportError({
    type: 'console_error',
    message: args.map(String).join(' '),
  });
  originalConsoleError.apply(console, args);
};

Network Error Tracking

// Intercept fetch to track API errors
const originalFetch = window.fetch;

window.fetch = async (...args) => {
  const startTime = performance.now();
  const [url, options] = args;

  try {
    const response = await originalFetch(...args);
    const duration = performance.now() - startTime;

    if (!response.ok) {
      reportError({
        type: 'api_error',
        url: typeof url === 'string' ? url : url.toString(),
        method: options?.method || 'GET',
        status: response.status,
        statusText: response.statusText,
        duration,
      });
    }

    // Track slow APIs
    if (duration > 3000) {
      reportError({
        type: 'slow_api',
        url: typeof url === 'string' ? url : url.toString(),
        duration,
      });
    }

    return response;
  } catch (error) {
    reportError({
      type: 'network_error',
      url: typeof url === 'string' ? url : url.toString(),
      message: (error as Error).message,
    });
    throw error;
  }
};

5.3 Error Tracking with Sentry

Sentry is the most popular frontend error tracking platform.

Setup

// src/index.ts
import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',

  // Release & environment
  release: 'my-app@2.3.1',
  environment: process.env.NODE_ENV,

  // Performance monitoring
  integrations: [
    Sentry.browserTracingIntegration(),
    Sentry.replayIntegration({
      maskAllText: false,
      blockAllMedia: false,
    }),
  ],

  // Sample rates
  tracesSampleRate: 0.1,        // 10% of transactions for perf monitoring
  replaysSessionSampleRate: 0.1, // 10% of sessions get replay
  replaysOnErrorSampleRate: 1.0, // 100% of error sessions get replay

  // Filter noise
  ignoreErrors: [
    'ResizeObserver loop limit exceeded',
    'Non-Error promise rejection captured',
    /^Loading chunk \d+ failed/,
  ],

  // PII protection
  beforeSend(event) {
    // Strip PII from error events
    if (event.request?.url) {
      event.request.url = stripSensitiveParams(event.request.url);
    }
    return event;
  },

  // Breadcrumbs — trail of events leading to an error
  beforeBreadcrumb(breadcrumb) {
    // Don't track breadcrumbs from analytics scripts
    if (breadcrumb.category === 'xhr' &&
        breadcrumb.data?.url?.includes('analytics')) {
      return null;
    }
    return breadcrumb;
  },
});

React Error Boundary Integration

import * as Sentry from '@sentry/react';

// Sentry-powered Error Boundary
const SentryErrorBoundary = Sentry.withErrorBoundary(App, {
  fallback: ({ error, resetError }) => (
    <div className="error-page">
      <h1>Something went wrong</h1>
      <p>Our team has been notified. Please try again.</p>
      <button onClick={resetError}>Try Again</button>
    </div>
  ),
  showDialog: true,  // Show Sentry feedback dialog
});

// Or wrap specific components
function ProductPage() {
  return (
    <Sentry.ErrorBoundary fallback={<ProductErrorFallback />}>
      <ProductDetail />
    </Sentry.ErrorBoundary>
  );
}

Manual Error Capture with Context

// Capture errors with rich context
try {
  await processPayment(order);
} catch (error) {
  Sentry.withScope((scope) => {
    // Add structured context
    scope.setTag('payment_provider', 'stripe');
    scope.setTag('order_type', 'subscription');
    scope.setLevel('critical');

    scope.setContext('order', {
      orderId: order.id,
      amount: order.total,
      currency: order.currency,
      items: order.items.length,
    });

    scope.setContext('user_journey', {
      steps_completed: ['cart', 'shipping', 'payment'],
      time_in_checkout: '3m 22s',
    });

    // Set user (without PII)
    scope.setUser({
      id: user.id,
      segment: user.plan,  // Not email — PII
    });

    Sentry.captureException(error);
  });
}

Sentry — What Gets Captured Automatically

Data	Source	How
Stack trace	`window.onerror`	Auto (with source maps)
Breadcrumbs	Console, clicks, navigation, XHR	Auto
User interactions	Clicks, inputs, navigation	Auto (breadcrumb trail)
HTTP requests	Fetch/XHR	Auto (BrowserTracing)
Performance spans	Page load, route change	Auto (BrowserTracing)
Session replay	DOM mutations, mouse, scroll	Auto (Replay integration)
Device info	User-Agent, viewport, OS	Auto
Release info	`release` config	Manual (set in CI)

5.4 Source Maps for Production Debugging

Minified production code produces useless stack traces:

// Minified error (useless):
TypeError: Cannot read property 'a' of undefined
  at e.value (main.abc123.js:1:24589)

// With source maps (useful):
TypeError: Cannot read property 'name' of undefined
  at ProductCard.render (src/components/ProductCard.tsx:42:18)

Source Map Strategy

┌──────────────────────────────────────────────────────────┐
│                Source Map Strategies                       │
│                                                           │
│  Option 1: Upload to Sentry (RECOMMENDED)                 │
│  ─────────────────────────────────────────                │
│  • Source maps uploaded during CI/CD build                 │
│  • NOT served to browsers (private)                       │
│  • Sentry un-minifies stack traces server-side            │
│  • No performance or security impact                      │
│                                                           │
│  Option 2: Hidden source maps                             │
│  ─────────────────────────────────────────                │
│  • devtool: 'hidden-source-map' in Webpack                │
│  • .map files generated but no //# sourceMappingURL       │
│  • Deployed to restricted storage (S3 with IAM)           │
│  • Error tracking service fetches them server-side        │
│                                                           │
│  Option 3: Source maps behind auth (NOT RECOMMENDED)      │
│  ─────────────────────────────────────────                │
│  • Anyone with Chrome DevTools can see your source code   │
│                                                           │
│  ❌ Option 4: No source maps in prod                      │
│  • Debugging is impossible                                │
│  • NEVER do this                                          │
└──────────────────────────────────────────────────────────┘

Uploading Source Maps to Sentry (CI/CD)

# .github/workflows/deploy.yml
- name: Build
  run: npm run build
  env:
    GENERATE_SOURCEMAP: true

- name: Upload Source Maps to Sentry
  run: |
    npx @sentry/cli releases new ${{ github.sha }}
    npx @sentry/cli releases files ${{ github.sha }} \
      upload-sourcemaps ./build/static/js \
      --url-prefix '~/static/js'
    npx @sentry/cli releases finalize ${{ github.sha }}

- name: Delete source maps from deploy bundle
  run: find ./build -name '*.map' -delete

- name: Deploy (without source maps)
  run: aws s3 sync ./build s3://my-app-bucket

5.5 Error Boundaries (React)

Error boundaries catch render-time errors and prevent the entire app from crashing.

// src/components/ErrorBoundary.tsx
import React, { Component, ErrorInfo, ReactNode } from 'react';

interface Props {
  children: ReactNode;
  fallback?: ReactNode | ((props: { error: Error; reset: () => void }) => ReactNode);
  onError?: (error: Error, errorInfo: ErrorInfo) => void;
  level?: 'page' | 'section' | 'widget';
}

interface State {
  hasError: boolean;
  error: Error | null;
}

class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false, error: null };

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    // Report to error tracking
    this.props.onError?.(error, errorInfo);

    console.error(`[ErrorBoundary:${this.props.level}]`, error, errorInfo);
  }

  reset = () => {
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError) {
      if (typeof this.props.fallback === 'function') {
        return this.props.fallback({
          error: this.state.error!,
          reset: this.reset,
        });
      }
      return this.props.fallback ?? <DefaultErrorFallback onRetry={this.reset} />;
    }
    return this.props.children;
  }
}

// Granular boundaries at different levels
function App() {
  return (
    <ErrorBoundary level="page" fallback={<FullPageError />}>
      <Header />
      <main>
        <ErrorBoundary level="section" fallback={<SectionError />}>
          <ProductGrid />
        </ErrorBoundary>
        <ErrorBoundary level="widget" fallback={<WidgetError />}>
          <Recommendations />
        </ErrorBoundary>
      </main>
    </ErrorBoundary>
  );
}

Error Boundary Placement Strategy:

┌────────────────────────────────────────┐
│  Page-Level Boundary                    │  ← Catches catastrophic failures
│                                         │     Shows "Something went wrong" page
│  ┌──────────────────────────────────┐  │
│  │  Section-Level Boundary           │  │  ← Catches section failures
│  │                                   │  │     Shows fallback, rest of page works
│  │  ┌──────────┐  ┌──────────┐      │  │
│  │  │ Widget   │  │ Widget   │      │  │  ← Catches widget failures
│  │  │ Boundary │  │ Boundary │      │  │     Shows placeholder, section works
│  │  └──────────┘  └──────────┘      │  │
│  └──────────────────────────────────┘  │
└────────────────────────────────────────┘

5.6 Structured Error Context

Always enrich errors with context so debugging is fast:

// src/errorTracking/errorReporter.ts

interface ErrorReport {
  // Error details
  type: string;
  message: string;
  stack?: string;

  // Context
  userId?: string;
  sessionId: string;
  page: string;
  route: string;
  component?: string;

  // Environment
  release: string;
  environment: string;
  browser: string;
  os: string;
  viewport: string;
  network: string;

  // Timing
  timestamp: string;
  pageLoadTime?: number;
  sessionDuration?: number;

  // Breadcrumbs (last N actions before error)
  breadcrumbs: Array<{
    type: 'click' | 'navigation' | 'api' | 'console' | 'state';
    message: string;
    timestamp: string;
    data?: Record<string, any>;
  }>;

  // App state snapshot (sanitized)
  state?: {
    cart?: { itemCount: number };
    auth?: { isLoggedIn: boolean; plan: string };
    flags?: Record<string, boolean>;
  };
}

⬆ Back to Top

Frontend Logging Where to Hold Logs and How

6.1 Client-Side Log Collection

Frontend logs are fundamentally different from backend logs — they originate on the user's device, not your server. Getting them off the client reliably is the core challenge.

Log Levels

// src/logging/logger.ts

enum LogLevel {
  DEBUG = 0,   // Development only — verbose debugging info
  INFO = 1,    // Normal operations — page views, user actions
  WARN = 2,    // Potential issues — deprecation, slow API, retry
  ERROR = 3,   // Errors — caught exceptions, API failures
  FATAL = 4,   // Critical — app crash, payment failure
}

interface LogEntry {
  level: LogLevel;
  message: string;
  data?: Record<string, any>;
  timestamp: string;
  sessionId: string;
  userId?: string;
  page: string;
  release: string;
}

class Logger {
  private buffer: LogEntry[] = [];
  private minLevel: LogLevel;
  private maxBufferSize: number;
  private flushInterval: ReturnType<typeof setInterval>;

  constructor(config: { minLevel: LogLevel; maxBufferSize?: number; flushIntervalMs?: number }) {
    this.minLevel = config.minLevel;
    this.maxBufferSize = config.maxBufferSize ?? 50;
    this.flushInterval = setInterval(() => this.flush(), config.flushIntervalMs ?? 10000);

    // Flush on page unload
    document.addEventListener('visibilitychange', () => {
      if (document.visibilityState === 'hidden') this.flush();
    });
  }

  debug(message: string, data?: Record<string, any>) { this.log(LogLevel.DEBUG, message, data); }
  info(message: string, data?: Record<string, any>)  { this.log(LogLevel.INFO, message, data); }
  warn(message: string, data?: Record<string, any>)  { this.log(LogLevel.WARN, message, data); }
  error(message: string, data?: Record<string, any>) { this.log(LogLevel.ERROR, message, data); }
  fatal(message: string, data?: Record<string, any>) { this.log(LogLevel.FATAL, message, data); }

  private log(level: LogLevel, message: string, data?: Record<string, any>) {
    if (level < this.minLevel) return;

    const entry: LogEntry = {
      level,
      message,
      data,
      timestamp: new Date().toISOString(),
      sessionId: getSessionId(),
      userId: getCurrentUserId(),
      page: window.location.pathname,
      release: __APP_VERSION__,
    };

    this.buffer.push(entry);

    // Immediate flush for FATAL
    if (level === LogLevel.FATAL) {
      this.flush();
      return;
    }

    if (this.buffer.length >= this.maxBufferSize) {
      this.flush();
    }
  }

  private async flush() {
    if (this.buffer.length === 0) return;

    const batch = this.buffer.splice(0);

    try {
      const blob = new Blob([JSON.stringify(batch)], { type: 'application/json' });
      const sent = navigator.sendBeacon('/api/logs', blob);

      if (!sent) {
        await fetch('/api/logs', {
          method: 'POST',
          body: JSON.stringify(batch),
          headers: { 'Content-Type': 'application/json' },
          keepalive: true,
        });
      }
    } catch {
      // Save to IndexedDB for retry
      await this.saveToIndexedDB(batch);
    }
  }

  private async saveToIndexedDB(entries: LogEntry[]) {
    try {
      const db = await openLogDB();
      const tx = db.transaction('logs', 'readwrite');
      for (const entry of entries) {
        tx.objectStore('logs').add(entry);
      }
      await tx.done;
    } catch {
      // Last resort — logs are lost. Acceptable for DEBUG/INFO.
    }
  }
}

// Production: only WARN and above
// Development: everything
export const logger = new Logger({
  minLevel: process.env.NODE_ENV === 'production' ? LogLevel.WARN : LogLevel.DEBUG,
  maxBufferSize: 50,
  flushIntervalMs: 10_000,
});

6.2 Log Transport — Getting Logs Off the Client

Transport Method	Reliability	Survives Page Unload	Size Limit	Use Case
`navigator.sendBeacon()`	High	✅ Yes	~64 KB	Primary method (analytics, logs)
`fetch()` with `keepalive`	High	✅ Yes	~64 KB	Fallback for sendBeacon
`fetch()` (normal)	Medium	❌ No	Unlimited	Batch uploads
`XMLHttpRequest`	Medium	❌ No	Unlimited	Legacy fallback
`Image` pixel	High	⚠️ Partial	~2 KB (URL)	Simple event pings
WebSocket	High (persistent)	❌ No	Unlimited	Real-time log streaming
IndexedDB (offline buffer)	High	✅ Persists	~50 MB+	Offline-first, retry queue

Transport Priority Chain

async function sendLogs(payload) {
  const body = JSON.stringify(payload);
  const blob = new Blob([body], { type: 'application/json' });

  // 1. Try sendBeacon (most reliable for page unload)
  if (navigator.sendBeacon?.('/api/logs', blob)) {
    return;
  }

  // 2. Fallback to fetch with keepalive
  try {
    await fetch('/api/logs', {
      method: 'POST',
      body,
      headers: { 'Content-Type': 'application/json' },
      keepalive: true,
    });
    return;
  } catch {}

  // 3. Last resort: save to IndexedDB for later retry
  await saveToIndexedDB(payload);
}

6.3 Log Storage & Querying Infrastructure

Where do logs go after they leave the browser? Here's the full pipeline:

┌──────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────────┐
│  Browser  │    │  Ingestion    │    │  Processing   │    │  Storage &     │
│           │    │  Layer        │    │  Layer        │    │  Querying      │
│ sendBeacon│───>│              │───>│              │───>│               │
│ fetch()   │    │  Options:     │    │  Options:     │    │  Options:      │
│           │    │  • API Gateway│    │  • Kafka      │    │  • ELK Stack   │
│           │    │  • Nginx      │    │  • Kinesis    │    │  • Loki+Grafana│
│           │    │  • Fluentd    │    │  • Datadog    │    │  • Datadog     │
│           │    │  • Vector     │    │    Pipeline   │    │  • CloudWatch  │
│           │    │  • CloudFlare │    │  • Logstash   │    │  • Splunk      │
│           │    │    Workers    │    │  • Vector     │    │  • ClickHouse  │
└──────────┘    └──────────────┘    └──────────────┘    └───────────────┘

Option 1: ELK Stack (Elasticsearch + Logstash + Kibana)

Browser → API Endpoint → Logstash → Elasticsearch → Kibana Dashboard

Pros: Powerful full-text search, great for debugging
Cons: Resource-heavy, expensive at scale

Best for: Large orgs with dedicated infra teams

Option 2: Loki + Grafana (Lightweight)

Browser → API Endpoint → Promtail/Vector → Loki → Grafana

Pros: Lightweight, cost-effective (only indexes labels, not content)
Cons: Weaker full-text search than ELK

Best for: Teams already using Grafana for metrics

Option 3: Datadog

Browser → Datadog Browser SDK → Datadog Logs → Datadog Dashboard

Pros: SaaS, zero infra, correlates logs + traces + metrics
Cons: Expensive at volume

Best for: Teams that want a single observability platform

Option 4: AWS CloudWatch Logs

Browser → API Gateway → Lambda → CloudWatch Logs → CloudWatch Insights

Pros: Serverless, auto-scales, native AWS integration
Cons: Query language is limited, UI is basic

Best for: AWS-native teams

Option 5: Sentry (Errors + Logs combined)

Browser → Sentry SDK → Sentry → Sentry Dashboard

Pros: Errors + breadcrumbs + replay in one place
Cons: Not designed for high-volume logging (use for errors/warnings only)

Best for: Error-focused logging (not general analytics logs)

Comparison Matrix

Solution	Self-Host	Cost	Query Power	Setup	Best For
ELK Stack	✅	$$$–$$$$ (infra)	⭐⭐⭐⭐⭐	Complex	Large scale, full-text search
Loki + Grafana	✅	$–$$	⭐⭐⭐	Medium	Cost-conscious, Grafana users
Datadog	❌ SaaS	$$$$	⭐⭐⭐⭐	Easy	All-in-one observability
CloudWatch	❌ AWS	$$	⭐⭐⭐	Easy	AWS-native teams
Sentry	❌ SaaS (or self-host)	$$–$$$	⭐⭐⭐	Easy	Error-focused
ClickHouse	✅	$–$$	⭐⭐⭐⭐	Medium	Custom analytics + logs

6.4 Structured Logging Best Practices

// ❌ BAD: Unstructured logs — impossible to query
console.log('User clicked button');
console.error('Payment failed for user john');

// ✅ GOOD: Structured logs — queryable, filterable
logger.info('button_clicked', {
  button_id: 'add_to_cart',
  product_id: 'SKU-123',
  page: '/product/SKU-123',
});

logger.error('payment_failed', {
  provider: 'stripe',
  error_code: 'card_declined',
  order_id: 'ORD-456',
  amount: 99.99,
  currency: 'USD',
  // ❌ NEVER log: user.email, user.name, card number, password
});

Structured log fields:

Field	Always Include?	Purpose
`timestamp`	✅	When it happened
`level`	✅	Severity (debug/info/warn/error/fatal)
`message`	✅	What happened (snake_case event name)
`sessionId`	✅	Group logs by session
`userId`	If available	Group logs by user
`page` / `route`	✅	Where it happened
`release`	✅	Which app version
`data.*`	Situational	Additional structured context
`traceId`	For APIs	Correlate frontend + backend logs

6.5 Log Levels & Sampling

Not all logs are equal. Sending every debug log from every user would be overwhelming and expensive.

Production Sampling Strategy:

  FATAL  → 100% sent (every fatal is critical)
  ERROR  → 100% sent (every error matters)
  WARN   → 50% sampled (reduce noise, still catch patterns)
  INFO   → 10% sampled (spot-check user flows)
  DEBUG  → 0% in production (development only)

  Exceptions:
  - 100% for users with active support tickets
  - 100% for internal/beta users
  - 100% for users in active experiments

// Sampling implementation
function shouldSample(level: LogLevel): boolean {
  const rates: Record<LogLevel, number> = {
    [LogLevel.FATAL]: 1.0,
    [LogLevel.ERROR]: 1.0,
    [LogLevel.WARN]:  0.5,
    [LogLevel.INFO]:  0.1,
    [LogLevel.DEBUG]: 0.0,
  };

  // Always log for internal users
  if (isInternalUser()) return true;

  return Math.random() < (rates[level] ?? 0);
}

6.6 Complete Logging Pipeline Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                   Frontend Logging Pipeline                          │
│                                                                      │
│   COLLECTION          TRANSPORT         PROCESSING       STORAGE     │
│                                                                      │
│  ┌─────────────┐    ┌────────────┐    ┌────────────┐  ┌──────────┐  │
│  │ Logger       │    │ sendBeacon │    │ API Gateway│  │ Kafka /  │  │
│  │ (in-memory   │───>│ (primary)  │───>│ / Nginx    │─>│ Kinesis  │  │
│  │  buffer)     │    │            │    │            │  │          │  │
│  │              │    │ fetch()    │    └────────────┘  └────┬─────┘  │
│  │ Batch (20)   │    │ (fallback) │                         │        │
│  │ Flush (10s)  │    │            │                         ▼        │
│  │ Flush on     │    └────────────┘                   ┌──────────┐  │
│  │  unload      │                                     │ Stream    │  │
│  └──────┬──────┘                                     │ processor │  │
│         │ offline?                                    │ (enrich,  │  │
│         ▼                                            │  filter,  │  │
│  ┌─────────────┐    On reconnect                     │  route)   │  │
│  │ IndexedDB    │────── retry ──────────>             └─────┬────┘  │
│  │ (offline     │                                          │        │
│  │  buffer)     │                                          ▼        │
│  └─────────────┘                                    ┌──────────┐   │
│                                                      │ Storage   │   │
│                                                      │           │   │
│                                        Errors ──────>│ Sentry    │   │
│                                        Logs ────────>│ ELK/Loki  │   │
│                                        Analytics ───>│ ClickHouse│   │
│                                        Replays ─────>│ FullStory │   │
│                                                      └──────────┘   │
│                                                           │         │
│                                                           ▼         │
│                                                      ┌──────────┐  │
│                                                      │ Dashboards│  │
│                                                      │ & Alerts  │  │
│                                                      │ (Grafana, │  │
│                                                      │  PagerDuty│  │
│                                                      │  Slack)   │  │
│                                                      └──────────┘  │
└──────────────────────────────────────────────────────────────────────┘

⬆ Back to Top

Putting It All Together Unified Observability

In production, these systems are interconnected:

User Action
    │
    ├──→ Analytics:    track('product_added_to_cart', { ... })
    │
    ├──→ Feature Flag: useFeatureFlag('new_cart_animation')
    │
    ├──→ A/B Test:     experiment exposure tracked
    │
    ├──→ Logger:       logger.info('cart_updated', { itemCount: 3 })
    │
    └──→ Error (if any): Sentry captures with breadcrumbs + replay

All connected by:
  • sessionId  — groups all events from one visit
  • userId     — groups all events from one user
  • traceId    — connects frontend request to backend span
  • release    — associates events with a specific deploy

Unified SDK Example

// src/observability/index.ts
import { analytics } from './analytics';
import { logger } from './logger';
import { featureFlags } from './featureFlags';
import * as Sentry from '@sentry/react';

export const observability = {
  // Analytics
  track: analytics.track.bind(analytics),

  // Logging
  log: logger,

  // Feature flags
  flag: featureFlags.evaluate.bind(featureFlags),

  // Error tracking
  captureError: (error: Error, context?: Record<string, any>) => {
    Sentry.captureException(error, { extra: context });
    logger.error(error.message, context);
  },

  // Identify user across all systems
  identify(user: { id: string; plan: string; [key: string]: any }) {
    analytics.identify(user);
    Sentry.setUser({ id: user.id });
    featureFlags.updateContext({ userId: user.id, plan: user.plan });
    logger.info('user_identified', { userId: user.id });
  },
};

⬆ Back to Top

Decision Matrix and Quick Reference

What Tool for What Job?

Need	Tool Category	Recommendations
"What are users doing?"	Product Analytics	Amplitude, Mixpanel, PostHog
"Why is this page slow?"	Performance Monitoring	Web Vitals + Sentry Perf / Datadog RUM
"What happened before the crash?"	Error Tracking + Replay	Sentry (errors) + LogRocket/FullStory (replay)
"Where are users clicking?"	Heatmaps	Hotjar, Microsoft Clarity (free)
"Is the new design better?"	A/B Testing	LaunchDarkly, Statsig, PostHog
"Can I ship this safely?"	Feature Flags	LaunchDarkly, Unleash, Flagsmith
"What's in the logs?"	Log Management	ELK, Loki+Grafana, Datadog Logs
"User reported a bug"	Session Replay	FullStory, LogRocket, Sentry Replay

Startup vs Enterprise Stack

Stage	Recommended Stack	Monthly Cost
Early startup	PostHog (all-in-one, free self-host) + Sentry (free tier)	$0–$50
Growing startup	Amplitude (analytics) + Sentry (errors) + LaunchDarkly (flags) + Clarity (replay)	$200–$1,000
Mid-size	Segment (CDP) + Amplitude + Sentry + LaunchDarkly + FullStory	$2,000–$10,000
Enterprise	Segment + custom analytics (ClickHouse) + Datadog (full stack) + LaunchDarkly	$10,000+

⬆ Back to Top

Key Interview Takeaways

Topic	Key Points to Mention
Analytics	Event taxonomy (object_action), batching with sendBeacon, sampling for cost, funnel tracking for business metrics
A/B Testing	Server-side evaluation to avoid flicker, deterministic hashing for assignment, statistical significance before calling results
Feature Flags	Decouple deploy from release, singleton evaluation (LD/Unleash), flag hygiene (expiry, owners, cleanup)
Session Replay	DOM diffing (rrweb / MutationObserver), privacy masking, storage cost vs value
Error Tracking	Global handlers (`error`, `unhandledrejection`), source maps uploaded to Sentry (not served), breadcrumbs for context, Error Boundaries at page/section/widget levels
Logging	Structured logs (not console.log), sendBeacon + IndexedDB for reliability, log levels + sampling for cost, ELK/Loki/Datadog for storage
Where to store logs	Sentry for errors, ELK/Loki/Datadog for general logs, ClickHouse for analytics, IndexedDB for offline buffer — never only in the browser

⬆ Back to Top

DEV Community: ZeeshanAli-0704

Frontend System Design: Google Docs

Frontend System Design: Google Docs (Collaborative Document Editor)

1. Concept, Idea, Product Overview

1.1 Product Description

1.2 Key User Personas

1.3 Core User Flows (High Level)

2. Requirements

2.1 Functional Requirements

2.2 Non Functional Requirements

3. Scope Clarification (Interview Scoping)

3.1 In Scope

3.2 Out of Scope

3.3 Assumptions

4. High Level Frontend Architecture

4.1 Overall Approach

4.2 Major Architectural Layers

4.3 External Integrations

5. Component Design and Modularization

5.1 Component Hierarchy

5.2 Rich Text Editor Engine (Deep Dive)

5.2.1 Why ContentEditable vs Custom Rendering

5.2.2 Document Model (Structured Data, Not HTML)

Document Tree Structure

JSON Representation

5.2.3 Selection and Cursor Model

Model Position

5.2.4 Input Handling Pipeline

Why beforeinput Event is Critical

IME (Input Method Editor) Handling

5.2.5 Rendering Pipeline (Model to Canvas)

Why Canvas Instead of DOM (or React) for the Content?

The Pipeline in Plain Terms

Hit-Testing (Pixel → Model Position)

5.2.6 Block and Inline Formatting

Inline Marks (Applied to Text Runs)

Block Types (Applied to Structural Nodes)

Formatting as Operations

5.2.7 Embedded Content (Images, Tables, Embeds)

Images

Tables

5.3 Reusability Strategy

5.4 Module Organization

6. High Level Data Flow Explanation

6.1 Initial Load Flow

6.2 User Interaction Flow

6.3 Error and Retry Flow

7. Data Modelling (Frontend Perspective)

7.1 Core Data Entities

7.2 Data Shape

7.3 Entity Relationships

7.4 UI Specific Data Models

8. State Management Strategy

8.1 State Classification

8.2 State Ownership

8.3 Persistence Strategy

9. Real Time Collaboration Deep Dive

9.1 The Fundamental Problem of Concurrent Editing

9.2 Operational Transformation (OT)

9.2.1 What is an Operation

9.2.2 The Transform Function

Transform(Insert, Insert)

Transform(Insert, Delete)

Transform Implementation

9.2.3 OT with a Central Server

9.2.4 Complete OT Client Implementation

Why Three States?

State Machine Visualization

9.2.5 Server Side OT Orchestration

9.3 CRDTs (Conflict Free Replicated Data Types)

9.3.1 How CRDTs Differ from OT

9.3.2 Sequence CRDTs for Text (Yjs Example)

How Yjs Represents Text

Concurrent Insert Resolution

9.3.3 CRDT Integration with Editor

9.4 OT vs CRDT Comparison

9.5 Cursor and Selection Presence

How Cursor Positions Are Shared

How Cursor Positions Survive Edits

Rendering Remote Cursors

Why `beforeinput` Event is Critical

1. `Array.prototype.map`

Deep dive: `callback.call(thisArg, this[i], i, this)`

2. `Array.prototype.filter`

3. `Array.prototype.reduce`

`arguments` vs `this` (and why `arguments.length >= 2`)

4. `Array.prototype.find`

5. `Array.prototype.some`

6. `Array.prototype.every`

7. `Array.prototype.flat(depth)`

8. `Array.prototype.flatMap`

9. `Array.prototype.includes`

Step 4 — handle cycles with a `WeakMap` (the full answer)

11. `Object.assign`

12. `Object.entries`

13. `Object.fromEntries`

18. `once()`

19. `memoize()`

20. `curry()`

21. `compose()`

22. `pipe()`

23. `partial()`