DEV Community: ZeeshanAli-0704

System Design: Optimistic vs Pessimistic Locking

ZeeshanAli-0704 — Wed, 21 Oct 2026 04:05:38 +0000

Optimistic vs Pessimistic Locking

A practical guide to concurrent updates: version checks, database row locks, conflict aware forms, inventory reservations, deadlocks, and choosing the right strategy.

The problem in one minute

Alice and Bob open the same product editing page. Both see the price as USD 50.

Alice changes it to USD 55 and saves.
Bob still sees the old page, changes it to USD 48, and saves.
A normal "replace the price" request can silently overwrite Alice's change.

Both requests were valid. The problem is that Bob made his decision using an old copy of the data.

Optimistic locking says:

"Save my change only if the data has not changed since I read it."

The server checks a version as part of the write. If someone already changed the record, it rejects the stale write instead of silently replacing newer data.

Think of editing a shared paper form. You photocopy revision 7, make changes, and return it. The clerk accepts it only if revision 7 is still current.

Now consider two shoppers trying to buy the last book. A short transaction can instead lock the inventory row before checking and reserving it. That is pessimistic locking.

Think of one key to a storeroom. The next person waits for the key, then inspects the room as it is now.

Strategy	Simple rule	Typical example
Optimistic	"Save only if my version is still current"	A person editing a product price
Pessimistic	"Coordinate access before making this database decision"	Reserving the last item in a short transaction

Both protect decisions made from shared data. They differ in when they coordinate competing work, not in whether correctness matters.

This guide explains optimistic locking first, pessimistic locking second, then compares them using the same shopping app scenarios.

Why Concurrent Updates Lose Data
What Optimistic Locking Actually Means
The Version Check Flow
The Atomic Database Write
Try It With Two Database Sessions
Carry the Version Through HTTP
Frontend Conflict Handling
Retry, Reload, or Merge
Inventory and Atomic Business Conditions
What a Row Version Does Not Protect
Optimistic Locking vs Optimistic UI
What Pessimistic Locking Means
The Last Item Checkout Flow
Transaction and Lock Lifetimes
Try It With Two Locking Sessions
A Short Reservation Transaction
What Readers and Writers Experience
Wait, Fail Fast, or Skip
Deadlocks and Consistent Lock Order
Do Not Hold Locks During Payment
Database Locks vs Other Locks
Comparison and Decision Guide
Production Rules and Common Mistakes
Testing and Observability
Interview Questions and Answers
Summary and Further Reading

The Mermaid diagrams render on GitHub and in Mermaid enabled Markdown previews. SQL examples use PostgreSQL, with Read Committed isolation unless stated otherwise. They are learning examples, not a complete API implementation. Other engines have different lock modes, defaults, and range lock behavior.

Reading shortcuts: start with version checks for stale edit screens, row locks for short database decisions, or the comparison for choosing a design.

1. Why Concurrent Updates Lose Data

What is a lost update?

A lost update happens when one successful write overwrites another person's change without detecting that it used stale data.

Consider an inventory count:

Step	Request A	Request B	Stored stock
1	Reads 10		10
2		Reads 10	10
3	Computes 10 - 1		10
4		Computes 10 - 1	10
5	Writes 9		9
6		Writes 9	9

Two purchases happened, but stock fell by only one. The second write replaced the first result.

The risky pattern is read, calculate in application memory, then write an absolute value without checking what changed.

-- Unsafe when this value was calculated from an earlier, unchecked read.
UPDATE inventory
SET available = 9
WHERE sku = 'BOOK-100';

Why doesn't a transaction automatically fix this?

A transaction provides an all or nothing boundary. It does not automatically encode the rule "the value I read must still be current."

At PostgreSQL Read Committed isolation, placing a normal SELECT and a later absolute value UPDATE inside a transaction can still allow this stale read modify write pattern.

Higher isolation levels can detect additional anomalies, but they have their own behavior and retry requirements. You must choose the concurrency rule explicitly.

2. What Optimistic Locking Actually Means

What is optimistic about it?

The approach assumes conflicts are uncommon enough that it is better to let people read and work independently, then check at save time.

It does not assume conflicts are impossible.

Three steps define the pattern:

Read the data and its version.
Prepare a change without holding a database lock during that preparation.
Write only if the stored version still matches, then advance the version.

Term	Plain language meaning	Product example
Version	Which saved revision you read	Revision 7
Expected version	The revision your edit is based on	"I edited revision 7"
Conditional write	Save only if a condition still holds	`WHERE version = 7`
Conflict	Another change invalidated your expectation	Database is now revision 8
Compare and swap	Compare the current value, then replace atomically if it matches	Check version and save together

Despite the name, optimistic locking is usually validation, not a long lived lock placed when the user opens the page.

The database can still take short lived row locks while executing the write. "Optimistic" does not mean "the database never locks anything."

Why is this useful for web forms?

A person may keep an edit screen open for ten minutes. Holding a database transaction open for those ten minutes would waste resources and block competing writes.

With a version, the browser can keep its draft without holding database resources. The server validates freshness when the user finally saves.

3. The Version Check Flow

Initial product:

{
  "id": "P-100",
  "priceCents": 5000,
  "version": "7"
}

The version is shown as a string because large database counters may exceed JavaScript's safe integer range. Clients can treat it as an opaque token.

sequenceDiagram
    participant A as Alice
    participant API as Product API
    participant DB as Database
    participant B as Bob
    A->>API: Read product
    API-->>A: Price 5000, version 7
    B->>API: Read product
    API-->>B: Price 5000, version 7
    A->>API: Set price 5500, expected version 7
    API->>DB: Update if version equals 7
    DB-->>API: One row updated, version 8
    API-->>A: Saved
    B->>API: Set price 4800, expected version 7
    API->>DB: Update if version equals 7
    DB-->>API: Zero rows updated
    API-->>B: Conflict - current data must be reviewed

The database does not decide whose price is better. It only prevents Bob from accidentally pretending he edited the latest version.

Bob can deliberately apply USD 48 after reviewing revision 8, but that is a new decision based on current data, not a blind retry.

4. The Atomic Database Write

Example table

CREATE TABLE products (
  id text PRIMARY KEY,
  name text NOT NULL,
  price_cents integer NOT NULL CHECK (price_cents >= 0),
  version bigint NOT NULL DEFAULT 1 CHECK (version > 0)
);

INSERT INTO products (id, name, price_cents, version)
VALUES ('P-100', 'System Design Book', 5000, 7);

Safe conditional update

UPDATE products
SET price_cents = 5500,
    version = version + 1
WHERE id = 'P-100'
  AND version = 7
RETURNING id, price_cents, version;

The version comparison, field update, and version increment happen in one database statement.

Result	Meaning
One returned row	This write matched the expected version and succeeded
No returned rows	No row matched both the identifier and expected version
Database error	The write did not succeed normally - handle the actual error

No returned rows does not universally mean a version conflict. The row may have been deleted, may not exist, or may be excluded by authorization predicates. The API must apply its resource visibility policy before exposing details.

Why must the check and write stay together?

This is unsafe:

SELECT version
If version is 7:
    UPDATE products SET price_cents = 5500 WHERE id = 'P-100'

Another writer can change the row between the check and the write. This is a time of check/time of use race.

Put the condition inside the write, not only in application code.

At Read Committed, if two conditional updates target version 7 concurrently, one may wait for the other writer. If the first commits version 8, PostgreSQL rechecks the waiting update's condition against the updated row, and version 7 no longer matches.

What about deletes?

Deletes can carry the same precondition:

DELETE FROM products
WHERE id = 'P-100'
  AND version = 8
RETURNING id;

Otherwise, a stale screen might delete a product that someone else has substantially changed.

5. Try It With Two Database Sessions

Use a disposable local PostgreSQL database. Run the table setup from Section 4 once.

Open two database sessions and read the product in both:

SELECT id, price_cents, version
FROM products
WHERE id = 'P-100';

Both should see price 5000, version 7.

Session A:

UPDATE products
SET price_cents = 5500,
    version = version + 1
WHERE id = 'P-100' AND version = 7
RETURNING price_cents, version;

Expected: one row, price 5500, version 8.

Session B, still using its earlier version:

UPDATE products
SET price_cents = 4800,
    version = version + 1
WHERE id = 'P-100' AND version = 7
RETURNING price_cents, version;

Expected: zero rows. The price remains 5500, version 8.

This first experiment demonstrates a stale edit. To observe actual contention, begin a transaction in A, run its update without committing, and run B's update. B waits. After A commits, B returns zero rows.

If A rolls back instead, version 7 remains current and B can succeed. The deciding fact is the committed state, not which browser clicked first.

6. Carry the Version Through HTTP

The browser needs a way to say which representation it edited.

Two common API contracts are:

Contract	Read response	Write request	Typical conflict response
Explicit application version	JSON includes `version`	JSON includes `expectedVersion`	`409 Conflict`
HTTP precondition	Response includes a strong `ETag`	Request includes `If-Match`	`412 Precondition Failed`

Do not mix these meanings accidentally. A failed If-Match precondition normally produces 412, not an arbitrary success response.

Example with ETag and If-Match

GET /products/P-100

HTTP/1.1 200 OK
ETag: "product-P-100-v7"
Content-Type: application/json

{"id":"P-100","priceCents":5000}

The browser preserves the ETag exactly, including the quotes:

PATCH /products/P-100
If-Match: "product-P-100-v7"
Content-Type: application/json

{"priceCents":5500}

The server maps that precondition to an atomic conditional database update. Merely checking the ETag before an unconditional update has the same race as checking a version separately.

If this API requires a precondition and none is supplied, it can return 428 Precondition Required rather than permit an unprotected write.

ETag details that matter

If-Match uses strong comparison. A weak ETag such as W/"v7" is not suitable for this write precondition pattern.
A strong ETag must change when the selected representation changes. A row version is suitable only when it tracks every field/dependency represented by that ETag.
A client treats the ETag as opaque. The server must correctly handle the HTTP field syntax rather than blindly trusting a string as a database version.
If-Match: * checks that a current representation exists. It does not protect a particular revision from stale replacement.
Cross origin browser clients need appropriate CORS configuration for the If-Match request header and access to the ETag response header.
Authentication, authorization, and payload validation are still required. A version is not permission to edit.

7. Frontend Conflict Handling

Keep three things separate

An edit screen should know:

Base: the data originally loaded.
Draft: the user's unsaved changes.
Latest: current server data fetched after a conflict.

Do not overwrite the draft as soon as a conflict occurs. That would prevent database data loss by causing user input loss instead.

flowchart TD
    A["Load data and ETag"] --> B["User edits a local draft"]
    B --> C["Save with If-Match"]
    C --> D{"Response"}
    D -->|"Saved"| E["Show confirmed result"]
    D -->|"412"| F["Keep draft and load latest data"]
    F --> G["Compare base, draft and latest"]
    G --> H["User resolves overlapping changes"]
    H --> C
    D -->|"Network failure"| I["Outcome unknown - reconcile before retry"]

A small browser request helper

This helper implements an API contract where a successful save returns JSON. It does not decide how your UI displays or merges a conflict.

async function saveProduct(productId, draft, etag) {
  if (typeof etag !== 'string' || etag.length === 0) {
    throw new Error('Load the product version before saving.');
  }

  const response = await fetch(
    `/products/${encodeURIComponent(productId)}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'If-Match': etag,
      },
      body: JSON.stringify({ priceCents: draft.priceCents }),
    }
  );

  if (response.status === 412) {
    return { status: 'conflict' };
  }

  if (!response.ok) {
    throw new Error(`Product save failed with HTTP ${response.status}.`);
  }

  return {
    status: 'saved',
    product: await response.json(),
    etag: response.headers.get('ETag'),
  };
}

The caller must preserve the draft on conflict, load the latest authorized representation, and show a comparison. A network rejection is propagated so the UI can show an unknown outcome, not silently label it a conflict.

An absent ETag on success means this helper has no validator for the next edit. Re fetch before another protected save, or enforce an API response contract that always supplies a fresh validator.

For successful PATCH responses, return a strong ETag only when it correctly identifies the resulting representation. For a transforming PUT, HTTP imposes additional restrictions on returning validators; a subsequent GET can obtain the current representation and validator.

8. Retry, Reload, or Merge

Why not automatically retry with the newest version?

Because that can turn a detected conflict back into a silent overwrite.

Bob's draft says USD 48 based on revision 7. Replacing its token with revision 8 and resending without review erases the meaning of the check.

Choose based on the operation:

Operation	Sensible response
Human edits a price or legal document	Preserve draft and ask for review
User sets a preference	Explicitly define whether latest user intent should win
System increments a counter	Prefer an atomic increment when that is the business intent
Background recomputation	Re read, recompute, and retry within a bounded budget
Collaborative text editing	Consider OT/CRDT rather than repeated whole document conflicts

A three way merge example

Field	Base revision 7	Alice's saved revision 8	Bob's draft
Name	Book	Advanced Book	Book
Price	5000	5000	4800

Alice changed the name; Bob changed the price. A three way comparison can propose combining both changes.

If both changed the price differently, that is an overlapping conflict requiring an explicit rule or user choice.

After a merge, submit against the latest version. Another writer might win before that save too, so even a merged write still needs a precondition.

A timeout is not a version conflict

The server might have committed a save whose response was lost. A retry with the original version can then fail because your own first request advanced the version.

Reconcile with current state or an operation status endpoint. For commands with side effects, use an idempotency key in addition to concurrency control.

9. Inventory and Atomic Business Conditions

Not every safe write needs a client read version.

If the business operation is "reserve one item if stock exists," express that condition directly:

UPDATE inventory
SET available = available - 1
WHERE sku = 'BOOK-100'
  AND available >= 1
RETURNING sku, available;

The database checks stock and decrements it in one statement. If two requests compete for the last item, only one can consume it under these semantics.

This is a conditional atomic update, not necessarily a version based stale edit check. It protects a stock invariant rather than detecting whether a person saw an old screen.

flowchart TD
    A["What is the operation?"] --> B{"Replace data based on an earlier read?"}
    B -->|"Yes"| C["Require the expected version"]
    B -->|"No"| D{"Simple atomic business condition?"}
    D -->|"Yes"| E["Put the condition in the UPDATE"]
    D -->|"No"| F["Consider a transaction and appropriate coordination"]

If the inventory row also participates in a versioning protocol, advance its version on this path too. All writers must agree on how changes become visible to version based clients.

Creating an order and consuming inventory may require a transaction. A guarded decrement alone does not make the entire checkout workflow atomic or idempotent.

10. What a Row Version Does Not Protect

Multi row invariants

Suppose two doctors are on call. The rule is at least one doctor must remain on call.

Transaction A reads that Bob is on call, then takes Alice off call.
Transaction B reads that Alice is on call, then takes Bob off call.
Each updates a different row with the correct version.

Both row version checks can succeed while the combined rule fails. This is write skew.

A version check on a row protects that row's expected revision, not arbitrary facts read from other rows.

Possible designs include:

Serializable transactions with whole transaction retries.
A shared coordination row that every relevant transaction updates or locks.
Locking the complete relevant set in a consistent order.
A schema or constraint that directly enforces the invariant where possible.

Other boundaries

A version check is not a uniqueness constraint.
It does not reserve stock for the next fifteen minutes.
It does not deduplicate repeated payments.
A cache only version check does not protect the authoritative database write.
A check against a stale read replica cannot replace the primary's atomic condition.

Missing rows and predicates need their own protection

In PostgreSQL, a SELECT ... FOR UPDATE that returns no rows does not row lock a future record.

Checking that username "alice" does not exist and then inserting it is not sufficient. Use a unique constraint to enforce uniqueness.

For more complex absence or range rules, consider an appropriate constraint, a stable coordination row, or Serializable isolation with retries. Locking existing rows alone does not necessarily protect a predicate from concurrent inserts.

Do not generalize this to every engine: gap and range lock behavior varies.

11. Optimistic Locking vs Optimistic UI

These names describe different layers:

Concept	What it does	Example
Optimistic locking	Protects server writes from stale assumptions	Reject saving version 7 after version 8 exists
Optimistic UI	Shows a predicted result before server confirmation	Show a new cart item immediately

You can use both. The UI predicts success, but if the server rejects the write, it reconciles or rolls back that prediction while preserving user intent.

Updating React state optimistically does not provide database concurrency control.

12. What Pessimistic Locking Means

What is a lock?

A lock is a database managed coordination rule. It determines which operations may access a protected resource concurrently.

For a read decide write transaction, SELECT ... FOR UPDATE locks the selected rows so competing updates, deletes, and conflicting locking reads must wait or follow the chosen failure policy.

SELECT sku, available
FROM inventory
WHERE sku = 'BOOK-100'
FOR UPDATE;

The lock must stay held while you check the value and perform related changes inside the same transaction. The keyword alone does not protect statements that run after that transaction ends.

Why "pessimistic"?

The design assumes conflicts are important enough to coordinate access before doing the protected work:

Optimistic:
Read -> prepare change -> conditionally write against the expected version

Pessimistic:
Acquire lock -> read protected state -> decide -> write -> end transaction

Term	Plain language meaning
Transaction	A group of database operations that commit or roll back together
Row lock	Coordination over a particular database row
Contention	Multiple operations competing for the same protected resource
Lock wait	Time spent waiting for a conflicting holder to finish
Deadlock	Transactions wait on each other in a cycle
Lock timeout	A limit on how long an operation may wait to acquire a lock

Use it for short, database local decisions where several operations depend on protected current values.

Do not hold a database lock while a person keeps an edit screen open. Human editing is usually a better fit for version checks or an explicit application level editing lease.

13. The Last Item Checkout Flow

A shop has one book left. Alice and Bob click Buy at almost the same time.

If both read "one available" before either updates stock, both can believe they may buy it.

With a protected read and decision:

sequenceDiagram
    participant A as Alice request
    participant DB as Database
    participant B as Bob request
    A->>DB: BEGIN
    A->>DB: SELECT inventory FOR UPDATE
    DB-->>A: Lock acquired, available 1
    B->>DB: BEGIN
    B->>DB: SELECT same inventory FOR UPDATE
    Note over B,DB: Bob waits for the conflicting row lock
    A->>DB: Reserve item and set available to 0
    A->>DB: COMMIT
    DB-->>B: Lock acquired, available 0
    B->>B: Reject purchase as out of stock
    B->>DB: ROLLBACK

Why does Bob need to check again?

His screen may have shown "one left." That screen is not the authority.

The decision must use the row returned after acquiring the lock, not an earlier cache or browser value.

At PostgreSQL Read Committed isolation, a waiting locking read can return the updated row after the competing transaction commits. At Repeatable Read or Serializable, a conflicting change can instead produce a serialization error; handle that isolation level's retry contract.

If Alice rolls back, Bob can see the still available item. A lock itself does not consume inventory; committed data changes do.

14. Transaction and Lock Lifetimes

The essential boundary

flowchart LR
    A["BEGIN"] --> B["Lock row"]
    B --> C["Read and validate"]
    C --> D["Write related changes"]
    D --> E["COMMIT or ROLLBACK"]
    E --> F["Transaction locks released"]

In PostgreSQL, transaction level row locks are normally released when the transaction commits or rolls back. Locks acquired after a savepoint can also be released by rolling back to that savepoint.

Why autocommit can break your intended design

If the locking SELECT runs as an independent autocommit statement, its transaction ends as soon as that statement finishes. The lock is gone before your later statement makes the decision.

This is not enough:

Autocommit SELECT FOR UPDATE
Application calculates result
Another independent UPDATE

Use one explicit transaction and the same database connection throughout.

A connection pool's general query helper may run separate calls on different connections. Use the driver's transaction/client API instead of assuming consecutive calls share a transaction.

How long should a lock be held?

Only as long as the protected database work needs. Do not include:

User think time.
Payment provider requests or customer authentication.
Email delivery.
An unrelated HTTP call.
Slow CPU work that could happen before acquiring the lock.

Holding a lock longer increases queues for everyone targeting the same resource.

15. Try It With Two Locking Sessions

Use a disposable local PostgreSQL database.

Setup, once

The earlier inventory examples described the mechanism. Create their actual learning table here:

CREATE TABLE inventory (
  sku text PRIMARY KEY,
  available integer NOT NULL CHECK (available >= 0)
);

INSERT INTO inventory (sku, available)
VALUES ('BOOK-100', 1);

Session A: lock but do not commit yet

BEGIN;

SELECT sku, available
FROM inventory
WHERE sku = 'BOOK-100'
FOR UPDATE;

UPDATE inventory
SET available = available - 1
WHERE sku = 'BOOK-100';

Leave the transaction open temporarily for this experiment. Do not do this in production.

Session B: try to acquire the same lock

BEGIN;

SELECT sku, available
FROM inventory
WHERE sku = 'BOOK-100'
FOR UPDATE;

Expected: B waits. It does not immediately return "one available."

Session A: finish

COMMIT;

B should now return available = 0. Its transaction still holds the lock it just acquired, so finish B too:

ROLLBACK;

What did this prove?

A conflicting locking read waits while A holds the row.
After A commits, B sees the updated value under Read Committed.
B must use that value to reject the purchase.
Ending B's transaction releases its lock.

For a rollback variant, restore stock to one outside these transactions, repeat the experiment, and roll A back instead of committing. B should then see one available.

Always close experimental transactions. An abandoned session can keep locks and database resources occupied.

16. A Short Reservation Transaction

A real checkout needs more than a decrement. It needs a durable record explaining who owns the reserved item and when that reservation expires.

After closing both experimental transactions, restore one item and add a reservation table:

UPDATE inventory SET available = 1 WHERE sku = 'BOOK-100';

CREATE TABLE reservations (
  id text PRIMARY KEY,
  sku text NOT NULL REFERENCES inventory(sku),
  quantity integer NOT NULL CHECK (quantity > 0),
  status text NOT NULL CHECK (status IN ('pending', 'confirmed', 'expired')),
  expires_at timestamptz NOT NULL
);

The following is a transaction template. Application branching is explicit in the comments; PostgreSQL does not interpret those comments as control flow.

BEGIN;

SET LOCAL lock_timeout = '500ms';

SELECT sku, available
FROM inventory
WHERE sku = 'BOOK-100'
FOR UPDATE;

-- Application: if no row or available < 1, ROLLBACK and return a domain error.
-- Continue only after that check succeeds.

UPDATE inventory
SET available = available - 1
WHERE sku = 'BOOK-100'
  AND available >= 1
RETURNING available;

-- Application: require exactly one returned row, otherwise ROLLBACK.

INSERT INTO reservations (id, sku, quantity, status, expires_at)
VALUES ('R-100', 'BOOK-100', 1, 'pending', now() + interval '10 minutes');

COMMIT;

If the insert fails, roll back the transaction, restoring the decrement. Do not catch the error and commit only the stock change.

In production, generate identifiers, bind values as SQL parameters, authorize the operation, and deduplicate repeated reservation commands. A primary key prevents duplicate IDs, but does not by itself define a friendly retry protocol.

Why keep the guarded UPDATE if a lock is held?

It states the stock rule at the write boundary and adds defense against an incorrect application branch. The CHECK (available >= 0) is another safeguard.

If all you need is a conditional decrement, one guarded update can suffice without an earlier locking read. Use the explicit lock when additional decisions or dependent writes make the protected read useful.

What happens on errors?

The SQL shows the successful path. Use the driver's transaction mechanism to roll back on every error, release the connection in a finally-style cleanup, and classify failures before choosing a whole transaction retry.

Never return a pooled connection with an open or failed transaction.

17. What Readers and Writers Experience

Pessimistic row locking does not necessarily mean "nobody can read this row."

PostgreSQL uses multi version concurrency control (MVCC). An ordinary SELECT can generally read a committed version while another transaction holds a row lock.

For a row locked with FOR UPDATE:

Competing operation	Typical PostgreSQL behavior
Ordinary `SELECT`	Reads a visible committed version without waiting for that row lock
`UPDATE` of the same row	Waits for the conflicting writer
`DELETE` of the same row	Waits
Another `SELECT ... FOR UPDATE`	Waits unless a non waiting policy is used
Operation on a different row	Not blocked by this row lock alone

"Not blocked by this row lock" does not promise a query can never wait. Table/DDL locks, other resources, and query execution can still cause waits.

PostgreSQL also has weaker row lock modes such as FOR NO KEY UPDATE, FOR SHARE, and FOR KEY SHARE. Choose the mode appropriate to your invariant rather than copying FOR UPDATE everywhere.

Do not assume PostgreSQL row lock rules exactly match another engine's gap, range, or escalation rules.

18. Wait, Fail Fast, or Skip

Option A: wait within a lock budget

BEGIN;
SET LOCAL lock_timeout = '500ms';

SELECT sku, available
FROM inventory
WHERE sku = 'BOOK-100'
FOR UPDATE;

-- Perform the short protected work, then commit.
COMMIT;

lock_timeout limits lock acquisition waiting, not total request duration. Use suitable statement, transaction, and HTTP budgets too.

If it times out, PostgreSQL reports an error and the failed transaction must be rolled back. Do not continue to the update as if the lock were acquired.

Option B: fail immediately with NOWAIT

SELECT sku, available
FROM inventory
WHERE sku = 'BOOK-100'
FOR UPDATE NOWAIT;

If the row cannot be locked immediately, the statement fails. This can support "busy, try shortly" instead of a long spinner.

NOWAIT does not report "out of stock." Lock unavailability and business unavailability are different outcomes.

Option C: skip busy rows with SKIP LOCKED

Useful for a queue, where another worker can handle a different job:

WITH candidate AS (
  SELECT id
  FROM jobs
  WHERE status = 'ready'
  ORDER BY created_at, id
  LIMIT 1
  FOR UPDATE SKIP LOCKED
)
UPDATE jobs
SET status = 'running'
FROM candidate
WHERE jobs.id = candidate.id
RETURNING jobs.id;

This example assumes a separate jobs table with id, status, and created_at. The claim is one atomic statement; it is not part of the inventory setup.

SKIP LOCKED deliberately omits busy rows. It is useful for competing queue consumers, not a consistent "show all inventory" query. It does not guarantee strict FIFO ordering or freedom from starvation.

After the claim commits, the lock is released. A crashed worker can leave a job marked running. Real queues need a claim owner, lease/timeout recovery, idempotent processing, and protection against a stale worker completing reassigned work.

19. Deadlocks and Consistent Lock Order

How does a deadlock happen?

Transaction A locks item 1, then requests item 2.
Transaction B locks item 2, then requests item 1.
Each holds the resource the other needs.

flowchart LR
    A["Transaction A holds item 1"] -->|"Waits for item 2"| B["Transaction B holds item 2"]
    B -->|"Waits for item 1"| A

Neither can finish without the other releasing its lock.

PostgreSQL detects the cycle and aborts one transaction. Do not depend on which transaction it chooses.

Use a common acquisition order

For a multi item order:

Collect all item identifiers.
Sort them consistently.
Acquire each lock in that order on the same transaction connection.
Validate the complete order, then write.

Every relevant path must follow the convention, including restocking, reservation expiry, and administrative operations.

This reduces a class of deadlocks; it does not prove the application is deadlock free. Foreign keys, triggers, other tables, and automatic locks can add dependencies.

Retry the whole transaction

After a deadlock or serialization failure, roll back and retry the whole transaction, including reads and decisions, within a bounded budget.

Do not retry just the last SQL statement with assumptions from an aborted transaction.

Retry only when replay is safe. An email or payment already sent outside the database cannot be undone by rolling back.

20. Do Not Hold Locks During Payment

The tempting but dangerous flow

BEGIN
Lock inventory
Call payment provider
Wait for customer authentication
Update order
COMMIT

A payment can take seconds or minutes. Other requests queue behind the lock, connections stay occupied, and a provider timeout creates an ambiguous result.

A local transaction cannot roll back money already charged externally.

Better: persist a reservation, then release the lock

sequenceDiagram
    participant API as Checkout API
    participant DB as Database
    participant PSP as Payment provider
    API->>DB: Begin short transaction
    API->>DB: Lock stock and create expiring reservation
    API->>DB: Commit and release locks
    API->>PSP: Charge using an idempotency key
    PSP-->>API: Payment result
    API->>DB: Begin finalization transaction
    API->>DB: Validate reservation state and record result
    API->>DB: Commit final state

Mechanism	Lifetime	Purpose
Database row lock	Until the short transaction ends	Prevent conflicting changes during a database decision
Business reservation	Until confirmed or expired by application rules	Hold inventory across a longer workflow

Expiry and payment completion can race. Both paths must coordinate on the same reservation state, with conditional transitions and transactional stock changes so inventory is released at most once.

If a late payment succeeds after expiry, use an explicit policy such as re reserving stock or refunding. Do not confirm an expired reservation unconditionally.

Use a transactional outbox or another deliberate recovery mechanism for external effects that must follow a database commit.

What should the frontend show?

The browser sends an authenticated command. It does not own a database row lock.

API outcome	Meaning	UI behavior
Reservation confirmed	Short transaction committed	Continue with the reservation
Out of stock	Protected business check failed	Refresh availability and explain
Busy/lock timeout	Could not obtain access within the budget	Preserve input and offer a bounded retry
Deadlock retry exhausted	Allowed retries did not complete	Show a retryable failure, not purchase success
HTTP/network timeout	Outcome may be unknown	Check status or reuse the same operation identity

An API might map a domain conflict to 409 and temporary service pressure to 503 with Retry-After. Define the contract explicitly; SQL lock errors do not have one universal HTTP status.

Disabling the Buy button prevents duplicate clicks in one screen. Only backend concurrency and idempotency rules protect against another tab, a phone, or a retried request.

21. Database Locks vs Other Locks

Mechanism	Scope	What it does not automatically protect
JavaScript mutex in one server process	Cooperating code in that process	Another server process or direct database writer
Browser Web Lock	Cooperating eligible browser contexts	Another browser, device, or backend instance
Database row lock	Conflicting access to rows in that database	External payments or arbitrary resources outside the transaction
Database advisory lock	Cooperating callers using the same advisory key	Writers that ignore that convention
Distributed lease	Cooperating clients of an external coordinator	Late writes from an expired owner without fencing

A database row lock coordinates requests from many backend instances because the database centrally manages conflicting row operations.

You do not need a separate distributed lock service merely because the API has multiple replicas. Coordinate at the resource that actually owns the invariant.

Conversely, a row lock does not make a multi database or external service workflow atomic.

22. Comparison and Decision Guide

Question	Optimistic	Pessimistic
Main idea	Check freshness at write time	Acquire a lock before the protected read/decision
While preparing an edit	No long lived database lock	Competing protected operations may wait
Typical conflict outcome	Conditional write fails	Wait, fail fast, or time out
Good starting point	Long lived forms, relatively rare conflicts	Short transactions needing exclusive access
Main cost	Conflict handling and repeated work	Waiting, lock management, deadlocks
Can database writes still lock?	Yes	Yes

Neither strategy is universally correct. High contention can make optimistic retries expensive, while a hot pessimistic lock can turn into a throughput bottleneck.

A practical decision guide

flowchart TD
    A["What needs protection?"] --> B{"Long lived human edit?"}
    B -->|"Yes"| C["Version check and conflict aware UI"]
    B -->|"No"| D{"Can one conditional write enforce the rule?"}
    D -->|"Yes"| E["Use an atomic guarded write"]
    D -->|"No"| F{"Short database local read and dependent writes?"}
    F -->|"Yes"| G["Consider row locks and a transaction"]
    F -->|"No"| H["Design the wider invariant and recovery protocol"]

The same application can use both:

Product editing forms use versions to reject stale edits.
Checkout uses short row locking transactions for reservations.
Simple counters use atomic updates.
Payment retries use idempotency keys.

These mechanisms solve different parts of correctness. They are not mutually exclusive application wide settings.

23. Production Rules and Common Mistakes

Optimistic rules

Every participating write must advance the version, including admin jobs, imports, and background updates.
Compare and change in one authoritative database operation.
Return explicit conflict results rather than success shaped fallbacks.
Preserve drafts and provide a recovery path.
Bound automated retries and use backoff/jitter when appropriate.
Keep database constraints as the final defense for representable invariants.
Include authorization predicates and enforce permissions independently of versions.
Publish cache invalidations only after the write commits.

Pessimistic rules

Start the transaction before the intended lock.
Keep protected work on one connection and inside that transaction.
Read decision values after locking.
Keep the critical section short and lock only the relevant rows.
Use suitable indexes to find those rows efficiently.
Acquire multiple resources in a consistent order.
Set lock/request budgets and classify failures explicitly.
Roll back on errors before releasing pooled connections.

Why use a counter instead of a timestamp?

A monotonic row counter is simple to reason about. Timestamp precision, repeated values, or application clocks can make a naive timestamp comparison unsafe.

A timestamp or opaque token can work if its generation and comparison guarantee that protected changes get distinct validators. Do not assume any updated_at field automatically has that guarantee.

Common mistakes

Mistake	Why it fails
Check the version, then write without it	Another write can slip between the two operations
Forget to increment the version	Later clients cannot detect the change
Retry a human draft with a fresh token silently	Reintroduces lost updates
Use browser cross tab messages as the authority	Another browser or missed notification bypasses them
Treat every zero row update as an exposed conflict	Can misclassify deletion or leak resource existence
Assume the version prevents duplicate commands	A retry and a stale edit are different problems
Reset versions when reusing an identifier	An old token can accidentally match a new record
Use `FOR UPDATE` in autocommit, then write later	The intended lock is already released
Split transaction steps across pooled connections	They do not share the intended transaction
Hold a lock during payment or user think time	Long queues and ambiguous external effects
Treat `SKIP LOCKED` as a complete result set	Busy rows disappear from the query's view
Assume a row lock protects missing rows	Concurrent inserts can bypass the assumption

Use non reused identifiers or include a generation identifier in the validator to avoid the "old state looks current again" problem.

An HTTP disconnect does not guarantee the backend database transaction was cancelled. A database connection failure also may take time for the server to detect. Define cancellation, timeouts, and cleanup explicitly instead of assuming locks disappear immediately.

24. Testing and Observability

Test the guarantee, not just the happy path

Test	Required outcome
Two clients read version 7 and save different values	One succeeds, the stale one cannot overwrite it
Two truly concurrent writes use version 7	At most one commits against that version
First competing writer rolls back	A later valid writer can still succeed
A background job edits the row	Its change advances the same version protocol
Row is deleted after a client read	No accidental resurrection through the update
A conflict occurs in the browser	Draft remains available for review
Save commits but response is lost	Client reconciles rather than claiming a definite failure
Two rows enforce a shared invariant	Invariant holds under the chosen multi row design
Two purchases target one remaining item	At most one reservation consumes it
A lock holder rolls back	A waiting transaction can see available stock again
A request exceeds the lock budget	Explicit timeout handling and full rollback
Two orders acquire multiple rows in opposite orders	Deadlock handling leaves no partial commits
A worker crashes after claiming a job	Recovery can reassign it safely
Reservation expiry races with payment completion	No double release or invalid confirmation
A duplicate checkout request arrives	One operation does not reserve twice
A locking query matches no rows	Constraints or invariant design still handle inserts

For concurrency tests, use separate database connections and synchronization barriers. Two requests executed one after the other only test stale data, not lock waiting or interleaving.

Useful metrics include conditional write conflict rate, successful saves, bounded retry exhaustion, save latency, and user visible conflict resolution rate. Avoid logging sensitive draft contents.

A high conflict rate may indicate a hot record, an overly broad document version, or an operation that should be expressed as an atomic command rather than whole record replacement.

For row locking workflows, also measure lock wait time, lock timeouts, transaction duration, deadlocks, idle in transaction sessions, pool queue time, and retry exhaustion.

In PostgreSQL, pg_stat_activity, pg_locks, and pg_blocking_pids() help identify holders and waiters. Visibility depends on database privileges; avoid exposing sensitive query text.

For last item concurrency tests, assert final stock and durable reservation count, not only HTTP status codes.

Why does lock duration matter?

If every request needs the same exclusive row for roughly 100 ms, that protected portion is limited to roughly ten completions per second before other overhead.

This is a capacity illustration, not a benchmark. Making that critical section ten times slower can make its queue grow dramatically even if the rest of the service is fast.

25. Interview Questions and Answers

What is optimistic locking in one sentence?

Save only if the record still has the version you read, and advance that version atomically when the save succeeds.

Does it avoid all locks?

No. It avoids holding a long lived lock while preparing a change, but the database can still lock rows during writes.

Why not just check the version in JavaScript?

Another writer can change the record after the JavaScript check. The authoritative write must include the expected version condition.

Should every conflict be retried automatically?

No. Recompute safe machine operations when appropriate, but do not silently overwrite someone else's edit with a stale human draft.

Can two different row updates still violate a rule?

Yes. Row versions do not automatically protect cross row invariants. Write skew needs a broader transaction or coordination design.

Is this the same as an idempotency key?

No. A version detects stale assumptions. An idempotency key identifies repeated attempts of the same command.

What is pessimistic locking in one sentence?

Acquire a database lock before the protected read and decision, keep it through related writes, and release it when the transaction ends.

Does FOR UPDATE block every reader?

Not in PostgreSQL. Ordinary reads generally see a visible committed version; competing writers and conflicting locking reads wait on that row lock.

Is SELECT FOR UPDATE enough by itself?

No. The decision and write must happen inside the same transaction while the lock is still held.

Can row locks deadlock?

Yes. Two transactions can hold different rows and wait for each other's row. Use consistent acquisition order and safe bounded whole transaction retries.

Should checkout hold a stock lock until payment finishes?

No. Commit a durable reservation in a short transaction, then perform payment and finalization using an explicit state/recovery protocol.

Which approach is better?

It depends on the invariant, conflict rate, transaction length, and recovery needs. Prefer a single atomic guarded update when it already expresses the complete rule.

26. Summary and Further Reading

Explain optimistic locking in plain English

I let people edit without holding database locks. Each read carries a version. The server saves only if that version is still current, and advances it in the same operation. If the data changed, I preserve the draft and help the user reconcile instead of silently overwriting newer work.

Explain pessimistic locking in plain English

I use a short transaction to lock rows involved in a database decision. Competing changes wait or follow an explicit non waiting policy. I inspect current protected values, make related changes atomically, and commit quickly. I never keep those locks while a user thinks or a payment provider responds.

Remember:

The problem is stale read modify write decisions.
The core mechanism is an atomic expected version check.
Conflicts are a normal outcome, not an excuse to discard user input.
Atomic business updates, constraints, idempotency, and transaction isolation solve related but different problems.
Row locks protect short database critical sections, not the whole user journey.
Long lived reservations are stored business state, not long held database locks.

Cross-Tab and Cross-Browser Communication

ZeeshanAli-0704 — Sat, 17 Oct 2026 10:48:02 +0000

Cross-Tab and Cross-Browser Communication

A practical guide to communication between tabs, windows, iframes, and workers in one browser instance, plus communication across browser instances and devices.

The problem in one minute

You open a shopping app in two tabs. In Tab A, you add a book to your cart. Tab B still shows Cart (0).

Why? Each tab runs its own application code and holds its own in-memory state. Updating a variable or a React store in Tab A does not update the corresponding variable or store in Tab B. Even if both tabs share a login cookie, their visible UI state is separate.

Cross-tab communication lets Tab A tell Tab B: "The cart changed; check the latest cart."

Now open the same app in Firefox or on your phone. A Chrome-local channel cannot reach those clients. The backend must store the change and notify the other connected clients.

That is the central idea of this article:

Messages tell other contexts that something happened. An authoritative store tells them what is true now.

We will use a shopping app as a running example: cart updates, logout, one shared connection, and recovery after a tab misses an update.

How to read the diagrams

The diagrams below use Mermaid, which GitHub can render directly. If your Markdown viewer does not support Mermaid, the surrounding explanations describe the same flow.

flowchart LR
    A["Tab A: add a book"] --> S["Backend: save cart"]
    S --> R["Tab A: save confirmed"]
    R --> C["Browser-local notification"]
    C --> B["Tab B: fetch latest cart"]
    S --> E["Backend real-time delivery"]
    E --> P["Phone or Firefox: fetch latest cart"]

Start With the Communication Boundary
What the Browser Provides by Default
BroadcastChannel
The localStorage Storage Event
window.postMessage and MessageChannel
SharedWorker
Service Worker as a Relay
IndexedDB and Web Locks
A Production Cross-Tab Event Bus
Common Cross-Tab Use Cases
Leader Election and Single-Owner Work
Cross-Browser Instances and Devices
Server-Mediated Real-Time Architecture
Reliability, Ordering and Replay
Security and Privacy
Decision Guide
Testing and Observability
Interview Questions and Answers

Additional references: Summary | Further Reading

1. Start With the Communication Boundary

Before choosing an API, identify which contexts must communicate.

What is a context, and why are tabs isolated?

A context is a place where JavaScript runs: a page, an iframe, or a worker. A worker runs JavaScript without owning a page's DOM.

Two tabs loading the same app do not share ordinary JavaScript objects:

// Run this in Tab A's console.
window.cartCount = 3;

// Run this in Tab B's console.
console.log(window.cartCount); // undefined, unless Tab B set its own value

This isolation lets pages run independently and helps enforce browser security boundaries. A message API is an explicit bridge between contexts; it does not merge their memory.

Think of tabs as separate rooms:

An in-memory store is a whiteboard inside one room.
BroadcastChannel is a live announcement to rooms on the same local channel.
IndexedDB is a shared filing cabinet those rooms can read.
A backend is the shared service that people in other buildings can also reach.

Same JavaScript context
  └─ components/modules in one page

Related browsing contexts
  ├─ parent ↔ iframe
  ├─ opener ↔ popup
  └─ page ↔ dedicated worker

Same origin + same browser instance
  ├─ Chrome Tab 1 ↔ Chrome Tab 2
  ├─ Chrome Window 1 ↔ Chrome Window 2
  ├─ SharedWorker clients
  └─ Service Worker clients

Outside that browser instance
  ├─ Chrome instance ↔ Firefox instance
  ├─ browser ↔ desktop/mobile app
  └─ device A ↔ device B

The most important distinction

For this guide, a browser instance is shorthand for a browser environment containing tabs and windows that can share the relevant browser-managed storage and messaging scope. It does not mean one operating-system process: modern browsers use many processes.

For ordinary first-party tabs, start with:

Same origin + same browser instance

The more precise rule is same origin + compatible storage partition/profile + API-specific scope. Separate profiles, normal versus private browsing, and browser privacy partitioning can separate otherwise identical URLs. A same-origin iframe embedded under a different top-level site may be in a different storage partition and unable to join the same BroadcastChannel.

Conversely, opening a second browser window is not necessarily a new isolated environment. Two windows using the same profile can still communicate. Do not use window count or process IDs to determine the boundary.

Separate browser environments or devices normally need a shared external system: your backend. The tables below assume ordinary same-profile, first-party pages; API-specific restrictions still apply.

What exactly is an origin?

An origin is the combination of scheme + hostname + port. A URL path is not part of it.

URL compared with `https://shop.example.com/cart`	Same origin?	Why?
`https://shop.example.com/products`	Yes	Only the path changed
`https://shop.example.com/cart?view=small`	Yes	Query parameters do not change the origin
`https://admin.example.com/cart`	No	Different hostname
`http://shop.example.com/cart`	No	Different scheme
`https://shop.example.com:8443/cart`	No	Different port

Why this matters: the browser uses origins as security boundaries. Two pages belonging to the same business are not automatically allowed to share a local channel.

Scope matrix

Contexts	Direct browser communication?	Typical option
Components in one page	Yes	In-memory event bus or state store
Parent and known iframe/popup	Yes	`postMessage`
Chrome Tab 1 and Tab 2 on the same origin	Yes	`BroadcastChannel`, `storage`, SharedWorker
Two Chrome windows on the same origin in one browser instance	Yes	`BroadcastChannel`, `storage`, SharedWorker
Different origins	Restricted	`postMessage` for related windows; otherwise backend
Chrome instance and Firefox instance	No direct local channel	Backend
Two separate browser instances	No direct local channel	Backend
Different devices	No direct local channel	Backend

Example: Chrome Tab 1 and Tab 2

Suppose both tabs are open in the same Chrome instance:

Tab 1: https://shop.example.com/products
Tab 2: https://shop.example.com/cart

Both URLs have the same origin:

protocol: https
host:     shop.example.com
port:     443 (the default HTTPS port)

Tab 1 can notify Tab 2 when an item is added to the cart.

Tab 1:

const channel = new BroadcastChannel('shop-events');

channel.postMessage({
  type: 'cart:item-added',
  productId: 'P-100',
});

Tab 2:

const channel = new BroadcastChannel('shop-events');

channel.addEventListener('message', event => {
  if (event.data.type === 'cart:item-added') {
    refreshCart();
  }
});

Assuming both tabs use the same profile and storage partition, this works because both pages use the same origin and open a channel with the same name, shop-events.

It would not work directly if Tab 2 used https://admin.example.com, because that is a different origin.

Example: two Chrome windows

The same rule applies when the pages are in separate Chrome windows:

Chrome Window 1: https://shop.example.com/dashboard
Chrome Window 2: https://shop.example.com/orders

The pages can still use the same BroadcastChannel. Moving a tab into another Chrome window does not change its origin or prevent browser-managed communication.

For example, Window 1 can announce a logout:

const channel = new BroadcastChannel('auth-events');
channel.postMessage({ type: 'auth:logged-out' });

Window 2 listens for it:

const channel = new BroadcastChannel('auth-events');

channel.addEventListener('message', event => {
  if (event.data.type === 'auth:logged-out') {
    window.location.assign('/login');
  }
});

The important rule is not whether the pages are displayed as tabs or separate windows. For BroadcastChannel, they need the same origin, compatible storage partition, and the same channel name.

2. What the Browser Provides by Default

No library is required for the browser's core communication APIs.

Three different jobs: notify, store, coordinate

These jobs often appear together, but they are not interchangeable:

Job	Plain-language question	Shopping-app example	Suitable mechanism
Communication	"What should another tab know?"	"Cart C-900 changed"	`BroadcastChannel`
Storage	"Where can I read the current data?"	Latest saved cart or offline draft	Backend or IndexedDB
Coordination	"Who is allowed to do this work right now?"	Only one tab drains the offline queue	Web Locks

A message is like a doorbell: it gets someone's attention. Stored state is the package left at the door: it can still be read later. A lock is the key that lets one person handle the package at a time.

For example, BroadcastChannel can announce a cart change, but it does not store the cart or prevent two tabs from submitting the same operation.

API	Scope	Message or shared state?	Durable?	Best use
`BroadcastChannel`	Same origin in one browser instance	Message	No	General cross-tab events
`storage` event	Same origin using `localStorage`	Change notification	Value persists	Compatibility fallback, simple signals
`window.postMessage`	Related windows/iframes	Message	No	Popup/iframe communication
`MessageChannel`	Two contexts with transferred ports	Message	No	Private point-to-point channel
SharedWorker	Same-origin tabs supported by the browser	Shared process/state + ports	Worker lifetime only	One socket or shared in-memory coordinator
Service Worker	Controlled pages for one origin	Message/relay	Worker is event-driven	Page coordination plus network/offline logic
IndexedDB	Same origin in one browser instance	Shared durable storage	Yes	Shared source of truth
Web Locks	Same origin in one browser instance	Coordination, not messaging	Lock lifetime only	Ensure one tab performs a task

Browser support is part of the design

Support and lifecycle behavior vary, especially for SharedWorker, service workers, and background throttling. Build capability detection and choose an explicit fallback rather than assuming every API exists.

Service workers and Web Locks require secure contexts, normally HTTPS; localhost is generally treated as trustworthy for development. Storage APIs can also fail because of browser policies or quota limits. Detecting an API's presence is a first check, not proof that every operation will succeed.

const capabilities = {
  broadcastChannel: 'BroadcastChannel' in globalThis,
  sharedWorker: 'SharedWorker' in globalThis,
  serviceWorker: 'serviceWorker' in navigator,
  webLocks: 'locks' in navigator,
  indexedDB: 'indexedDB' in globalThis,
};

3. BroadcastChannel

BroadcastChannel is the simplest general-purpose API for same-origin cross-tab messaging.

What it is, and why use it?

It is a browser-managed publish/subscribe channel:

A publisher sends an event to a named channel.
Subscribers create a channel object with the same name and listen.
The publisher does not need a reference to each subscriber.

Use it when independent tabs need small, live notifications. Unlike polling, receivers do not repeatedly ask, "Did something change?"

The channel name is a routing label, not a password. Anyone running code in the same eligible origin/partition can open that channel.

Tab A ─┐
Tab B ─┼── channel: "app-events"
Tab C ─┘

Basic example

const channel = new BroadcastChannel('app-events');

channel.addEventListener('message', event => {
  console.log('Received:', event.data);
});

channel.postMessage({
  type: 'cart:item-added',
  payload: { productId: 'P-100', quantity: 1 },
});

// When this tab no longer needs the channel:
channel.close();

Messages are delivered asynchronously. postMessage() returning means the send operation did not throw; it is not an acknowledgement that another tab received or applied the event.

The sending channel object does not receive its own message. Other eligible channel objects can receive it, including a second channel object in the same page. Update the sender's UI directly, or deliberately provide local delivery in a wrapper.

Structured clone means the browser copies supported values, such as plain objects, arrays, and dates. It does not send a live reference to the sender's object. Functions and DOM elements cannot be sent this way, and changing your original object afterward does not change the receiver's copy.

Try it: two tabs, no backend required

Open two ordinary tabs at the same application origin, such as your local development server. Run this in the DevTools console of both tabs:

const demoChannel = new BroadcastChannel('cart-learning-demo');

demoChannel.onmessage = event => {
  console.log('Another tab announced:', event.data);
};

Then run this in Tab A:

demoChannel.postMessage({
  type: 'cart:invalidated',
  cartId: 'C-900',
});

Tab B logs the object; Tab A's sending object does not. Open Tab C afterward and run the listener setup: it will not receive that earlier message, because the channel has no history. Send again to reach both B and C.

When finished, run demoChannel.close() in each tab. This experiment demonstrates delivery, not real cart storage.

Better application example: save first, notify second

Suppose the cart contains two books. Tab A adds a third book:

sequenceDiagram
    actor User
    participant A as Tab A - products
    participant API as Cart API
    participant B as Tab B - cart
    User->>A: Add one book
    A->>API: POST cart item
    API-->>A: Saved cart, revision 17
    A->>A: Render confirmed cart
    A-->>B: Broadcast cart:invalidated
    B->>API: GET current cart
    API-->>B: Cart with three books, revision 17
    B->>B: Render current cart

The important ordering is commit, then notify. Broadcasting before the save completes could make Tab B fetch the old cart. If the save fails, show an error in Tab A rather than broadcasting a successful change.

Why announce an invalidation instead of saying "increase your count by one"? Tab B might have missed an earlier increment, or another device might have edited the cart. Reading the current cart repairs both problems.

On initial load and when a tab becomes active again, also refresh or check the cart revision. Recovery must not depend on receiving every broadcast.

What it gives you

One-to-many delivery to listening contexts
Structured-clone payloads, not JSON-only strings
No need to know which tabs exist
No mutation of persistent browser storage
Simple lifecycle and small API surface

What it does not give you

Durable history or replay
Delivery acknowledgement
Guaranteed delivery to sleeping, frozen, or closed tabs
Cross-origin communication
Communication across separate browser instances
A central owner for shared state or one shared WebSocket

Delivery semantics

Treat it as best-effort notification:

Update the authoritative state.
Broadcast that something changed.
Receivers re-read or reconcile the source of truth.

For example, send cart:invalidated rather than assuming a full cart snapshot reached every tab.

4. The localStorage Storage Event

Changing localStorage in one tab produces a storage event in other same-origin tabs.

What it is, and why use it?

localStorage is a small persistent string key/value store. The storage event tells other eligible pages that a value changed; it was not originally designed as a message broker.

Imagine writing a note on a shared noticeboard. Other rooms are notified about the edit, but the room making the edit already knows what it wrote.

This makes it useful for a low-frequency fallback, such as "theme changed to dark." It is a poor fit for mouse movements or hundreds of live updates per second because writing storage is synchronous.

const EVENT_KEY = 'app:cross-tab-event';

window.addEventListener('storage', event => {
  if (event.key !== EVENT_KEY || event.newValue === null) return;

  const message = JSON.parse(event.newValue);
  console.log('Received:', message);
});

function publish(message) {
  localStorage.setItem(
    EVENT_KEY,
    JSON.stringify({
      ...message,
      id: crypto.randomUUID(),
      sentAt: Date.now(),
    })
  );

  localStorage.removeItem(EVENT_KEY);
}

Important behavior

The tab that calls setItem does not receive its own storage event.
Values are strings, so serialization is required.
localStorage operations are synchronous and can block the main thread.
Storage can be unavailable or restricted.
Reusing an identical value may not produce the change behavior you expect; include a unique ID.

In the example, setItem creates a change carrying the message, and removeItem removes the temporary value. Receivers ignore the removal event because its newValue is null. The unique ID makes each written value different.

Removing the value does not turn this into a durable queue. A tab opened later cannot retrieve the old signal. For an actual preference, store theme = dark separately so new tabs can read the current preference on startup.

The snippet assumes valid JSON and available storage to keep the mechanism visible. Application code must catch malformed JSON and storage failures at the transport boundary, report the error, and use an explicit recovery path. Also check event.storageArea === localStorage when the listener must exclude sessionStorage events.

sessionStorage is not an arbitrary cross-tab substitute: it is scoped to a top-level browsing context, with sharing limited to eligible frames within that context.

When to use it

Compatibility fallback when BroadcastChannel is unavailable
Low-frequency signals such as logout, theme changes, or cache invalidation
Cases where the persisted value itself is useful

When not to use it

High-frequency events
Large payloads
Streaming updates
Secrets or authentication tokens
A queue requiring reliable delivery

5. window.postMessage and MessageChannel

`window.postMessage`

What: a way to send a message to a window you already have a reference to.

Why: a host page and a payment iframe may intentionally use different origins. They cannot share a BroadcastChannel, but can exchange a narrow, validated message contract through postMessage.

Unlike a broadcast, this is addressed communication: "send this to that popup," not "tell every tab listening on this channel."

Use postMessage when contexts have a direct relationship:

Parent page and iframe
Window and popup opened with window.open
Embedded micro frontend and host shell

const popup = window.open('/payment', 'payment-window');

popup?.postMessage(
  { type: 'payment:start', orderId: 'O-100' },
  'https://app.example.com'
);

Receiver:

window.addEventListener('message', event => {
  if (event.origin !== 'https://app.example.com') return;
  if (event.source !== window.opener) return;

  const message = event.data;
  if (message?.type === 'payment:start') {
    startPayment(message.orderId);
  }
});

Never use '*' as targetOrigin for sensitive messages. Validate origin, source, message type, and payload.

The popup example shows message routing, not a complete startup protocol. Sending immediately after window.open() can race with navigation and listener installation. In a real integration, the popup announces payment:ready; the opener validates that message's origin and source before sending payment:start.

sequenceDiagram
    participant H as Shop page
    participant P as Payment popup
    H->>P: Open popup
    P->>P: Install message listener
    P-->>H: payment:ready
    H->>H: Validate origin and source
    H->>P: payment:start with exact targetOrigin
    P->>P: Validate origin, source and payload
    P-->>H: payment:completed with order reference
    H->>H: Verify payment through backend

Why both checks? origin checks the sender's site; source checks which window sent it. A message from an unexpected window on an otherwise allowed site should not control this popup flow.

Treat payment:completed as a hint to check the order, not proof that money moved. The backend must verify payment status.

`MessageChannel`

MessageChannel creates two connected ports. Transfer one port to another context to establish a private point-to-point channel.

const channel = new MessageChannel();

channel.port1.onmessage = event => {
  console.log('Reply:', event.data);
};

iframe.contentWindow?.postMessage(
  { type: 'connect' },
  'https://app.example.com',
  [channel.port2]
);

channel.port1.postMessage({ type: 'ping' });

This is useful when a host wants to give one embedded context a dedicated communication port instead of sharing all traffic on window.

Think of the initial postMessage as introducing two people, and the transferred port as giving them a dedicated phone line. The iframe must accept the initial connection only after validating the sender, then attach a listener to event.ports[0].

When using addEventListener('message', ...) on a MessagePort, call port.start() to begin delivery. Assigning port.onmessage starts it automatically. Close the ports when the integration ends.

The port does not replace authentication: it is a capability handed to another context. Transfer it only to the intended receiver.

Limitation

Unrelated tabs do not automatically have references to each other. Use BroadcastChannel, a worker relay, or the backend for discovery and communication between arbitrary tabs.

6. SharedWorker

A SharedWorker is one worker context shared by multiple same-origin tabs or windows.

What problem does a shared worker solve?

With three independent tabs, your app may accidentally open three WebSockets and perform the same processing three times. That can be acceptable, but it costs connections and duplicates work.

A SharedWorker moves that work to a shared JavaScript runtime. Each tab connects through a MessagePort; the worker owns one socket and distributes incoming updates.

Without a SharedWorker	With a SharedWorker
Each tab owns a socket	The worker owns the socket
Each tab handles reconnects	The worker centralizes reconnect handling
In-memory state is separate	Worker-owned state is shared through messages
Closing a tab closes its socket	Closing one tab need not disconnect other clients

Eligible clients must agree on the worker script URL/name and compatible worker options, and be within the browser's sharing scope. Two unrelated worker scripts do not become one just because they serve the same app.

Shopping-app example: all tabs display order-status updates. The worker receives one order.shipped event and forwards it to each tab. Each tab decides how to render its own UI; the worker cannot directly update the DOM.

Tab A ── MessagePort ─┐
Tab B ── MessagePort ─┼── SharedWorker ── one WebSocket ── Server
Tab C ── MessagePort ─┘

Shared worker

// shared-connection-worker.js
const ports = new Set();
let socket;

function broadcast(message) {
  for (const port of ports) {
    port.postMessage(message);
  }
}

function ensureSocket() {
  if (socket && socket.readyState <= WebSocket.OPEN) return;

  socket = new WebSocket('wss://api.example.com/events');
  socket.addEventListener('message', event => {
    broadcast({
      type: 'server:event',
      payload: JSON.parse(event.data),
    });
  });
}

self.addEventListener('connect', event => {
  const [port] = event.ports;
  ports.add(port);
  port.start();
  ensureSocket();

  port.addEventListener('message', messageEvent => {
    if (messageEvent.data?.type === 'disconnect') {
      ports.delete(port);
      port.close();
    }
  });
});

Tab

const worker = new SharedWorker('/shared-connection-worker.js', {
  name: 'app-connection',
});

worker.port.start();
worker.port.addEventListener('message', event => {
  handleServerEvent(event.data);
});

window.addEventListener('pagehide', () => {
  worker.port.postMessage({ type: 'disconnect' });
  worker.port.close();
});

Best uses

One WebSocket shared by all tabs
Shared in-memory state
Request deduplication
One centralized coordinator
Cross-tab work distribution

Trade-offs

Support and lifecycle behavior must be verified for target browsers.
The worker can terminate when no clients remain.
It is not a durable data store.
Authentication refresh and reconnect logic still need careful design.
A broken worker can affect every connected tab.

The code above is a teaching skeleton. It does not reconnect a closed socket automatically, validate server messages, or reliably detect crashed clients. A pagehide disconnect is best-effort and a page restored from the back/forward cache needs to reconnect its port. Production ownership must account for these lifecycle cases.

7. Service Worker as a Relay

A service worker can find controlled windows and relay messages.

Why use this instead of a SharedWorker?

A service worker is primarily an event-driven network/offline intermediary, not an always-running shared process.

For example, the shopping app's background sync finishes uploading an offline cart operation. The service worker can notify controlled pages: "The cart cache changed." Those pages read the updated cache or server state.

Use this relay when your application already has service-worker responsibilities. Introducing a service worker only to send a simple theme event usually adds unnecessary lifecycle complexity.

Service worker

self.addEventListener('message', event => {
  event.waitUntil((async () => {
    const clients = await self.clients.matchAll({
      type: 'window',
      includeUncontrolled: false,
    });

    for (const client of clients) {
      if (client.id === event.source?.id) continue;
      client.postMessage(event.data);
    }
  })());
});

Page

navigator.serviceWorker.addEventListener('message', event => {
  handleCrossTabMessage(event.data);
});

async function publish(message) {
  const registration = await navigator.serviceWorker.ready;
  registration.active?.postMessage(message);
}

Best uses

Coordination already tied to offline/network behavior
Push notification fan-out to open pages
Cache invalidation after background sync
Messaging between controlled pages and the service worker

Important lifecycle rule

A service worker is event-driven and can be stopped between events. Do not treat its global variables as durable shared state. Store durable state in IndexedDB and use messages as signals.

Newly opened pages may not be controlled until navigation or clients.claim() is used during activation.

event.waitUntil() ties the relay's asynchronous work to the message event's lifetime. Merely making the listener async does not ask the browser to keep the service worker alive for that promise.

The page example assumes successful registration and activation. navigator.serviceWorker.ready can remain pending when no active registration is available, so complete setup and expose registration errors before offering worker-dependent features.

8. IndexedDB and Web Locks

These APIs solve coordination problems rather than replacing a message bus.

IndexedDB as shared durable state

All same-origin tabs in the same browser instance can read the same IndexedDB database.

What: an asynchronous browser database with records, indexes, and transactions.

Why: a message disappears after delivery; a saved draft should still exist when another tab opens later. IndexedDB lets that new tab read the current saved record without having heard the earlier event.

Here, "durable" means data outlives an individual page or worker, not that it is indestructible. Users can clear storage, browsers may evict it, and private browsing has different retention rules. Use the server for data that must survive loss of local storage.

Good pattern:

Tab A writes durable record to IndexedDB
  -> Tab A broadcasts { type: "record:changed", id: "R-100" }
  -> Tab B receives the signal
  -> Tab B reads the current record from IndexedDB

This avoids sending large payloads and lets a tab recover after missing a transient message.

Handle versionchange so old tabs close stale database connections during schema upgrades:

database.addEventListener('versionchange', () => {
  database.close();
  showReloadRequired();
});

Web Locks for single-owner work

The Web Locks API ensures that only one same-origin context holds a named lock at a time.

What: a browser-managed way for cooperating contexts to request exclusive access to named work.

Why: two tabs can both notice an offline queue is ready. Broadcasting "I am processing it" is not a lock: both tabs could announce that at the same time. An exclusive Web Lock serializes the cooperating owners.

async function tryBecomeSyncLeader(signal) {
  return navigator.locks.request(
    'background-sync-leader',
    { ifAvailable: true },
    async lock => {
      if (!lock) return false;

      await runSyncLoop(signal);
      return true;
    }
  );
}

The lock remains held until the callback's promise settles.

Here, ifAvailable: true means "try now; do not queue if another tab holds it." The callback receives null when it cannot acquire the lock. The signal is passed to the application-defined runSyncLoop to stop that loop cooperatively; it is not combined with ifAvailable in the lock options, because that combination is invalid.

If another tab needs to take over later, it must request the lock again, or use a queued request without ifAvailable. There is no automatic retry in this helper. Without ifAvailable, a lock-request signal can cancel a pending request; it does not automatically stop a callback that already acquired the lock.

sequenceDiagram
    participant A as Tab A
    participant L as Web Locks
    participant B as Tab B
    A->>L: Try background-sync-leader
    L-->>A: Lock granted
    B->>L: Try same lock with ifAvailable
    L-->>B: Not available - callback gets null
    A->>A: Process queue until stopped
    A->>L: Callback settles - release lock
    B->>L: Try again later
    L-->>B: Lock granted

Locks protect only cooperating clients in the applicable browser scope. They do not prevent a phone, another browser, or a direct API caller from submitting the same operation. Server-side idempotency is still needed for operations such as creating an order.

Use Web Locks for:

One tab performs polling
One tab refreshes a shared cache
One tab processes an IndexedDB queue
Avoiding concurrent migrations

Web Locks do not send results to other tabs. Pair them with BroadcastChannel or shared storage.

9. A Production Cross-Tab Event Bus

A wrapper gives the application one contract with a BroadcastChannel primary path and storage fallback.

Why add a wrapper?

Without one, every feature repeats transport selection, event names, subscription cleanup, and serialization. A shared bus lets feature code express intent:

Feature code: "publish cart:invalidated"
                 |
                 v
Bus: envelope + local delivery + chosen transport
                 |
                 v
Receiver: validate + dispatch to the cart subscriber

An envelope is metadata wrapped around the business payload. Think of a postal envelope: the event type says what it is, the ID identifies the delivery, and the schema version tells the receiver how to interpret its contents.

The implementation below is a production-oriented starting point, not a complete hardened bus. In particular, TypeScript types do not validate incoming data at runtime, and the basic envelope check below does not validate the allowed event types or their payloads. Apply the production additions before treating messages as trusted application events.

type EventMap = {
  'auth:logged-out': { reason: string };
  'cart:invalidated': { cartId: string };
  'theme:changed': { theme: 'light' | 'dark' };
};

type Envelope<K extends keyof EventMap = keyof EventMap> = {
  id: string;
  sourceId: string;
  type: K;
  version: 1;
  sentAt: number;
  payload: EventMap[K];
};

class CrossTabBus {
  #sourceId = crypto.randomUUID();
  #storageKey: string;
  #channel?: BroadcastChannel;
  #handlers = new Map<keyof EventMap, Set<(payload: never) => void>>();

  constructor(name: string) {
    this.#storageKey = `cross-tab:${name}`;

    if ('BroadcastChannel' in globalThis) {
      this.#channel = new BroadcastChannel(name);
      this.#channel.addEventListener('message', event => {
        this.#receive(event.data);
      });
    } else {
      window.addEventListener('storage', this.#onStorage);
    }
  }

  publish<K extends keyof EventMap>(type: K, payload: EventMap[K]) {
    const envelope: Envelope<K> = {
      id: crypto.randomUUID(),
      sourceId: this.#sourceId,
      type,
      version: 1,
      sentAt: Date.now(),
      payload,
    };

    // BroadcastChannel and storage events do not deliver to the sender.
    this.#receive(envelope);

    if (this.#channel) {
      this.#channel.postMessage(envelope);
      return;
    }

    localStorage.setItem(this.#storageKey, JSON.stringify(envelope));
    localStorage.removeItem(this.#storageKey);
  }

  subscribe<K extends keyof EventMap>(
    type: K,
    handler: (payload: EventMap[K]) => void
  ) {
    const handlers = this.#handlers.get(type) ?? new Set();
    handlers.add(handler as (payload: never) => void);
    this.#handlers.set(type, handlers);

    return () => handlers.delete(handler as (payload: never) => void);
  }

  close() {
    this.#channel?.close();
    window.removeEventListener('storage', this.#onStorage);
    this.#handlers.clear();
  }

  #onStorage = (event: StorageEvent) => {
    if (event.key !== this.#storageKey || event.newValue === null) return;
    this.#receive(JSON.parse(event.newValue));
  };

  #receive(envelope: Envelope) {
    if (!this.#isValid(envelope)) return;

    const handlers = this.#handlers.get(envelope.type);
    for (const handler of handlers ?? []) {
      handler(envelope.payload as never);
    }
  }

  #isValid(value: unknown): value is Envelope {
    if (typeof value !== 'object' || value === null) return false;
    const candidate = value as Partial<Envelope>;

    return (
      typeof candidate.id === 'string' &&
      typeof candidate.sourceId === 'string' &&
      typeof candidate.type === 'string' &&
      candidate.version === 1 &&
      typeof candidate.sentAt === 'number'
    );
  }
}

Production additions

Catch and report JSON parsing, serialization, channel creation, and storage errors; define how the UI recovers when messaging is unavailable.
Deduplicate recent message IDs.
Expire messages older than an allowed clock-skew window.
Validate each payload with a runtime schema.
Add event-version migration rules.
Record publish/receive/drop metrics.
Do not send secrets.
Use invalidation events when the payload can be re-read.

The wrapper deliberately delivers to subscribers in the publishing page too. Keep feature handlers idempotent and avoid handling the same local action both directly and through the subscription.

A fallback also needs a deployment-wide transport policy. A tab using only BroadcastChannel cannot hear a tab using only storage events. If mixed modes are possible, design and test a bridge or a common transport; dual publishing requires ID-based deduplication and loop prevention.

10. Common Cross-Tab Use Cases

10.1 Logout across tabs in one browser instance

bus.subscribe('auth:logged-out', () => {
  clearInMemoryAuthState();
  router.navigate('/login');
});

async function logout() {
  await api.logout();
  bus.publish('auth:logged-out', { reason: 'user-requested' });
}

The server must still invalidate the session. A cross-tab event improves UX but is not the security boundary.

The bus in Section 9 also invokes the sender's subscribers, so the logout handler clears and navigates the initiating tab as well. Doing that again in logout() would duplicate the local side effects. Surface a failed logout request explicitly rather than publishing a server-confirmed logout event.

10.2 Theme and preference sync

Persist the preference, then broadcast its new version.

function setTheme(theme) {
  localStorage.setItem('theme', theme);
  bus.publish('theme:changed', { theme });
}

10.3 Cache invalidation

bus.subscribe('cart:invalidated', ({ cartId }) => {
  queryClient.invalidateQueries({ queryKey: ['cart', cartId] });
});

Invalidation is safer than treating transient messages as the only copy of state.

10.4 Prevent duplicate notifications

Elect one owner to show system notifications while every tab can still update its visible UI.

10.5 Draft coordination

Store drafts in IndexedDB and broadcast document version changes. If two tabs edit simultaneously, use version checks, conflict resolution, or a collaborative protocol rather than last-write-wins by accident.

10.6 Single background poller

One tab holds a Web Lock and polls the server. It writes results to IndexedDB and broadcasts invalidations to other tabs.

10.7 Putting the shopping-app flow together

Situation	What to do	Why
User opens the cart in a new tab	Fetch the current cart	Earlier broadcasts are not replayed
Tab A successfully adds an item	Render the response, then broadcast an invalidation	Other tabs should read committed state
Tab B receives the invalidation	Re-fetch its active cart query	An increment alone cannot repair missed changes
Tab B wakes after being suspended	Revalidate on resume or visibility change	It may have missed notifications
Phone edits the same cart	Backend notifies authorized browser connections	A local channel cannot reach the phone
Two tabs retry the same checkout	Backend deduplicates with an operation/idempotency key	Local coordination is not a payment guarantee

If server events are also relayed locally, choose who owns the connection and deduplicate deliveries. Otherwise Tab B might receive the same change from both its own socket and Tab A's broadcast.

11. Leader Election and Single-Owner Work

Leader election is useful when only one tab should:

Poll the server
Maintain a connection
Process an offline queue
Display a system notification
Refresh shared data

What does "leader" mean here?

A leader is simply the context temporarily responsible for one task. It is not a special browser permission and does not need to own every part of the application.

For example, with four open tabs and a five-second polling interval, independent polling produces roughly 48 requests per minute. One polling leader produces roughly 12, then shares the results locally. This saves work but introduces a new requirement: another tab must take over when the leader disappears.

Three concepts help explain that requirement:

Heartbeat: a periodic "I am still here" signal. A missing heartbeat is suspicion, not proof that a tab has stopped.
Lease: ownership that expires unless renewed.
Fencing token: an increasing ownership number that lets the server reject a former owner's late writes.

Background throttling can delay a healthy tab. That is why a timer alone is not enough to establish exclusive ownership for critical work.

Prefer a platform coordinator

Use, in order:

SharedWorker when one shared runtime/connection is the design
Web Locks when one tab should temporarily own a task
A backend lease when ownership must span browser instances or devices

Why a localStorage lease is risky

A naive lease uses read-modify-write operations:

Tab A reads "no leader"
Tab B reads "no leader"
Tab A writes "A is leader"
Tab B writes "B is leader"
Both believe they won

localStorage does not provide a compare-and-swap transaction. A timestamp lease can reduce collisions but cannot provide strong distributed-lock guarantees.

Leases need fencing

For critical server-side work, issue a monotonically increasing fencing token:

leader A gets token 41
leader A pauses
leader B gets token 42
server rejects later writes carrying stale token 41

Do not rely on a browser tab as the exclusive owner of financially or operationally critical work. Put correctness on the server.

12. Cross-Browser Instances and Devices

What “cross-browser” can mean

Scenario	Browser-local APIs work?
Chrome Tab 1 and Tab 2 in the same Chrome instance	Yes
Two Chrome windows in the same Chrome instance	Yes
Chrome instance and Firefox instance	No
Two separate browser instances	No
Browser and mobile app	No
Laptop and phone	No

Browser-local APIs connect tabs and windows inside one browser instance. They do not create a direct channel to another browser instance. For example, a Chrome instance cannot open a BroadcastChannel directly to a Firefox instance.

Why doesn't using the same channel name work?

The channel name is looked up by the local browser within its own eligible scope. It is not a globally registered network address, and no message is automatically uploaded to your server.

Opening new BroadcastChannel('cart-events') in Chrome and Firefox is like tuning two disconnected intercom systems to "cart-events": the label matches, but there is no wire between the systems.

Likewise, signing into the same account does not automatically synchronize localStorage or IndexedDB. Your application must explicitly synchronize user data through its backend.

The shared meeting point

Use infrastructure both clients can reach:

Chrome tab ──┐
Firefox tab ─┼── HTTPS / WebSocket / SSE ── Backend ── shared state/event broker
Mobile app ──┘

Possible transports:

WebSocket for bidirectional real-time messaging
SSE for server-to-client streams
Short or long polling as fallback
Push notifications for background delivery
WebRTC for peer-to-peer data after server-based signaling

WebRTC does not remove the need for discovery, authentication, signaling, and usually a relay fallback.

Choose the transport by the direction of information

Transport	Simple mental model	Example	Main trade-off
WebSocket	An open two-way conversation	Collaborative cart or chat	Connection management, reconnects, and server capacity
SSE	A live server announcement feed	Order-status updates	Server-to-client only; client writes use normal HTTP
Polling	Ask "anything new?" on a schedule	Refresh cart every 30 seconds	Simpler, but stale between requests and wasteful when nothing changes
Web Push	A background notification via a push service	Notify that an order shipped	Permissions and delivery constraints; not a live state-sync guarantee

For a cart app, normal HTTP writes plus SSE notifications may be enough. A persistent bidirectional socket is useful only if both directions need it; "real-time" does not automatically mean WebSocket.

13. Server-Mediated Real-Time Architecture

Reference architecture

Browser instance/device A
        |
        | WebSocket + authenticated session
        v
Connection Gateway
        |
        +── Presence/connection registry
        |
        +── Event broker ── durable event store
        |
        +── Authorization service
        |
        v
Connection Gateway
        |
        v
Browser instance/device B

Connection identity

The backend cannot route an event merely because two clients are connected. It needs to know who each client represents and which resources that identity may access.

Model at least:

userId
sessionId
deviceId
connectionId
Optional tabId

One user can have many active connections. Route events to the intended scope:

user scope     -> every session/device for the user
session scope  -> tabs sharing one login session
device scope   -> one device
connection     -> one socket/tab

Example event

{
  "id": "evt_01J...",
  "type": "cart.updated",
  "version": 2,
  "sequence": 1842,
  "occurredAt": "2026-10-17T10:00:00Z",
  "scope": {
    "userId": "U-100"
  },
  "payload": {
    "cartId": "C-900",
    "revision": 17
  }
}

Client flow

Authenticate the connection.
Subscribe only to authorized scopes.
Receive an event with ID, version, and sequence.
Deduplicate by event ID.
Detect sequence gaps.
Re-fetch authoritative state or request replay.
Apply the update.
Persist the last processed cursor if required.

Concrete example: phone updates the cart, laptop follows

The phone sends an authenticated cart-update request.
The backend verifies ownership and commits cart revision 18.
The event system publishes cart.updated for that user's authorized connections.
The laptop receives the event and notices that its local cart is revision 17.
The laptop fetches revision 18 and refreshes the UI.

If the laptop is disconnected at step 3, the backend still has revision 18. Reconnecting and fetching the current cart restores correctness even without event replay.

An event broker fans events out between backend services or connection gateways. A durable event store retains events for later replay. These may be separate systems: using a broker does not automatically mean you have replayable history.

Also consider the gap between saving state and publishing its event. If the server crashes after the cart commit but before publishing, a notification can be lost. A transactional outbox records the state change and a pending event in the same database transaction; a separate publisher retries delivery. Consumers still need deduplication because retries can create duplicate notifications.

14. Reliability, Ordering and Replay

Local browser channels

BroadcastChannel, storage, and worker messages are useful notifications, but do not treat them as a durable event log.

Tabs can:

Open after an event was sent
Sleep or freeze
Crash
Miss a transient message
Process events at different times

Reliable-state pattern

Authoritative state: server or IndexedDB
Transient message: "state changed"
Recovery: read current version/snapshot

What can go wrong? A small timeline

sequenceDiagram
    participant A as Tab A
    participant API as Backend
    participant B as Tab B
    B->>B: Suspended with cart revision 16
    A->>API: Save revision 17
    API-->>A: Saved
    A--xB: Notification not observed while suspended
    B->>B: Resume later
    B->>API: Fetch current cart
    API-->>B: Revision 17
    B->>B: Replace stale view

The fix is not to make Tab A keep broadcasting forever. The fix is to make recovery read the source of truth.

Translate reliability terms into application behavior

Term	Meaning	Example response
Acknowledgement	Receiver confirms a particular stage completed	Distinguish "received" from "applied"
Retry	Send or perform an operation again	Reconnect and retry a failed fetch
Duplicate	The same event arrives more than once	Ignore a recently processed event ID
Idempotent handler	Repeating the handler does not create extra effects	Set cart revision 18 instead of blindly incrementing count
Ordering	The sequence in which changes are interpreted	Do not replace revision 18 with revision 17
Replay	Read retained events after a saved position	Resume after cursor 1842
Snapshot	A complete current view of state	Fetch the current cart when replay is unavailable

Acknowledgements and retries alone do not produce "exactly once" business effects. A receiver can apply an operation, crash before acknowledging, and then receive the retry. Protect the business operation with idempotency or transactional deduplication.

Event envelope

Include:

Unique message ID
Source context ID
Event type
Schema version
Timestamp
Entity revision or sequence
Payload

Ordering

Do not assume unrelated publishers create one global order.

For example, a slow request for cart revision 17 can finish after a faster request for revision 18. Compare revisions before applying a response, or use your data-fetching layer's cancellation/stale-result controls. Receiving the newer event first does not prevent an older HTTP response from overwriting the UI.

Use:

Per-entity revisions
Per-stream sequence numbers
Server-assigned order where required
Conflict-resolution rules

Deduplication

Maintain a bounded set of recent event IDs:

class RecentIds {
  #ids = new Map();

  constructor(maxSize = 1_000) {
    this.maxSize = maxSize;
  }

  has(id) {
    return this.#ids.has(id);
  }

  add(id) {
    this.#ids.set(id, true);
    while (this.#ids.size > this.maxSize) {
      this.#ids.delete(this.#ids.keys().next().value);
    }
  }
}

Reconnection

After reconnect:

Send the last processed cursor.
Replay missed events when supported.
If replay is unavailable or the gap is too large, fetch a fresh snapshot.
Resume live events from the new cursor.

Replay and live delivery must have a defined handoff. Otherwise an event can occur between "fetch snapshot" and "start listening" and fall into the gap. A server can return a snapshot with a cursor and replay events after that cursor, or the client can subscribe first and buffer events while fetching a versioned snapshot.

Sequence numbers must have a defined scope. A cart revision orders that cart; it does not order every event for every user. Gap detection is meaningful only for a stream whose sequence contract promises continuity for that subscriber.

15. Security and Privacy

Same origin is not the same as trusted

An XSS vulnerability in any same-origin tab can publish and receive the same cross-tab messages. Browser-local messaging does not protect against compromised code running under the origin.

Security rules

Validate every message type and payload at runtime.
Never put access tokens, refresh tokens, passwords, or sensitive personal data in cross-tab messages.
Treat channel names as identifiers, not secrets.
Validate event.origin and event.source for postMessage.
Use exact targetOrigin, not '*', for sensitive communication.
Authorize every server-side subscription and event.
Apply CSP, Trusted Types, and XSS defenses.
Minimize payloads and broadcast invalidations where possible.

Logout

Cross-tab logout is a UX optimization:

server revokes session/token
  -> initiating tab clears local state
  -> initiating tab broadcasts logout
  -> other tabs clear UI state

Other tabs must not remain authorized merely because a message was missed. The server remains authoritative.

16. Decision Guide

Which contexts must communicate?
  |
  +-- Same page/components
  |     -> in-memory state store/event bus
  |
  +-- Parent ↔ iframe or opener ↔ popup
  |     -> postMessage; MessageChannel for a dedicated port
  |
  +-- Arbitrary same-origin tabs
  |     |
  |     +-- Simple events
  |     |     -> BroadcastChannel
  |     |
  |     +-- Compatibility fallback
  |     |     -> storage event
  |     |
  |     +-- One shared socket/state owner
  |     |     -> SharedWorker
  |     |
  |     +-- Network/offline/push coordination
  |     |     -> Service Worker + IndexedDB
  |     |
  |     +-- Exactly one tab performs a task
  |           -> Web Locks + BroadcastChannel
  |
  +-- Different browser instances/devices
        |
        +-- Bidirectional real time
        |     -> WebSocket + backend broker
        |
        +-- Server-to-client only
        |     -> SSE
        |
        +-- Real time not required
              -> polling or normal API refresh

Comparison summary

Requirement	Recommended starting point
Logout/theme/cart sync across tabs	`BroadcastChannel`
Old-browser fallback for small events	`storage` event
Popup or iframe integration	`postMessage`
One WebSocket for all tabs	SharedWorker
Push/offline/cache coordination	Service Worker
Durable local shared state	IndexedDB
One tab performs polling	Web Locks
Chrome-to-Firefox communication	Backend WebSocket/SSE
Cross-device sync	Backend durable state + real-time delivery

17. Testing and Observability

Test matrix

Test at least:

Two same-origin tabs
A tab opened after previous events were sent
Sender tab closing during publish
Receiver sleeping/backgrounded
Browser refresh and reconnect
A separate browser instance
Chrome and Firefox
Offline then reconnect
Duplicate and out-of-order server events

Playwright multi-page example

test('logout propagates to another tab', async ({ context }) => {
  const firstTab = await context.newPage();
  const secondTab = await context.newPage();

  await firstTab.goto('/dashboard');
  await secondTab.goto('/dashboard');

  await firstTab.getByRole('button', { name: 'Log out' }).click();

  await expect(secondTab).toHaveURL(/\/login$/);
});

Useful metrics

Messages published/received/dropped by transport
Schema-validation failures
Active tabs/ports per SharedWorker
Leader changes and lease duration
WebSocket reconnect count
Sequence gaps and replay requests
Time from server event to tab application
Fallback usage by browser/version

Logging

Include messageId, sourceId, event type, schema version, and entity revision. Do not log sensitive payloads.

18. Interview Questions and Answers

How do two tabs communicate by default?

For arbitrary same-origin tabs, start with BroadcastChannel. Use the storage event as a simple compatibility fallback. Related windows or iframes can use postMessage.

Can BroadcastChannel communicate between Chrome and Firefox?

No. They are separate browser instances. Both clients must connect to shared backend infrastructure such as WebSocket, SSE, or polling.

Can Tab 1 and Tab 2 in the same Chrome instance use BroadcastChannel?

Yes, when both tabs use the same origin and eligible storage partition/profile. Create a BroadcastChannel with the same channel name in each tab. A normal tab and a private-browsing tab are not one shared channel environment.

How do you share one WebSocket across tabs?

Use a SharedWorker as the connection owner and connect each tab through a MessagePort. If SharedWorker is not available, elect one tab as leader or allow one connection per tab and manage the extra server load.

Is the storage event a message queue?

No. It is a notification that storage changed. It has no acknowledgement, replay, or durable queue semantics, and the writing tab does not receive its own event.

How do you prevent duplicate work across tabs?

Use Web Locks for same-origin tab coordination, a SharedWorker as a central owner, or a server-issued lease with fencing when correctness must span browsers or devices.

What happens if a tab misses an event?

Transient events should point to an authoritative source of truth. The tab re-reads IndexedDB or server state, or reconnects with a cursor and requests replay.

How do you secure cross-tab communication?

Validate payloads, avoid secrets, close channels on teardown, and remember that any same-origin XSS can access the channel. For postMessage, validate both origin and source. For backend events, authenticate and authorize every subscription.

What is the difference between coordination and communication?

Communication transfers information. Coordination decides who may perform an action. BroadcastChannel communicates; Web Locks coordinates. Production designs often use both.

Summary

Explain the design in plain English

Each tab has its own memory. I use a local message channel to tell other eligible tabs that data changed, not as the only copy of the data. They read the latest state from IndexedDB or the backend. If only one tab should do shared work, I use a coordinator such as Web Locks or a SharedWorker. Other browsers and devices synchronize through the backend. Every client can recover after missing a notification.

Use the smallest mechanism that matches the real boundary:

postMessage for related windows and iframes.
BroadcastChannel for simple same-origin cross-tab events.
storage events as a low-frequency fallback.
SharedWorker for shared in-memory state or one connection.
Service Worker for network, push, and offline coordination.
IndexedDB for durable local state.
Web Locks for one-owner work.
Backend WebSocket, SSE, or polling across browser instances and devices.

Browser-local messages are transient. Keep important state in an authoritative store, validate every message, and design for sleeping tabs, missed events, reconnection, deduplication, and versioning.

Frontend Memory Leaks — Detection, Diagnosis and Prevention

ZeeshanAli-0704 — Sat, 17 Oct 2026 10:04:54 +0000

Frontend Memory Leaks — Detection, Diagnosis and Prevention

A practical system-design guide to understanding browser memory, finding retained objects, preventing lifecycle leaks, and keeping long-running web applications stable.

What a Memory Leak Is
How Browser Memory Works
Memory Leak vs High Memory Usage
Common Frontend Leak Sources
Framework Lifecycle Patterns
A Repeatable Detection Workflow
Chrome DevTools Deep Dive
Automated Memory Regression Testing
Production Monitoring
Prevention by Design
System Design for Long-Running Apps
End-to-End Incident Case Study
Debugging Checklist
Interview Questions and Answers

1. What a Memory Leak Is

A memory leak occurs when an application no longer needs an object but a reachable reference still prevents the garbage collector from reclaiming it.

GC root
  |
  +-- window
       |
       +-- event listener
            |
            +-- callback closure
                 |
                 +-- old component state
                      |
                      +-- large response data

The old component is no longer visible, but the listener keeps its callback reachable. The callback keeps its closure reachable, and the closure keeps the component state and response data reachable.

In a long-running single-page application, repeated leaks usually produce a staircase:

Memory
  ^
  |                         ________
  |                  ______/
  |           ______/
  |    ______/
  |___/________________________________> Time
      open/close the same screen repeatedly

Garbage collection still happens, but the post-GC baseline rises after each cycle.

User-visible symptoms

Navigation becomes slower after the app has been open for a long time.
Typing, scrolling, and animation become janky.
The number of DOM nodes or event listeners keeps increasing.
Background CPU usage continues after leaving a screen.
Mobile browsers reload or terminate the tab.
The browser reports an out-of-memory crash.

2. How Browser Memory Works

JavaScript engines allocate most objects on a managed heap. The garbage collector starts from known roots and marks everything reachable from them.

Typical roots include:

window, document, and active DOM trees
Current call stacks
Module-level and global variables
Active timers and animation callbacks
Registered event listeners
Pending asynchronous callbacks
Open observers, workers, sockets, and subscriptions

Objects that cannot be reached from any root are eligible for collection.

Reachable from a root?  Yes  -> keep the object
                         No  -> reclaim the object

The collector does not understand business intent. It cannot know that an event listener belongs to a screen the user already closed. If the reference is valid, the object remains alive.

Retained size vs shallow size

Measurement	Meaning
Shallow size	Memory used by the object itself
Retained size	Memory that would become collectible if this object were removed

A small listener function can have a tiny shallow size but a huge retained size when its closure captures a large object graph.

Garbage collection is not immediate

Memory can remain high temporarily because the engine decides when to collect. A single measurement is therefore weak evidence. A reliable test repeats the same action, forces or waits for GC in a controlled environment, and compares the post-GC baseline.

JavaScript heap vs total browser memory

The JavaScript heap is only one part of a tab's memory footprint.

Memory category	Examples	Typical tools
JavaScript heap	Objects, arrays, closures, application stores	Heap snapshots, allocation profiler
DOM-related memory	Live and detached nodes, layout structures, event targets	Heap snapshots, DOM node counters
Browser/native memory	Decoded images, GPU textures, media buffers, network buffers	Chrome Task Manager, browser tracing
Worker/process memory	Web Workers, service workers, renderer processes	Chrome Task Manager, worker-specific profiling

A stable JavaScript heap does not prove that total memory is stable. An image gallery can release its JavaScript references while decoded images or GPU resources still create memory pressure. Use the measurement that matches the suspected resource.

3. Memory Leak vs High Memory Usage

High memory usage is not automatically a leak.

Situation	Leak?	Explanation
A photo editor intentionally keeps the active image in memory	No	The data is still needed
A cache grows to 100 entries and then evicts old entries	No	Memory is bounded
A cache grows forever as users navigate	Yes	Unbounded retention
A fetch callback retains a component until the request settles	Usually temporary	It becomes a leak risk when requests never settle or accumulate
Opening and closing a modal adds another listener every time	Yes	Old modal closures remain reachable
Memory rises during work and returns near baseline after GC	No	Normal allocation behavior

The key test

Ask:

After the feature returns to its original state, should these objects still exist?

If the answer is no but a retaining path still connects them to a GC root, the application has a leak.

A rising post-GC baseline is a strong signal, not proof by itself. Establish the root cause by combining:

Repeatable growth after the same lifecycle action
Heap or resource comparisons that identify what accumulates
A retaining path or owner keeping objects alive
Product evidence that those objects are no longer needed

4. Common Frontend Leak Sources

4.1 Forgotten event listeners

Why it leaks: Global targets such as window and document live for the entire page. An event target stores a strong reference to every registered callback. The callback's closure can retain component state, API responses, and DOM nodes after the component disappears.

window
  -> resize listener
  -> callback closure
  -> panelState
  -> old panel data and DOM

Leaking code:

function mountPanel(panelState) {
  window.addEventListener('resize', () => {
    panelState.recalculate();
  });
}

// Calling mountPanel() for every route visit adds another listener.
// Nothing removes the old callback.

How to fix it: Give the listener the same lifecycle as the panel. An AbortSignal is useful because the caller does not need to keep the callback reference required by removeEventListener.

function mountPanel(panelState) {
  const controller = new AbortController();

  window.addEventListener(
    'resize',
    () => panelState.recalculate(),
    { signal: controller.signal }
  );

  return () => controller.abort();
}

const destroyPanel = mountPanel(panelState);

// When the panel unmounts:
destroyPanel();

4.2 Timers and animation frames

Why it leaks: The scheduler retains the timer or animation callback while it remains active. That callback retains everything in its closure. An interval or recursive animation loop can therefore keep an entire destroyed screen reachable and continue consuming CPU.

timer scheduler
  -> interval callback
  -> loadUpdates closure
  -> old screen store

Leaking code:

function mountActivityFeed(feedStore) {
  setInterval(() => {
    feedStore.refresh();
  }, 5_000);

  requestAnimationFrame(function render() {
    feedStore.renderProgress();
    requestAnimationFrame(render);
  });
}

How to fix it: Store every timer/frame ID and cancel it when the owner is destroyed. For a recursive animation loop, guard against scheduling the next frame after disposal.

function startPolling(loadUpdates) {
  const intervalId = setInterval(loadUpdates, 5_000);
  let disposed = false;
  let frameId;

  function renderFrame() {
    if (disposed) return;
    renderProgress();
    frameId = requestAnimationFrame(renderFrame);
  }

  frameId = requestAnimationFrame(renderFrame);

  return () => {
    disposed = true;
    clearInterval(intervalId);
    cancelAnimationFrame(frameId);
  };
}

Recursive setTimeout, requestIdleCallback, and library schedulers require the same ownership discipline.

4.3 Detached DOM nodes

Why it leaks: Removing an element from the document only removes it from the live DOM tree. If JavaScript still references that element, the garbage collector must keep the element, all of its children, attached listeners, and related closures.

Leaking code:

const retainedNodes = [];

function removeCard(card) {
  card.remove();
  retainedNodes.push(card);
}

// retainedNodes -> detached card -> child nodes/listeners/state

How to fix it: Do not store removed nodes in long-lived collections. If a registry is necessary, delete the entry during teardown. Use WeakMap when metadata should follow the node without keeping it alive.

const metadataByCard = new WeakMap();

function registerCard(card, metadata) {
  metadataByCard.set(card, metadata);
}

function removeCard(card) {
  card.remove();
  // No long-lived strong reference remains; the WeakMap does not keep card alive.
}

The retaining reference can also hide inside a closure, debugging registry, third-party widget, or stale virtualized-list cache. Use the heap snapshot's Retainers panel rather than assuming remove() releases everything.

4.4 Subscriptions and event buses

Why it leaks: A publisher normally outlives its subscribers. Its subscriber collection holds each callback, and each callback can retain the destroyed component or route store.

Leaking code:

function mountDashboard(eventBus, dashboardStore) {
  eventBus.subscribe('metrics:update', metrics => {
    dashboardStore.update(metrics);
  });
}

// eventBus -> subscriber callback -> dashboardStore

How to fix it: Make subscription return an idempotent unsubscribe function and invoke it during teardown.

function mountDashboard(eventBus, dashboardStore) {
  return eventBus.subscribe('metrics:update', metrics => {
    dashboardStore.update(metrics);
  });
}

const unsubscribe = mountDashboard(eventBus, dashboardStore);

// When the dashboard unmounts:
unsubscribe();

Returning an unsubscribe function is safer than requiring callers to reconstruct the original topic and callback. Development diagnostics should expose subscriber counts so tests can assert that they return to baseline.

4.5 Observers

Why it leaks: Observer objects retain their callbacks and can retain observed targets or records. If the observer is owned by a destroyed screen but never disconnected, its callback closure and associated state remain reachable.

IntersectionObserver
ResizeObserver
MutationObserver
PerformanceObserver

Leaking code:

function observeChart(element, chartModel) {
  const observer = new ResizeObserver(() => {
    chartModel.resize(element.clientWidth);
  });

  observer.observe(element);
  // observer and chartModel have no teardown path
}

How to fix it: Return cleanup from the setup function. Use unobserve(element) when only one target ends, or disconnect() when the whole observer owner ends.

function observeChart(element, chartModel) {
  const observer = new ResizeObserver(() => {
    chartModel.resize(element.clientWidth);
  });

  observer.observe(element);
  return () => observer.disconnect();
}

const stopObserving = observeChart(element, chartModel);
stopObserving();

4.6 WebSockets, streams, workers, and channels

Why it leaks: These resources are designed to outlive a single task. They retain event handlers, queues, buffers, execution contexts, and sometimes operating-system resources until explicitly closed.

Leaking code:

function mountLiveView(url, viewStore) {
  const socket = new WebSocket(url);
  const worker = new Worker('/workers/parser.js');

  socket.addEventListener('message', event => {
    worker.postMessage(event.data);
  });

  worker.addEventListener('message', event => {
    viewStore.add(event.data);
  });

  // Navigating away does not close either resource.
}

How to fix it: Assign one lifecycle owner and close every resource during teardown.

function mountLiveView(url, viewStore) {
  const socket = new WebSocket(url);
  const worker = new Worker('/workers/parser.js');
  const channel = new BroadcastChannel('updates');

  worker.addEventListener('message', event => {
    viewStore.add(event.data);
  });

  return () => {
    socket.close(1000, 'screen disposed');
    worker.terminate();
    channel.close();
  };
}

Also release readers, stream locks, media tracks, and third-party SDK clients when their scope ends.

4.7 Unbounded collections and caches

Why it leaks: A module-level Map, Set, array, history, or queue is reachable for the lifetime of the application. If entries are never evicted, every visited entity remains reachable even when the UI no longer needs it.

Leaking code:

const responsesByUrl = new Map();

async function cachedFetch(url) {
  if (!responsesByUrl.has(url)) {
    responsesByUrl.set(url, await fetch(url).then(response => response.json()));
  }
  return responsesByUrl.get(url);
}

module scope
  -> responsesByUrl
  -> every URL ever visited
  -> every response object

Every cache needs:

A maximum size or memory budget
An eviction policy such as LRU or TTL
Invalidation rules
Metrics for entries, bytes, hit rate, and evictions

TTL alone does not guarantee bounded memory. Expired entries can remain allocated until something reads them or a cleanup job removes them. Enforce a maximum entry or byte limit and actively sweep expired entries.

Treat concurrent request deduplication as a separate concern. Without an in-flight request map, two simultaneous misses for the same key can allocate duplicate responses and perform duplicate network work.

How to fix it: Enforce a hard bound and actively remove expired entries. The following example uses insertion order as a simple LRU approximation:

class BoundedCache {
  #entries = new Map();

  constructor(maxEntries, ttlMs) {
    this.maxEntries = maxEntries;
    this.ttlMs = ttlMs;
  }

  get(key) {
    const entry = this.#entries.get(key);
    if (!entry) return undefined;

    if (entry.expiresAt <= Date.now()) {
      this.#entries.delete(key);
      return undefined;
    }

    this.#entries.delete(key);
    this.#entries.set(key, entry);
    return entry.value;
  }

  set(key, value) {
    this.#entries.delete(key);
    this.#entries.set(key, {
      value,
      expiresAt: Date.now() + this.ttlMs,
    });

    while (this.#entries.size > this.maxEntries) {
      const oldestKey = this.#entries.keys().next().value;
      this.#entries.delete(oldestKey);
    }
  }

  clear() {
    this.#entries.clear();
  }
}

For large values, enforce an estimated byte budget rather than only an entry count. Clear route- or workspace-scoped caches when their owner ends.

4.8 Closures retaining large state

Why it leaks: A closure retains referenced variables from its lexical scope. If a long-lived listener, timer, or registry stores that function, one seemingly small callback can retain a large report, store, or component tree.

Leaking code:

function createHandler(report) {
  return () => console.log(report.title);
}

If the returned handler is placed in a global registry, it retains the complete report, including a potentially large rows array.

How to fix it: Capture only the primitive or small object the callback needs, and remove the callback from its owner when finished.

function createHandler(report) {
  const { title } = report;
  return () => console.log(title);
}

const handler = createHandler(report);
shortcutRegistry.add(handler);

function destroy() {
  shortcutRegistry.delete(handler);
}

4.9 Blob URLs and media resources

Why it leaks: URL.createObjectURL() asks the browser to retain the underlying Blob until the URL is revoked. Media streams can keep camera, microphone, decoder, and buffer resources alive even after their UI disappears.

Leaking code:

const objectUrl = URL.createObjectURL(file);
preview.src = objectUrl;

// Removing preview alone does not revoke objectUrl.
preview.remove();

How to fix it: Revoke Blob URLs, stop media tracks, pause media, and clear element sources during teardown.

const objectUrl = URL.createObjectURL(file);
preview.src = objectUrl;

function destroyPreview() {
  preview.pause?.();
  mediaStream?.getTracks().forEach(track => track.stop());
  URL.revokeObjectURL(objectUrl);
  preview.removeAttribute('src');
  preview.load?.();
  preview.remove();
}

4.10 Pending asynchronous work

A promise that eventually settles is usually temporary retention rather than a permanent leak. The risk grows when operations are long-lived, repeatedly created, never settle, or are stored in another long-lived collection.

Why it can retain memory: The pending operation stores its continuation callback. That callback closes over the component state. Repeated obsolete requests can therefore retain multiple screen generations until they settle.

Leaking or wasteful code:

function mountProfile(userId, profileStore) {
  fetch(`/api/users/${userId}`)
    .then(response => response.json())
    .then(user => profileStore.setUser(user));

  // No cancellation or stale-result guard when userId changes.
}

How to fix it: Abort cancellable work during teardown and handle abort separately from real failures.

function loadUser(userId) {
  const controller = new AbortController();

  const promise = fetch(`/api/users/${userId}`, { signal: controller.signal })
    .then(response => {
      if (!response.ok) {
        throw new Error(`Failed to load user: ${response.status}`);
      }
      return response.json();
    })
    .catch(error => {
      if (error instanceof DOMException && error.name === 'AbortError') {
        return undefined;
      }
      throw error;
    });

  return {
    promise,
    cancel: () => controller.abort(),
  };
}

const request = loadUser(userId);
void request.promise.then(user => {
  if (user) profileStore.setUser(user);
});

// When the screen unmounts or userId changes:
request.cancel();

For non-cancellable operations, use a generation token so obsolete results are ignored. This protects correctness, but the underlying operation can still retain resources until it finishes.

5. Framework Lifecycle Patterns

5.1 React

Every effect that acquires a resource should release it.

useEffect(() => {
  const controller = new AbortController();
  const socket = new WebSocket(url);
  const intervalId = window.setInterval(refreshPresence, 10_000);

  window.addEventListener('online', refreshPresence, {
    signal: controller.signal,
  });

  return () => {
    controller.abort();
    socket.close();
    window.clearInterval(intervalId);
  };
}, [url]);

React Strict Mode intentionally runs an extra setup-cleanup cycle in development. Treat duplicate subscriptions or requests as evidence that cleanup is incomplete, not as a reason to disable Strict Mode.

Request ownership should also be explicit when dependencies change:

useEffect(() => {
  const controller = new AbortController();

  async function loadReport() {
    try {
      const response = await fetch(`/api/reports/${reportId}`, {
        signal: controller.signal,
      });

      if (!response.ok) {
        throw new Error(`Failed to load report: ${response.status}`);
      }

      setReport(await response.json());
    } catch (error) {
      if (error instanceof DOMException && error.name === 'AbortError') {
        return;
      }

      reportError(error);
    }
  }

  void loadReport();
  return () => controller.abort();
}, [reportId]);

Cancellation stops obsolete work when possible. For an operation that cannot be cancelled, use a generation token or stale-result guard so an old response cannot update the current screen. Ignoring a stale result protects correctness; cancellation additionally releases resources and avoids wasted work.

Common React leak risks:

Effects without cleanup
Effects that rerun because dependencies are unstable
Query caches with unlimited retention
Portals or imperative widgets not destroyed on unmount
External stores that never unsubscribe

5.2 Vue

import { onMounted, onUnmounted } from 'vue';

let observer: ResizeObserver;

onMounted(() => {
  observer = new ResizeObserver(updateLayout);
  observer.observe(container.value);
});

onUnmounted(() => {
  observer.disconnect();
});

5.3 Angular and RxJS

import { DestroyRef, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';

const destroyRef = inject(DestroyRef);

updates$
  .pipe(takeUntilDestroyed(destroyRef))
  .subscribe(updateView);

Prefer lifecycle-aware subscription operators over manually maintained subscription arrays.

5.4 Framework-independent ownership

The same rule applies everywhere:

setup/acquire                     cleanup/release
---------------------------------------------------------------
addEventListener                  removeEventListener / abort
setInterval                       clearInterval
requestAnimationFrame            cancelAnimationFrame
subscribe                         unsubscribe
observe                           disconnect
new WebSocket                     close
new Worker                        terminate
createObjectURL                   revokeObjectURL
open stream/reader                cancel/releaseLock

6. A Repeatable Detection Workflow

Do not start by staring at a large heap snapshot. First create a controlled reproduction.

Diagnostic decision tree

Does the post-GC JavaScript heap grow after a repeated flow?
  |
  +-- Yes -> Compare heap snapshots
  |           |
  |           +-- Detached nodes grow -> inspect DOM retainers/listeners
  |           +-- One constructor grows -> inspect retaining paths
  |           +-- Arrays/Maps grow -> inspect cache and store ownership
  |
  +-- No -> Does total tab memory still grow?
              |
              +-- Images/media-heavy -> inspect decoded media and buffers
              +-- Canvas/WebGL -> inspect GPU resources and explicit disposal
              +-- Workers grow -> profile and terminate worker lifecycles

Do you know exactly when allocations occur?
  |
  +-- Yes -> Allocation instrumentation on timeline
  +-- No  -> Performance Monitor first, then narrow the flow

Step 1: Define a cycle

Choose an action that should return the app to the same state:

Open the dashboard.
Open and close a detail panel.
Navigate away.
Return to the starting screen.

Step 2: Warm up

Run the cycle once or twice so lazy modules, caches, fonts, and one-time framework initialization do not pollute the measurement.

Step 3: Record a baseline

Track:

JavaScript heap size
DOM node count
Listener/subscription count where available
Active timers, workers, sockets, and observers
Application cache entry counts

Step 4: Repeat the cycle

Run it 10–20 times with the same data and timing.

Step 5: Force or wait for GC

In a controlled debugging session, use the DevTools garbage-collection button. In automation, use a browser launched with explicit GC support when available.

Step 6: Compare the post-GC baseline

Healthy applications may keep a small amount of warmed cache. A leak shows consistent growth proportional to cycle count.

Step 7: Find the retaining path

Once a leaking constructor or detached node is identified, inspect the shortest retaining path to the GC root. Fix the owner keeping the object alive rather than nulling arbitrary variables.

7. Chrome DevTools Deep Dive

7.1 Performance Monitor

Open DevTools Command Menu and choose Show Performance monitor.

Watch:

JS heap size
DOM nodes
Event listeners
CPU usage
Documents and frames

This is the fastest way to confirm a trend, but it does not identify the retaining reference.

7.2 Heap snapshots

Open Memory.
Select Heap snapshot.
Take a baseline snapshot.
Repeat the suspected action.
Force GC.
Take a second snapshot.
Choose Comparison.
Sort by positive delta or retained size.

Useful filters:

Detached for detached DOM trees
A known component or model constructor
(closure) for retained lexical scopes
Large Array, Map, or Set instances

The Retainers panel answers the most important question: why is this object still reachable?

7.3 Allocation instrumentation on timeline

Use this when you know when the leak occurs but not what is allocated.

Start recording.
Perform the action.
Stop recording.
Focus on allocations that survive GC.
Inspect their stack traces and retainers.

7.4 Allocation sampling

Sampling has lower overhead and is useful for broad allocation hotspots. It is less precise than instrumentation but better for longer sessions.

7.5 Chrome Task Manager

Open Chrome Task Manager with Shift+Esc to compare the tab's total memory footprint with JavaScript heap measurements. Total memory also includes DOM, images, GPU resources, media buffers, and browser internals.

7.6 Programmatic measurement

performance.measureUserAgentSpecificMemory() can provide a more complete measurement where supported, but it is experimental and requires cross-origin isolation.

async function readMemory() {
  if (!('measureUserAgentSpecificMemory' in performance)) {
    return null;
  }

  const result = await performance.measureUserAgentSpecificMemory();
  return result.bytes;
}

Do not make production correctness depend on this API.

8. Automated Memory Regression Testing

Memory tests are noisy, so test repeated growth rather than one absolute reading.

Use layered tests because each layer proves something different:

Test layer	What it verifies	What it does not prove
Unit	Cleanup callbacks run; counters and subscriptions return to baseline	Browser objects are collectible
Browser integration	Repeated navigation and teardown leave the expected UI/resource state	Absence of hidden retained objects
Memory regression	Post-GC trends, detached nodes, or retained constructors remain within budget	The root cause without snapshot analysis

No single heap-size threshold proves correctness. Treat a budget failure as a regression signal that triggers comparison and retaining-path analysis.

Browser test strategy

launch browser
  -> warm up application
  -> collect baseline
  -> run user flow N times
  -> request GC in test environment
  -> collect final measurement
  -> fail if retained growth exceeds budget

Example Playwright-style flow:

test('detail panel does not leak across repeated use', async ({ page }) => {
  await page.goto('/dashboard');

  for (let index = 0; index < 20; index += 1) {
    await page.getByRole('button', { name: 'Open details' }).click();
    await page.getByRole('button', { name: 'Close details' }).click();
  }

  const remainingDialogs = await page.locator('[role="dialog"]').count();
  expect(remainingDialogs).toBe(0);
});

DOM-count assertions do not prove the absence of leaks, but they provide a stable first guard. A dedicated Chromium test environment can add heap snapshots or Chrome DevTools Protocol metrics.

Good regression signals

Post-GC heap growth per cycle
Detached-node count
DOM node count after returning to baseline
Event-bus subscriber count
Active socket/worker count
Cache entries and estimated bytes

Avoid flaky tests

Warm up before measuring.
Use the same data on every cycle.
Disable unrelated polling and analytics.
Compare trends across several runs.
Keep generous budgets for engine noise.
Run deep memory tests on scheduled CI if they are too expensive for every pull request.

9. Production Monitoring

Production browsers do not expose the same deterministic controls as DevTools. Use indirect signals and feature-level telemetry.

Useful telemetry

Signal	What it can reveal
Session duration vs responsiveness	Long-session degradation
Route transitions vs heap where supported	Screen-specific growth
DOM node count sampled periodically	Detached or duplicated UI
Cache entries and estimated bytes	Unbounded application caches
Active sockets, workers, and subscriptions	Missing teardown
Long tasks and INP over session age	GC pressure and degraded interaction
Tab reloads or crash reports	Severe memory pressure

Sample sparingly

Memory and DOM measurements can be expensive. Sample a small percentage of sessions, avoid collecting user content, and aggregate values into buckets.

Correlate with lifecycle events

Include dimensions such as:

Route or feature
App version
Session age
Device-memory class
Number of repeated feature cycles

This makes it possible to identify patterns such as “heap grows after every workspace switch on version 4.2.”

10. Prevention by Design

10.1 Make resource ownership explicit

Every long-lived resource should have one owner responsible for cleanup.

interface Disposable {
  dispose(): void;
}

Composite ownership helps complex screens:

class Disposables {
  #cleanups = new Set<() => void>();
  #disposed = false;

  add(cleanup: () => void): () => void {
    if (this.#disposed) {
      cleanup();
      return () => {};
    }

    let active = true;
    const run = () => {
      if (!active) return;
      active = false;
      this.#cleanups.delete(run);
      cleanup();
    };

    this.#cleanups.add(run);
    return run;
  }

  dispose(): void {
    if (this.#disposed) return;
    this.#disposed = true;

    const cleanups = [...this.#cleanups].reverse();
    this.#cleanups.clear();
    const errors: unknown[] = [];

    for (const cleanup of cleanups) {
      try {
        cleanup();
      } catch (error) {
        errors.push(error);
      }
    }

    if (errors.length > 0) {
      throw new AggregateError(errors, 'One or more cleanup operations failed');
    }
  }
}

This disposer is idempotent, releases resources in reverse acquisition order, executes late registrations immediately, and continues cleanup after an individual failure. Callers must report or handle the aggregate error according to the application's error policy.

10.2 Prefer bounded data structures

Set limits for:

API response caches
Infinite-scroll pages
Chat messages retained in memory
Analytics queues
Deduplication sets
Undo/redo history
Image and media buffers

10.3 Use weak references only for the right problem

WeakMap and WeakSet are useful when metadata should not keep object keys alive.

const metadataByElement = new WeakMap();
metadataByElement.set(element, { measuredAt: Date.now() });

They are not general-purpose caches:

Entries are not enumerable.
Collection timing is nondeterministic.
They do not replace explicit cleanup for listeners, timers, or resources.

Avoid relying on FinalizationRegistry for correctness. Finalizers may run late or not before process termination.

10.4 Make cleanup testable

Expose diagnostics in development:

const diagnostics = {
  activeSubscriptions: 0,
  activeSockets: 0,
  cacheEntries: 0,
};

Tests can assert that counts return to baseline after a feature is destroyed.

10.5 Review lifecycle in code review

When code acquires a resource, reviewers should look for the corresponding release in the same change.

11. System Design for Long-Running Apps

Memory management becomes an architectural concern for dashboards, editors, communication tools, trading interfaces, and kiosk applications that remain open for hours or days.

Bound the in-memory working set

Server history
     |
     v
Paginated query cache --evict--> bounded recent pages
     |
     v
Normalized entity cache --TTL/LRU--> active entities
     |
     v
Virtualized viewport --> only visible DOM nodes

Separate durable state from view state

Durable data belongs in server storage or IndexedDB.
Query caches need stale and garbage-collection policies.
View state should disappear when its owning route or component disappears.
Large binary data should be streamed or persisted instead of retained indefinitely.

Design reset boundaries

Some applications benefit from explicit reset points:

Clear workspace-scoped stores when switching workspaces.
Dispose editor models when tabs close.
Drop old chat pages outside the navigation window.
Recreate third-party widgets that do not expose reliable cleanup.

Establish budgets

Illustrative budgets for a long-running SPA:

Metric	Example target
Post-GC heap growth after 20 repeated flows	Less than 5 MB
Detached DOM nodes after route exit	0
Event-bus subscriptions after route exit	Return to baseline
In-memory chat messages	Last 500 per active channel
Undo history	Last 100 operations or 20 MB

Budgets must reflect product behavior and target devices. The important property is that growth is intentional and bounded.

12. End-to-End Incident Case Study

Symptom

Users report that an enterprise reporting dashboard becomes slow after switching workspaces for 30–60 minutes. Production telemetry shows worsening INP as session age and workspace-switch count increase.

Reproduction

The team creates one controlled cycle:

Open workspace A.
Open and close the report drawer.
Switch to workspace B.
Return to workspace A.

After warm-up, the flow is repeated 20 times. The post-GC JavaScript heap rises by roughly 3 MB per cycle, and detached DOM nodes increase.

Isolation

Heap snapshot comparison shows:

20 retained ReportDrawerModel instances
A detached drawer subtree for each cycle
One global keydown listener per old drawer

The shortest retaining path is:

window
  -> EventListener("keydown")
  -> onShortcut closure
  -> ReportDrawerModel
  -> report rows
  -> detached drawer DOM

Root cause

The drawer registers a global keyboard shortcut with an inline closure. Closing the drawer removes the DOM but never removes the listener. The closure retains the model, report data, and detached subtree.

Fix

function mountReportDrawer(model: ReportDrawerModel) {
  const controller = new AbortController();

  window.addEventListener(
    'keydown',
    event => {
      if (event.key === 'Escape') model.close();
    },
    { signal: controller.signal }
  );

  return () => controller.abort();
}

The workspace owner stores and invokes the returned cleanup before replacing its drawer model.

Regression coverage

Unit test: disposing the drawer returns the shortcut-listener counter to baseline.
Browser integration test: opening and closing the drawer 20 times leaves no dialogs or drawer models registered.
Scheduled memory test: the repeated workspace flow stays within an illustrative post-GC growth budget and produces zero detached drawer roots.

Rollout verification

The fix is released behind a feature flag. The team compares:

Heap trend by app version
INP by session age
Detached-node diagnostics from sampled internal sessions
Active drawer/listener counters

After rollout, memory returns near the warmed baseline and long-session INP no longer degrades with workspace switches.

Principal-level lesson

The durable fix is not merely removeEventListener. The team establishes an ownership contract for global resources, adds lifecycle counters, creates a repeated-flow regression test, and verifies the outcome in production.

13. Debugging Checklist

Reproduction

[ ] Can the issue be reproduced with one repeated user flow?
[ ] Was the application warmed up before measuring?
[ ] Does the post-GC baseline rise after each cycle?

Retention

[ ] Are detached DOM nodes increasing?
[ ] Do heap comparisons show a growing constructor count?
[ ] What is the shortest retaining path to a GC root?
[ ] Is a closure retaining more state than necessary?

Lifecycle resources

[ ] Are global event listeners removed?
[ ] Are timers and animation frames cancelled?
[ ] Are observers disconnected?
[ ] Are event-bus and store subscriptions removed?
[ ] Are requests aborted when no longer useful?
[ ] Are WebSockets, channels, workers, and streams closed?
[ ] Are Blob URLs revoked and media tracks stopped?

Data structures

[ ] Are caches, queues, maps, sets, and histories bounded?
[ ] Do route- or workspace-scoped stores reset?
[ ] Are virtualized items and old pages evicted?

Verification

[ ] Does the same repeated flow return close to baseline after the fix?
[ ] Is there a regression test or diagnostic counter?
[ ] Are production metrics available for long sessions?

Incident response

[ ] Is there a short-term mitigation for affected users?
[ ] Is the leaking feature isolated behind a flag or rollback?
[ ] Is the retaining owner documented in the root-cause analysis?
[ ] Does regression coverage reproduce the original lifecycle?
[ ] Are rollout metrics segmented by release version and session age?

14. Interview Questions and Answers

What is a frontend memory leak?

A frontend memory leak is unintended retention: the UI no longer needs an object, but a reachable reference from a GC root prevents collection. Common roots include global listeners, active timers, subscriptions, sockets, observers, and module-level collections.

How do you prove an application leaks?

Define a repeatable flow that returns to the same state, warm up the app, take a baseline, repeat the flow, force or wait for GC, and compare the new baseline. Consistent post-GC growth is stronger evidence than one high memory reading.

What is a detached DOM node?

It is a node removed from the live document but still referenced by JavaScript. The reference can keep the entire detached subtree and associated closures alive.

Why can a small callback retain a large amount of memory?

Its closure may reference a component, store, or large response object. The callback's shallow size is small, but its retained size includes everything that would become collectible if the callback were released.

Does every unresolved promise cause a memory leak?

No. A pending promise retains its callbacks until it settles, which is often temporary. It becomes a leak risk when operations never settle, are created repeatedly, or are retained by another long-lived structure.

When should you use `WeakMap`?

Use it for metadata keyed by objects when the metadata must not keep the keys alive. Do not use it as a replacement for resource cleanup or as an observable cache.

How would you design a leak-resistant event bus?

Return an unsubscribe function, support AbortSignal, remove empty topic sets, optionally expose subscriber counts in development, and test that counts return to baseline after component teardown.

How do you prevent memory leaks in long-running SPAs?

Make ownership explicit, pair every acquisition with cleanup, bound all caches and histories, virtualize large views, reset scoped state, monitor long-session behavior, and automate repeated-flow regression tests.

A dashboard heap grows after every workspace switch. How do you isolate the cause?

Warm up the app, define a repeatable workspace-switch cycle, compare post-GC heap and DOM counts, then compare snapshots by constructor delta. Follow the shortest retaining paths for workspace-scoped models and detached nodes. Also inspect global listeners, subscriptions, query caches, and workers owned by the previous workspace.

How do you distinguish a leak from a legitimate cache?

A legitimate cache has an owner, purpose, maximum size or byte budget, eviction and invalidation rules, and observable metrics. Its growth should plateau. A leak retains data without a continuing product need or grows beyond its declared policy.

How would you enforce lifecycle correctness across a large codebase?

Provide standard disposable abstractions, lifecycle-aware framework hooks, bounded cache utilities, and diagnostics counters. Add linting or review rules for resource acquisition, test teardown behavior, run repeated-flow browser tests, and monitor long-session production signals.

Why might total memory rise while the JavaScript heap remains stable?

Decoded images, canvas or WebGL resources, GPU textures, media buffers, DOM/layout structures, network buffers, and worker processes can grow outside the measured JavaScript heap. Use Chrome Task Manager or browser tracing to investigate the relevant category.

How do you detect memory regressions in CI without making tests flaky?

Warm up first, use deterministic data, disable unrelated background activity, repeat the same flow, compare trends rather than a single sample, and use generous evidence-based budgets. Keep stable lifecycle assertions in pull-request tests and run expensive heap analysis in a controlled scheduled job.

Summary

Memory leaks are ownership failures. The garbage collector can reclaim only objects that are unreachable; it cannot infer that a listener, cache entry, socket, or detached node is no longer useful.

The reliable approach is:

Reproduce a flow that returns to baseline.
Confirm repeated post-GC growth.
Identify the retained object.
Follow its retaining path to the owner.
Fix lifecycle cleanup or bound the data structure.
Add a regression test and production signal.
Verify the rollout across release version, session age, and affected flows.

Idempotency Keys - The Double-Charge Trap

ZeeshanAli-0704 — Sat, 17 Oct 2026 07:53:54 +0000

The Problem

You click Pay. The server charges your card, but the response is lost on the way back (network drop, timeout, tab freeze). The UI thinks it failed, so you click Pay again and get charged twice.

A timeout means "I don't know what happened", not "payment failed".

The Idea

Idempotent = doing the same thing twice has the same effect as doing it once.

Action	Repeat it twice	Idempotent?
Set notifications to OFF	Still OFF	Yes
Add USD 50 to the balance	USD 100 added	No
Create a payment	Two charges	No, unless we add a key

An idempotency key is a unique ID for one payment attempt. The UI sends it with the request. If the same key arrives again, the backend says "I've already handled this one" and returns the saved result instead of charging again.

UI's job: create the key once, keep it, and resend the same key on every retry.
Backend's job: remember each key and its result, so repeats are not executed again.

Full Flow Diagram

Example: user pays USD 50 for order O100.

sequenceDiagram
    actor User
    participant UI as Browser UI
    participant SS as sessionStorage
    participant API as Backend
    participant DB as Database
    participant PSP as Payment Provider

    User->>UI: Click "Pay"
    UI->>SS: Key for O100?
    SS-->>UI: None
    UI->>UI: key = crypto.randomUUID() → K1
    UI->>SS: Save payment-key:O100 = K1
    UI->>UI: Disable Pay button, show "Processing..."

    UI->>API: POST /orders/O100/pay<br/>Idempotency-Key: K1
    API->>DB: Insert (user, K1, O100, processing)
    DB-->>API: Inserted (K1 is new)
    API->>PSP: Charge USD 50 (provider key derived from K1)
    PSP-->>API: Success, payment P900
    API->>DB: Update K1 → succeeded, result P900
    API--xUI: 200 OK (response LOST)

    UI->>UI: Timeout → show "Checking payment status..."
    UI->>SS: Read key for O100
    SS-->>UI: K1 (same key)
    UI->>API: POST /orders/O100/pay<br/>Idempotency-Key: K1 (retry)
    API->>DB: Find K1
    DB-->>API: K1 = succeeded, P900
    Note over API,PSP: Provider NOT called again
    API-->>UI: 200 OK, payment P900 (saved result)
    UI->>SS: Remove payment-key:O100
    UI-->>User: Show receipt ✅ (charged once)

Step-by-Step

Step 1: User clicks "Pay" — UI gets a key

The UI first checks whether this order already has a key (from an earlier attempt or before a refresh).

Key found → reuse it. This is a retry of the same payment.
No key → generate a new one with crypto.randomUUID().

payment-key:O100  →  K1   (e.g. "6f13d95a-e6c1-4bf2-9459-99b502098dc1")

Use crypto.randomUUID() — it is random and practically never collides. Do not use Date.now(), Math.random(), or the amount; two different payments could produce the same value.

Step 2: Save the key BEFORE sending the request

sessionStorage.setItem("payment-key:O100", key);

Save first, then send. If the page crashes or reloads mid-request, the key is still there and the next attempt reuses it.

Where to store on the UI:

Place	Survives refresh?	Use it?
Variable / React state	No	Only for the current screen
sessionStorage	Yes (same tab)	Recommended — cleared when the tab closes
localStorage	Yes (even after browser restart)	Avoid — leftover keys on shared devices, shared across tabs
Cookie	Yes	Avoid — sent with every request for no reason

Also disable the Pay button while the request is in flight. This stops accidental double clicks, but it is only a UX helper; the key is the real protection.

Step 3: Send the payment request with the key

POST /orders/O100/pay
Idempotency-Key: K1
Cookie: session=...   (user is logged in)

The UI sends only the order ID and key. The backend loads the amount from the order itself; never trust a price sent by the browser.

Step 4: Backend checks the key

Why does the backend store the key? Because the UI can't know whether the first request was charged — only the backend can remember.

The backend saves one row per key:

User	Key	Order	Status	Result
U1	K1	O100	processing → succeeded	P900

When a request arrives:

Backend finds...	Backend does
K1 not found	New payment: save `processing`, charge, save result, respond
K1 = `processing`	Another request is already charging → reply "in progress, check again" (e.g. `409`)
K1 = `succeeded` / `declined`	Return the saved result. Do not charge again
K1 exists but for a different order	Reject (e.g. `422`) — key misuse

The insert must be atomic (a unique constraint on user + key). If two identical requests arrive at the same moment, only one insert succeeds, so only one charge happens.

Step 5: Backend charges and saves the result

The backend calls the payment provider and passes its own provider idempotency key derived from K1, saved before the call. If the backend crashes after the provider charged but before saving the result, a retry reuses that provider key, so the provider returns the original charge instead of creating a new one.

Then it updates the row to succeeded with result P900 and responds.

Step 6: UI handles the response

What the UI gets	What it means	UI action	Key?
`200` success	Paid	Show receipt	Remove key
Card declined (clear failure)	Not charged	Show error, let user try again	Remove key; next try gets a new one
`409` in progress	Still charging	Show "Processing...", check again shortly	Keep
Timeout / network error / `5xx`	Unknown!	Show "Checking payment status...", retry	Keep

The key rule: only remove the key when you know the final outcome.

Step 7: Retry after timeout

The UI retries with the same K1 (a few times, with increasing delays like 1s, 2s, 4s).

Two possible cases, both safe:

First request never reached the backend → K1 is new → backend charges once now.
First request was already charged → K1 = succeeded → backend returns P900, no second charge.

That's the whole point: the UI doesn't need to know which case happened.

Step 8: User refreshes the page

flowchart TD
    A[Page loads / user clicks Pay] --> B{Key for O100 in sessionStorage?}
    B -- Yes --> C[Reuse the same key]
    B -- No --> D[Generate new key with crypto.randomUUID]
    D --> E[Save key in sessionStorage]
    C --> F[POST /orders/O100/pay with key]
    E --> F
    F --> G{Response}
    G -- Success --> H[Show receipt, remove key]
    G -- Declined --> I[Show error, remove key]
    G -- In progress / timeout / 5xx --> J[Show 'Checking...', keep key, retry later]
    J --> F

After refresh, the UI finds K1 in sessionStorage and sends the request with K1 again. The backend returns the saved result or "in progress" — never a second charge.

UI Code Example

Illustrative only; status codes depend on your API.

function getOrCreateKey(orderId) {
  const name = `payment-key:${orderId}`;
  let key = sessionStorage.getItem(name);
  if (!key) {
    key = crypto.randomUUID();
    sessionStorage.setItem(name, key); // save BEFORE sending
  }
  return key;
}

async function pay(orderId) {
  const key = getOrCreateKey(orderId);

  try {
    const res = await fetch(`/orders/${orderId}/pay`, {
      method: "POST",
      headers: { "Idempotency-Key": key },
      credentials: "include",
      signal: AbortSignal.timeout(15000),
    });

    if (res.ok) {
      sessionStorage.removeItem(`payment-key:${orderId}`);
      return { status: "paid", payment: await res.json() };
    }
    if (res.status === 402) {
      // Clear decline: not charged, a new attempt may use a new key
      sessionStorage.removeItem(`payment-key:${orderId}`);
      return { status: "declined" };
    }
    // 409 in progress, 5xx, etc.: outcome unknown, keep the key
    return { status: "unknown" };
  } catch {
    // Timeout or network error: outcome unknown, keep the key
    return { status: "unknown" };
  }
}

On "unknown", show "Checking payment status..." and call pay(orderId) again after a delay — it automatically reuses the same key.

sessionStorage can throw (e.g. storage full or blocked). In that case, keep the key in memory for this page and avoid letting the user start a fresh payment while one is unresolved.

When Is a New Key Needed?

Situation	Same key or new?
Timeout, network error, server error	Same
Page refresh during payment	Same (read from sessionStorage)
User double-clicks Pay	Same
Payment succeeded	No more payment needed
Card clearly declined, user tries again	New
User changes amount / card / order	New (old attempt must be finished first)
A different order	New

Simple rule: same intention → same key. New intention → new key.

Security Checklist

Store only the key in sessionStorage. Never store card number, CVV, or tokens.
The key is not a password. The backend must still check that the logged-in user owns order O100.
The backend scopes keys per user, so one user's key can't read another user's payment.
Never trust amount or status from the browser; the backend decides both.
Clear payment keys on logout.

What If sessionStorage Is Lost?

New tab, cleared storage, or another device → the UI generates a new key for the same order. The idempotency key can't catch this, so the backend needs one more rule:

An order that is already paid, or has a payment in progress, cannot start another charge.

Keys stop duplicate requests. Order rules stop duplicate payments for the same order. You need both.

System Design: Key Creation, Change Detection, and Cancellation

So far, one key = one payment. Real checkouts are messier: the user changes the cart, applies a coupon, or switches cards while a payment is unclear. This section designs a setup that answers three questions:

When should the UI create a key?
How do UI and backend detect that the payment details changed?
How is an old attempt safely cancelled so a new key can be used?

Core idea: a key belongs to a checkout snapshot

A key represents "pay for exactly this checkout". The checkout is identified by a small snapshot:

Snapshot field	Changes when...
`orderId`	A different order
`orderVersion`	Backend bumps it on any change to items, quantity, coupon, address, or total
`paymentMethodId`	User picks another saved card or method (an ID like `pm_123`, never the card number)

Same snapshot      → same intention → reuse the key
Different snapshot → new intention  → old attempt must be finished/cancelled, then a new key

orderVersion is the important part: the UI doesn't have to compare cart items itself. The backend increases the version whenever anything affecting the price changes.

Architecture

flowchart LR
    subgraph Browser
        UI[Checkout UI]
        KM[Key Manager]
        SS[(sessionStorage)]
        UI --> KM
        KM <--> SS
    end

    KM -->|Pay / Cancel + Idempotency-Key| GW[API Gateway<br/>auth, rate limit]
    GW --> PS[Payment Service<br/>idempotency check]
    GW --> OS[Order Service<br/>cart, orderVersion, lock]
    PS <--> IDB[(Idempotency Store<br/>key, fingerprint, status, result)]
    PS <--> OS
    PS -->|charge with provider key| PSP[Payment Provider]
    PSP -->|webhook: final result| WH[Webhook Handler]
    WH --> PS
    RJ[Reconciliation Job] -->|resolve stuck attempts| PS
    CJ[Cleanup Job] -->|expire old finished keys| IDB

Component	Responsibility
Key Manager (UI)	Creates, reuses, stores, and clears keys based on the snapshot
API Gateway	Authenticates the user, rate-limits Pay clicks
Order Service	Owns the cart and `orderVersion`; blocks cart edits while a payment is active
Payment Service	Checks the key, compares fingerprints, charges, saves results, handles cancel
Idempotency Store	Database table with a unique constraint; the source of truth. A cache like Redis can speed up lookups but must not be the only store
Webhook Handler	Receives the provider's final result if the original response was lost
Reconciliation Job	Periodically asks the provider about attempts stuck in `processing`
Cleanup Job	Deletes finished keys after the retry window (e.g. 24h). Never deletes `processing` ones

Data model

Idempotency store (one row per key):

Column	Example	Purpose
`user_id` + `key`	U1 + K1	Unique together, so duplicates can't both insert
`order_id`	O100	Which order this attempt pays
`fingerprint`	hash of `O100, v3, 5000, USD, pm_123`	Detects the same key reused with different details
`status`	`processing`, `succeeded`, `declined`, `failed`, `cancelled`	Current state
`response`	`{ paymentId: "P900" }`	Saved result to replay
`provider_key`	derived from K1, saved before charging	Prevents duplicate charges at the provider
`expires_at`	now + 24h	Cleanup time (only once finished)

Order (relevant columns):

Column	Example	Purpose
`version`	3	Increases on every cart/price change
`status`	`unpaid` / `paid`	Paid orders can't be charged again
`active_attempt`	K1 or empty	Only one payment may be in progress per order

The backend calculates the fingerprint from its own data (loaded order + amount), not from values the browser claims.

Attempt lifecycle

stateDiagram-v2
    [*] --> processing: Pay request accepted (new key)
    [*] --> cancelled: Cancel arrives before Pay
    processing --> succeeded: Provider approved
    processing --> declined: Provider declined
    processing --> processing: Provider timeout, waiting for webhook / reconciliation
    processing --> failed: Reconciliation found no charge
    succeeded --> [*]
    declined --> [*]
    failed --> [*]
    cancelled --> [*]

Cancel is only possible before charging starts. Once processing, the UI must wait for the final result.
A succeeded payment cannot be "cancelled". Undoing it is a refund, a separate operation with its own key.

When should the UI create a key?

Moment	Create a key?	Why
Checkout page loads	No	User hasn't decided to pay; details may still change
User edits cart / coupon / address	No	Nothing to pay yet
User clicks Pay, no saved attempt	Yes	Intention is now fixed. Bind the key to the current snapshot
User clicks Pay again, same snapshot	No, reuse	Same intention (retry, double click, refresh)
Snapshot changed while an attempt is unresolved	Not yet	Cancel/resolve the old attempt first
Old attempt `declined`, `failed`, or `cancelled`	Yes, on next Pay	Previous intention is finished, nothing was charged
Old attempt `succeeded`	No	Order is paid. Show the receipt

Rule: create the key at the moment of commitment (the Pay click), never earlier.

Backend rules on `POST /orders/O100/pay`

The request now carries the snapshot:

POST /orders/O100/pay
Idempotency-Key: K1
Content-Type: application/json

{ "orderVersion": 3, "paymentMethodId": "pm_123" }

The backend checks in this order:

Authenticate and confirm the user owns O100.
Look up the key. If it already exists:
- Fingerprint differs → 422 KEY_REUSED_WITH_DIFFERENT_DETAILS. Nothing is charged.
- succeeded / declined / failed → replay the saved result.
- processing → 409 IN_PROGRESS.
- cancelled → 409 ATTEMPT_CANCELLED. This blocks a late, delayed request from charging after the user cancelled.
New key. In one database transaction:
- Request orderVersion ≠ current version → 409 ORDER_CHANGED (UI must refresh the checkout).
- Order is paid or already has an active_attempt → 409 PAYMENT_ALREADY_ACTIVE.
- Otherwise insert the key as processing and set order.active_attempt = K1.
Charge using the saved provider key, then save the result:
- Success → key succeeded, order paid.
- Decline → key declined, clear active_attempt.
- Timeout → stays processing; webhook or reconciliation finishes it later.

Key lookup comes before the version check, so a retry of an already-paid attempt still gets its saved receipt.

Cart edits while a payment is active

The Order Service rejects cart changes while active_attempt is set:

PATCH /orders/O100/cart  →  409 PAYMENT_IN_PROGRESS

The UI also disables editing during payment. The backend check is what actually guarantees it (another tab or device could try to edit).

Cancel endpoint

POST /orders/O100/payment-attempts/cancel
Content-Type: application/json

{ "key": "K1" }

The key goes in the body, not the URL, so it doesn't end up in access logs or browser history.

Backend finds K1...	Backend does	Response
Not found (Pay never arrived)	Inserts K1 as `cancelled` (a "tombstone")	`cancelled`
`processing`	Cannot cancel, a charge may be happening	`processing` — wait
`declined` / `failed` / `cancelled`	Nothing to do	Same status
`succeeded`	Cannot cancel	`succeeded` — show receipt or offer refund

Why insert a tombstone for an unknown key? Because the original Pay request might be stuck in the network and arrive later. The tombstone uses the same unique (user_id, key) slot, so whichever arrives first wins, and the late Pay is rejected instead of charging.

Scenario: user changes the cart after a timeout

sequenceDiagram
    actor User
    participant UI as Checkout UI
    participant SS as sessionStorage
    participant API as Backend

    User->>UI: Click Pay (cart v3, card pm_123)
    UI->>SS: Save {key: K1, snapshot: "v3:pm_123"}
    UI->>API: POST /pay, key K1, v3
    API--xUI: Timeout (outcome unknown)
    UI-->>User: "Checking payment status..."

    User->>UI: "I want to change my cart"
    UI->>API: Cancel K1
    alt K1 never reached backend
        API->>API: Insert K1 as cancelled (tombstone)
        API-->>UI: cancelled
        UI->>SS: Remove K1
        UI-->>User: Cart unlocked
        User->>UI: Edit cart → backend bumps to v4
        User->>UI: Click Pay
        UI->>SS: Save {key: K2, snapshot: "v4:pm_123"}
        UI->>API: POST /pay, key K2, v4
        API-->>UI: Success ✅
        Note over API: If delayed K1 arrives now → cancelled, no charge
    else K1 is processing
        API-->>UI: processing
        UI-->>User: "Payment in progress, please wait"
    else K1 already succeeded
        API-->>UI: succeeded, P900
        UI->>SS: Remove K1
        UI-->>User: Show receipt (refund if they still want changes)
    end

Scenario: backend crashes mid-payment (K1 stuck in `processing`)

The key reached the backend and was saved as processing, but the status was never updated. Now the user retries with K1. What happens?

Why K1 gets stuck:

1. UI sends Pay with K1
2. Backend saves K1 = processing (+ provider key PK1)   ✅ saved
3. Backend calls the provider
4. One of these happens:
   a) Backend crashes before or during the provider call  → maybe NOT charged
   b) Provider charged, backend crashed before saving      → charged
   c) Provider is slow or timed out                       → unknown
5. K1 is still "processing" in the DB

The backend itself doesn't know whether money moved.

What the retry does:

UI      -> Backend: Pay O100 with K1 (retry)
Backend -> DB:      Find K1
DB      -> Backend: K1 = processing
Backend -> UI:      409 "Payment in progress"   (provider NOT called)
UI:     shows "Checking payment status...", asks again in a few seconds

Rule: a retry request never starts a charge for a key that is already processing. It could be case (b) or (c), where money already moved or is moving.

Who fixes the stuck status?

Provider webhook (usually first). When the provider finishes the charge, it notifies the backend's webhook handler, which updates K1 to succeeded or declined.
Reconciliation job (safety net). Every minute or so, it finds attempts stuck in processing for longer than a threshold (e.g. 2 minutes) and asks the provider about them using PK1, which was saved with K1 before calling the provider.

Provider says (for PK1)	Reconciliation job does
Charge succeeded	K1 → `succeeded`, save P900, order → `paid`
Charge declined	K1 → `declined`, unlock the order
No charge found (crashed before calling)	Retry the charge with the same PK1, or mark K1 `failed` (not charged) and unlock the order

Retrying with the same PK1 is safe: if the charge already exists, the provider returns it instead of creating a second one.

If the provider can't be reached, or offers no idempotency or status lookup, K1 stays processing and the order stays locked. It is flagged for manual review, never charged blindly.

sequenceDiagram
    participant UI as Checkout UI
    participant API as Backend
    participant DB as Database
    participant PSP as Payment Provider
    participant RJ as Webhook / Reconciliation

    UI->>API: Pay with K1
    API->>DB: K1 = processing, save PK1
    API->>PSP: Charge with PK1
    PSP->>PSP: Charge succeeds
    Note over API: 💥 Backend crashes. K1 still processing
    API--xUI: No response

    UI->>API: Retry with K1
    API->>DB: Find K1 → processing
    API-->>UI: 409 In progress (no charge)
    UI->>UI: "Checking payment status..."

    RJ->>PSP: Status of PK1?
    PSP-->>RJ: Succeeded, P900
    RJ->>DB: K1 = succeeded, P900, order paid

    UI->>API: Retry with K1
    API->>DB: Find K1 → succeeded
    API-->>UI: 200 Paid, P900 (saved result)
    UI->>UI: Show receipt, remove K1

Timeline:

12:00:00  UI: Pay with K1
12:00:00  Backend: K1 = processing, PK1 saved
12:00:01  Backend calls provider with PK1 → provider charges
12:00:01  Backend CRASHES (K1 still processing)
12:00:15  UI timeout → "Checking payment status..."
12:00:20  UI retries K1 → 409 in progress (no charge)
12:00:30  UI retries K1 → 409 in progress (no charge)
12:00:40  Webhook arrives: PK1 succeeded → K1 = succeeded, P900
12:00:45  UI retries K1 → 200 "Paid, P900" (saved result)
          UI shows receipt, removes K1 from sessionStorage
          Customer charged ONCE ✅

If the webhook never arrives, the reconciliation job performs the same update around 12:02.

What the user sees:

While processing: "Payment in progress, please don't close this page." Pay button and cart stay locked.
After a long wait (e.g. 1-2 minutes): "We're confirming your payment. We'll email you when it's done." The UI can stop polling; the backend still finishes the work.
On refresh: the UI reads K1 from sessionStorage and asks again, getting the latest status.
If the attempt ends as failed (not charged), the backend replays it like a decline (e.g. 402 in the UI example), so the UI removes K1 and the next Pay creates a new key.

Why it's safe:

Protection	Prevents
K1 saved as `processing` before charging	A retry starting a second charge
PK1 saved before calling the provider	The provider creating two charges
Webhook + reconciliation job	K1 staying stuck forever
Order lock (`active_attempt`)	A new key starting another payment for the same order

Key Manager code (UI)

Illustrative; extends the earlier example with a snapshot and cancel.

const nameFor = (orderId) => `payment-attempt:${orderId}`;
const snapshotOf = (c) => `${c.orderVersion}:${c.paymentMethodId}`;

// Called only when the user clicks Pay
function getOrCreateAttempt(checkout) {
  const name = nameFor(checkout.orderId);
  const saved = JSON.parse(sessionStorage.getItem(name) ?? "null");
  const snapshot = snapshotOf(checkout);

  if (saved && saved.snapshot === snapshot) {
    return saved; // same intention: reuse key
  }
  if (saved) {
    // Details changed but the old attempt is unresolved
    throw new Error("Resolve the previous payment attempt first");
  }

  const attempt = { key: crypto.randomUUID(), snapshot };
  sessionStorage.setItem(name, JSON.stringify(attempt)); // save BEFORE sending
  return attempt;
}

// Called when the user wants to change details during an unclear payment
async function cancelAttempt(orderId) {
  const saved = JSON.parse(sessionStorage.getItem(nameFor(orderId)) ?? "null");
  if (!saved) return { status: "none" };

  try {
    const res = await fetch(`/orders/${orderId}/payment-attempts/cancel`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      credentials: "include",
      body: JSON.stringify({ key: saved.key }),
    });
    if (!res.ok) return { status: "unknown" }; // keep key, try later

    const { status } = await res.json();
    if (["cancelled", "declined", "failed", "succeeded"].includes(status)) {
      sessionStorage.removeItem(nameFor(orderId)); // final: key no longer needed
    }
    return { status }; // "processing" → keep key and wait
  } catch {
    return { status: "unknown" }; // network error: keep key
  }
}

UI reactions:

cancelled / declined → unlock the cart; the next Pay creates a new key.
processing / unknown → keep the cart locked, show "Payment in progress".
succeeded → show the receipt; offer a refund if the user still wants changes.
Pay returns 409 ORDER_CHANGED → the order changed elsewhere (another tab). Reload the checkout, show the new total, and let the user confirm. The old key was never accepted, so remove it; the confirmation Pay creates a new key.

Design summary

Concern	Handled by
Create key at the right time	UI Key Manager, on Pay click only
Reuse on retry / refresh	UI snapshot match + sessionStorage
Detect changed details with the same key	Backend fingerprint check (`422`)
Detect stale checkout	`orderVersion` check (`409 ORDER_CHANGED`)
Prevent edits during payment	Order lock (`active_attempt`)
Cancel before charging	Cancel endpoint + tombstone
Late request after cancel	Tombstone blocks it
Lost response / crash	Saved result, provider key, webhook, reconciliation
Key stuck in `processing`	Retries get `409`, reconciliation resolves via provider key
Storage growth	Cleanup job removes finished keys after the retry window

Summary

Click Pay
  → UI: reuse key, or create one with crypto.randomUUID()
  → UI: save key in sessionStorage
  → UI: POST with Idempotency-Key
  → Backend: new key? charge and save result. Known key? return saved result
  → UI: success/decline → remove key | unknown → keep key and retry

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: 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`

DEV Community: ZeeshanAli-0704

System Design: Optimistic vs Pessimistic Locking

Optimistic vs Pessimistic Locking

The problem in one minute

Table of Contents

1. Why Concurrent Updates Lose Data

What is a lost update?

Why doesn't a transaction automatically fix this?

2. What Optimistic Locking Actually Means

What is optimistic about it?

Why is this useful for web forms?

3. The Version Check Flow

4. The Atomic Database Write

Example table

Safe conditional update

Why must the check and write stay together?

What about deletes?

5. Try It With Two Database Sessions

6. Carry the Version Through HTTP

Example with ETag and If-Match

ETag details that matter

7. Frontend Conflict Handling

Keep three things separate

A small browser request helper

8. Retry, Reload, or Merge

Why not automatically retry with the newest version?

A three way merge example

A timeout is not a version conflict

9. Inventory and Atomic Business Conditions

10. What a Row Version Does Not Protect

Multi row invariants

Other boundaries

Missing rows and predicates need their own protection

11. Optimistic Locking vs Optimistic UI

12. What Pessimistic Locking Means

What is a lock?

Why "pessimistic"?

13. The Last Item Checkout Flow

Why does Bob need to check again?

14. Transaction and Lock Lifetimes

The essential boundary

Why autocommit can break your intended design

How long should a lock be held?

15. Try It With Two Locking Sessions

Setup, once

Session A: lock but do not commit yet

Session B: try to acquire the same lock

Session A: finish

What did this prove?

16. A Short Reservation Transaction

Why keep the guarded UPDATE if a lock is held?

What happens on errors?

17. What Readers and Writers Experience

18. Wait, Fail Fast, or Skip

Option A: wait within a lock budget

Option B: fail immediately with NOWAIT

Option C: skip busy rows with SKIP LOCKED

19. Deadlocks and Consistent Lock Order

How does a deadlock happen?

Use a common acquisition order

Retry the whole transaction

20. Do Not Hold Locks During Payment

The tempting but dangerous flow

Better: persist a reservation, then release the lock

What should the frontend show?

21. Database Locks vs Other Locks

22. Comparison and Decision Guide

A practical decision guide

23. Production Rules and Common Mistakes

Optimistic rules

Pessimistic rules

Why use a counter instead of a timestamp?

Common mistakes

24. Testing and Observability

Test the guarantee, not just the happy path

Why does lock duration matter?

25. Interview Questions and Answers

What is optimistic locking in one sentence?

Does it avoid all locks?

Why not just check the version in JavaScript?

`window.postMessage`

`MessageChannel`