Design Notion: System Design Interview

Design Notion's architecture with diagrams, data models, and trade-off analysis.

Introduction

30 Second Summary

Every day, millions of people organize their work in Notion without thinking about the system behind it. In a system design interview, you'd be asked to design that system from scratch.

In this project, you will walk through a complete system design of Notion, producing a polished design document and architecture diagrams. You'll follow the same framework that interviewers evaluate: requirements, high-level design, deep dives, and trade-offs.

What You'll Build

A polished system design document with supporting diagrams that walks through designing Notion's architecture from scratch.

By the end of this project, you'll have:

  • A Google Doc containing your full Notion system design with sections for requirements, architecture, data model, API contracts, real-time collaboration, and scaling strategy.
  • Three Excalidraw diagrams: a high-level architecture diagram, a block data model diagram, and a real-time sync sequence flow.
  • Trade-off analysis for key decisions including CRDT vs OT, sharding strategy, and caching approach.
  • Secret Mission: Design Notion's permissions and access control system with hierarchical inheritance.

Are there any prerequisites?

No prior system design experience is needed. All you need is a web browser and a free Google account for Google Docs.

Before We Start

Before We Start...

Set Up Your Design Tools

System design interviews follow a predictable structure. Interviewers evaluate how you clarify requirements, sketch an architecture, dive deep into components, and analyze trade-offs.

In this step, you will set up Excalidraw for drawing architecture diagrams and create a design document in Google Docs. Both tools are free and browser-based.

In this step, get ready to:
  • Set up Excalidraw for architecture diagramming.
  • Create a structured design document in Google Docs.
  • Learn the four-phase system design interview framework.
Set up Excalidraw

You need a diagramming tool for creating architecture diagrams throughout this project. Excalidraw is a free, open-source whiteboard tool that is widely used in system design interviews.

  • Open excalidraw.com in your browser. No account or installation is needed.

What is Excalidraw?

Excalidraw is an open-source whiteboard tool that runs entirely in your browser. Your drawings are stored locally on your device, so nothing is uploaded to a server unless you choose to share.

Its hand-drawn style encourages quick sketching over pixel-perfect diagrams. This matches real interview conditions where speed matters more than polish.

You should see a blank white canvas with a toolbar across the top of the screen.

  • Try out the keyboard shortcuts you will use throughout this project:
  • Press R on your keyboard to activate the rectangle tool. You will use rectangles to represent system components.
  • Press A to activate the arrow tool. You will use arrows to show connections between components.
  • Press T to activate the text tool for adding labels.
  • Press ? to see all available keyboard shortcuts.

Clearing your test shapes

After trying the shortcuts, click on any shapes you created and press Backspace (or Delete) to remove them. You want a clean canvas before you start your diagrams.

  • Practice saving your canvas by clicking the menu icon (three horizontal lines) in the top-left corner of the screen.
  • Click Save to disk.

A .excalidraw file downloads to your computer. You can reopen this file anytime by dragging it back into the Excalidraw browser tab.

Why Excalidraw over other diagramming tools?

Alternatives like draw.io work but feel more formal. Lucidchart requires an account and has a limited free tier. Excalidraw requires nothing beyond a browser, and its sketch-style output is exactly what interviewers expect to see on a whiteboard.

Set up your design document in Google Docs

Your design document will capture all requirements, architecture decisions, and trade-off analyses. This is the deliverable you would present in a real interview or design review.

  • Open docs.google.com in a new browser tab.
  • Sign in with your Google account if prompted.
  • Under Start a new document, click Blank.

Don't see the Blank option?

Make sure you are on the Google Docs home screen at docs.google.com, not inside an existing document. The Blank option appears under Start a new document near the top of the home screen.

If you are not signed in, Google will prompt you to log in before showing the home screen.

help me create a new blank document in Google Docs

  • Click Untitled document at the top-left of the page to rename it.
  • Type System Design: Notion as the document title and press Enter.
  • Add the following section headings to your document. Type each one on its own line:
  • 1. Requirements
  • 2. High-Level Architecture
  • 3. Data Model & API
  • 4. Real-Time Collaboration
  • 5. Scaling & Storage
  • Leave each section empty for now. You will fill them in as you work through each step.

Your document should show the title System Design: Notion at the top with all five numbered headings listed below it.

Why these five sections?

These sections mirror the structure that interviewers expect to see in a system design answer. Each section maps to a phase of the interview process, from clarifying requirements to discussing how the system scales under load.

Understand the interview framework

Before diving into the design, understand the structure that interviewers use to evaluate candidates. System design interviews follow four phases.

  1. Clarify requirements and scope. Define what the system does and what it does not do.
  2. Propose a high-level design. Sketch the major components and how they communicate.
  3. Deep-dive into critical components. Design the data model, APIs, and complex subsystems in detail.
  4. Discuss trade-offs and scaling. Analyze alternatives and explain how the system handles growth.

How does this project map to the framework?

Each remaining step in this project maps to one of these phases. Step 2 covers requirements and high-level design. Steps 3 and 4 are deep dives into the data model, APIs, and real-time collaboration. Step 5 covers scaling and storage trade-offs.

Your design document follows the same flow. By the end, you will have a complete document that walks through each phase the way an interviewer expects.

Your tools are ready and your document is structured. Next up, you will define Notion's requirements and draw your first architecture diagram.

Define Requirements and Draw the High-Level Architecture

Your design tools are ready and your document structure is in place. Now comes the most important first move in any system design interview: defining exactly what you're building and sketching the big picture.

Interviewers want to see that you can scope a problem before diving into details. In this step, you'll write clear requirements for Notion and then translate them into a high-level architecture diagram that shows how the major components connect.

In this step, get ready to:
  • Write functional and non-functional requirements for Notion.
  • Draw a high-level architecture diagram in Excalidraw.
  • Document the trade-offs behind your architecture choices.
Write your requirements in Section 1

In a real interview, the first few minutes are spent clarifying what the system needs to do. This prevents you from designing the wrong thing and shows the interviewer you can think before you build.

  • Switch to your Google Doc and scroll to the 1. Requirements heading.
  • Under the heading, type Functional Requirements as a sub-heading.
  • Below that, write the following five requirements as a numbered list:
  • Users can create, edit, and nest pages.
  • Pages are composed of blocks (text, headings, images, to-dos, embeds).
  • Users can create databases with multiple views (table, board, calendar).
  • Multiple users can edit the same page simultaneously in real time.
  • Content can be shared with specific users, groups, or made public.

What are functional requirements?

Functional requirements describe what the system does from a user's perspective. They answer the question: "What actions can a user take?"

Interviewers use these to gauge whether you understand the core product. Getting them right early means every design decision that follows has a clear reason behind it.

  • Below the functional requirements, type Non-Functional Requirements as another sub-heading.
  • Write the following five requirements as a numbered list:
  • Low latency for editing (local keystroke echo under 50ms).
  • Eventual consistency for collaborative editing.
  • Support for large documents (10,000+ blocks).
  • High availability and durability (no data loss).
  • Scale to millions of users and billions of blocks.

What are non-functional requirements?

Non-functional requirements describe how well the system performs. They cover speed, reliability, and scale.

The 50ms latency target is important because users expect typing to feel instant. If there is any noticeable delay between pressing a key and seeing a character, the editor feels broken.

  • Below the non-functional requirements, type Scope as a sub-heading.
  • Write a short note stating what you are NOT designing: mobile apps, offline sync, the Notion API for third-party integrations, and the template marketplace.

Why scope down?

Scoping down shows interviewer maturity. A 45-minute interview cannot cover an entire product like Notion, so explicitly stating what you will skip signals that you can prioritize.

Section 1 of your document should now have three sub-sections: functional requirements, non-functional requirements, and scope.

Draw the high-level architecture diagram

With your requirements defined, the next move in a system design interview is to sketch the high-level architecture. This shows how the major components of the system fit together before diving into any single one.

  • Switch to your Excalidraw canvas.
  • Press R to select the rectangle tool.
  • Draw a rectangle on the far left and label it CDN (press T to add a text label).
  • Draw a second rectangle to the right of the CDN and label it Client (Web/Desktop).
  • Draw a third rectangle to the right and label it API Gateway.
  • To the right of the API Gateway, draw three rectangles stacked in a vertical column.
  • Label them Block Service, Collaboration Service, and Database Service from top to bottom.
  • Below the three services, draw two more rectangles.
  • Label them PostgreSQL (primary storage) and Redis (cache).

Why separate services instead of one big application?

Notion's features have different scaling profiles. The Collaboration Service is CPU-bound because it runs merge operations, while the Database Service is IO-bound because it processes queries.

Separating them allows each service to scale independently based on its own load. You will document this trade-off in the next substep.

  • Press A to select the arrow tool.
  • Draw an arrow from Client (Web/Desktop) to API Gateway and label it HTTPS.
  • Draw arrows from API Gateway to each of the three services and label them gRPC (or internal).
  • Draw a direct arrow from Client (Web/Desktop) to Collaboration Service and label it WebSocket.
  • Draw arrows from each service down to PostgreSQL and Redis.

What do the arrow labels mean?

HTTPS is the standard protocol for web traffic from the client to the API Gateway. gRPC is a high-performance protocol for communication between internal services.

The WebSocket connection goes directly from the client to the Collaboration Service, bypassing the API Gateway. This is because real-time editing needs a persistent, two-way connection that standard request-response HTTP cannot provide.

  • Click the menu icon (three horizontal lines) in the top-left corner of Excalidraw.
  • Select Export image.
  • Save the PNG file to your computer.
  • Switch to your Google Doc and scroll to the 2. High-Level Architecture heading.
  • Paste the PNG image into Section 2 (use Ctrl+V or drag the file into the document).
  • Below the diagram, write a one-paragraph summary explaining the flow.
  • Describe how clients connect via HTTPS for read/write operations and via WebSocket for real-time collaboration.
  • Mention that the API Gateway routes requests to the appropriate service, and that all services read from and write to PostgreSQL with Redis as a caching layer.

Your diagram should show eight rectangles connected by labeled arrows, reading left to right from the CDN through to the data stores.

Diagram feeling messy?

Excalidraw diagrams do not need to be pixel-perfect. In a real interview, hand-drawn clarity matters more than aesthetics. Make sure every rectangle has a label and every arrow has a protocol name.

If your arrows overlap, try dragging the service rectangles further apart to create more space between them. Help me fix my architecture diagram layout.

Document the architecture rationale

A strong system design answer does not just show the architecture. It explains why you chose this structure over alternatives.

  • In your Google Doc under Section 2, add a sub-heading called Trade-offs.
  • Write a paragraph explaining why you chose a service-oriented architecture over a monolith.
  • Note that Notion's features (editing, collaboration, database views) have different scaling profiles.
  • Explain that the Collaboration Service is CPU-bound (merge operations) while the Database Service is IO-bound (queries), so separating them allows independent scaling.
  • State the trade-off: a service-oriented architecture increases operational complexity and introduces network latency between services.

Why do interviewers care about trade-offs?

Every architecture decision has upsides and downsides. Naming the downsides yourself shows the interviewer that you are not blindly following a pattern.

A monolith would be simpler to deploy and debug, but it cannot scale individual features independently. Acknowledging this makes your design more credible.

Section 2 of your Google Doc should now have three things: the architecture diagram, a summary paragraph, and a trade-offs sub-section.

✔️ Awesome, I've got everything!

Nice work. Double check that your Google Doc Section 1 has functional requirements, non-functional requirements, and a scope note. Section 2 should have the architecture diagram, a summary paragraph, and a trade-offs sub-section.

ⓧ I'd like to double check my work

Here is what each section should contain at this point.

Section 1 (Requirements):

  • Functional Requirements: (1) Create, edit, and nest pages. (2) Pages composed of blocks. (3) Databases with table, board, calendar views. (4) Real-time multi-user editing. (5) Sharing with users, groups, or public.
  • Non-Functional Requirements: (1) Sub-50ms keystroke latency. (2) Eventual consistency. (3) Support 10,000+ blocks per document. (4) High availability and durability. (5) Scale to millions of users and billions of blocks.
  • Scope: Explicitly excludes mobile apps, offline sync, third-party API, template marketplace.

Section 2 (High-Level Architecture):

  • Architecture diagram with 8 rectangles: CDN, Client (Web/Desktop), API Gateway, Block Service, Collaboration Service, Database Service, PostgreSQL, Redis.
  • Arrows labeled: HTTPS (Client to API Gateway), gRPC/internal (API Gateway to services), WebSocket (Client to Collaboration Service).
  • Summary paragraph describing the request flow.
  • Trade-offs sub-section explaining service-oriented vs monolith, with the CPU-bound vs IO-bound reasoning.

Sections 3, 4, and 5 of your Google Doc should still be empty.

You now have the foundation that every other design decision builds on. Next up, you will design the data model that makes Notion's "everything is a block" philosophy work, and define the API endpoints that clients use to interact with it.

Design the Block Data Model and API

Your architecture diagram maps out how Notion's services connect. The next question goes deeper: how does Notion actually represent content?

The answer is Notion's defining design decision. Everything in Notion is a block. A page is a block. A paragraph is a block. Even a database is a block whose children are row blocks. In this step, you'll define the block schema, design the API that reads and writes blocks, and analyze the trade-offs of this recursive approach.

In this step, get ready to:
  • Design the block data model schema and draw a data model diagram in Excalidraw.
  • Define REST API contracts for the six core block operations.
  • Document trade-offs comparing the block model to a document-based alternative.
Design the block data model

Notion's core insight is that every piece of content shares the same shape. A page, a paragraph, a heading, an image, a to-do item, and even a database are all blocks. Blocks can contain other blocks, forming a recursive tree.

Why is everything a block?

A unified block model means Notion only needs one storage table and one set of APIs for all content types. Adding a new content type (like a callout or a toggle) is just a new value in the type enum. No new tables, no new endpoints.

The trade-off is that fetching a full page requires traversing a tree of blocks rather than reading a single row. You'll address this trade-off in the final substep.

  • In your Google Doc, scroll down to Section 3 ("Data Model & API").
  • Write the block schema using the reference below as a guide. You can format it as a bulleted list or a table in your doc:
Block {
  block_id       UUID         (primary key)
  type           ENUM         (text, heading, image, database, page, toggle, callout, ...)
  parent_id      UUID         (references the parent block)
  workspace_id   UUID         (for data partitioning)
  properties     JSONB        (type-specific data: text content, image URL, checkbox state)
  children       UUID[]       (ordered array of child block_ids)
  created_by     UUID
  created_at     TIMESTAMP
  last_edited_by UUID
  last_edited_at TIMESTAMP
}

What do these fields mean?

  • block_id is a UUID primary key that uniquely identifies every block in the system.
  • type is an enum that tells Notion how to render the block. Adding a new content type means adding a new enum value.
  • parent_id links each block to its parent, forming the recursive tree. A page's parent_id points to a workspace block. A paragraph's parent_id points to its page.
  • workspace_id groups all blocks belonging to one workspace together. This becomes the partition key for sharding later.
  • properties is a JSONB column that stores type-specific data. A text block stores its content here. An image block stores its URL. This flexibility is what makes the unified block model work.
  • children is an ordered array of child block IDs. The order matters because it determines how content appears on the page.

Now you'll visualize this schema as a diagram. Switch to your Excalidraw canvas.

  • Draw a large rectangle for the Block entity. Inside it, list all ten fields from the schema above.
  • To the right of the entity box, draw five smaller rectangles representing example blocks: one labeled "Workspace", one labeled "Page", one labeled "Heading", two labeled "Text", and one labeled "Database".
  • Draw arrows from each child block's parent_id to its parent. The Page arrow points to Workspace. The Heading, both Text blocks, and Database arrows all point to Page.
  • Label each arrow parent_id so the relationship is clear.

What should the diagram show?

Your diagram should tell a story: the entire workspace is a recursive tree of blocks. The Workspace block sits at the root. The Page block is its child. The Heading, Text, and Database blocks are children of the Page. This tree structure is the core insight that interviewers want to see.

  • Export your diagram as a PNG. Click the hamburger menu in the top-left corner of Excalidraw, then select Export image. Click PNG to download the image.
  • Switch to your Google Doc and paste the PNG into Section 3, below the schema you just wrote.

You should now see the block schema and the data model diagram side by side in Section 3.

Diagram not showing in Google Docs?

  • Make sure you exported as PNG (not SVG or the native .excalidraw format). Google Docs displays PNGs directly.
  • If the image looks too small, try increasing the Scale setting in the Excalidraw export dialog before exporting.
  • Help me paste my Excalidraw diagram into Google Docs as a PNG.
Design the core API endpoints

With the data model defined, you need an API that lets clients create, read, update, and delete blocks. These REST API contracts show interviewers that you can translate a data model into a working interface.

  • Below the data model diagram in Section 3 of your Google Doc, add a subheading called "API Contracts".
  • Write the following six endpoints, using the reference below as a guide:
GET    /blocks/:id              Returns a block and its immediate children
POST   /blocks                  Creates a new block (type, parent_id, properties)
PATCH  /blocks/:id              Updates block properties or reorders children
DELETE /blocks/:id              Soft-deletes a block and its children recursively
GET    /pages/:id               Fetches a page (root block + children in batches)
POST   /databases/:id/query     Queries database rows with filters, sorts, pagination

Why does page fetching need special handling?

Fetching a full page means traversing the block tree: start at the root page block, fetch its children, then fetch their children, and so on. Making one query per block would be extremely slow for large pages.

Notion optimizes this by batch-fetching children using an IN clause or a recursive CTE (Common Table Expression) in PostgreSQL. A recursive CTE lets you write a single query that walks the tree and returns all descendants in one round trip.

  • For each endpoint, add a brief note in your doc explaining what it accepts and returns. Pay special attention to GET /pages/:id. Note that it fetches the root block, then recursively fetches children in batches using a CTE.
  • For POST /databases/:id/query, note that it queries database rows with filters, sorts, and pagination. This is a separate endpoint because database queries are structurally different from simple block reads.
Document the data model trade-offs

Every design choice has a cost. The block model is powerful, but interviewers want to see that you understand what you're giving up.

  • Below the API contracts in Section 3, add a subheading called "Trade-offs".
  • Write three costs of the block model:
  • Recursive queries for page rendering can be expensive for deeply nested documents.
  • The JSONB properties field is schema-less, making validation and indexing harder.
  • Reordering children requires updating the ordered array, which can cause write contention.
  • Below the three costs, compare the block model to the alternative: a document-based approach where each page is stored as one JSON blob. Write that the document approach is simpler to fetch (one read per page) but impossible to collaborate on at the block level, because two users editing different paragraphs would conflict on the same JSON blob.

Why does this trade-off matter in an interview?

Interviewers aren't looking for the "right" answer. They want to see that you can reason about the strengths and weaknesses of a design decision. Naming the costs of your own design shows engineering maturity.

The block model wins for Notion because real-time collaboration requires granular, block-level operations. The document-blob approach would make collaboration impossible at scale.

Your data model and API are locked in. Next up, you'll tackle the hardest part of Notion's architecture: real-time collaboration, where multiple users edit the same page simultaneously.

Design the Real-Time Collaboration System

Your data model and API contracts are locked in. Every piece of content in Notion is a block, and you have endpoints to create, read, update, and delete them.

The next challenge is the hardest part of designing Notion. What happens when two people edit the same paragraph at the same time? In this step, you'll design the conflict resolution system that keeps every user's view in sync.

In this step, get ready to:
  • Describe the collaboration problem and compare conflict resolution strategies.
  • Draw a real-time sync sequence flow diagram in Excalidraw.
  • Document trade-offs between three conflict resolution approaches.
Understand the collaboration challenge

When two users open the same Notion page, both can start typing at once. Without a strategy to handle conflicting edits, one user's changes will silently overwrite the other's.

  • In Section 4 of your Google Doc, write a paragraph describing the core problem.
  • Frame it this way: User A changes a paragraph's text while User B edits the same paragraph simultaneously.
  • State that without a conflict resolution strategy, one edit gets lost.

Below the problem statement, introduce the two main approaches the industry uses to solve this: Operational Transformation (OT) and Conflict-free Replicated Data Types (CRDTs).

What are OT and CRDTs?

OT uses a central server to transform operations against each other. When two edits arrive at the same time, the server adjusts each one so both apply cleanly. Google Docs uses this approach.

CRDTs are data structures designed to merge without any central coordinator. Each edit carries enough metadata to resolve conflicts locally. Figma uses CRDTs.

  • Write a paragraph in your design doc explaining the key difference: OT requires a central server to order and transform operations, while CRDTs let each client merge independently.
  • Below that, write a paragraph describing Notion's hybrid approach.
  • Explain that Notion uses block-level last-writer-wins (LWW), where the most recent timestamp wins for each block property.
  • Add that for text content within a single block, Notion uses a character-level CRDT so two users typing in the same paragraph see their edits merge smoothly.
  • Note the key insight: two users editing different blocks never conflict at all, because each block is an independent unit.

Why does Notion's hybrid approach work?

In a block-based editor, concurrent edits within the exact same block are relatively uncommon. Users are usually working on different blocks at the same time.

Block-level LWW handles the common case cheaply. The character-level CRDT only kicks in for the rarer edge case of two people typing in the same paragraph.

Section 4 of your Google Doc should now describe the collaboration problem, explain OT and CRDTs, and detail Notion's hybrid approach.

Draw the real-time sync flow

Your written explanation covers what Notion does to handle conflicts. Now you need a diagram that shows how a single edit flows through the system from one user to another.

  • Switch back to Excalidraw and scroll to an empty area below your existing two diagrams.
  • Press R to draw four rectangles arranged left to right.
  • Label them (press T for text): Client A, Collaboration Service, PostgreSQL, and Client B.
  • Press A to draw arrows between the actors, representing the five steps of the sync flow:

What is an optimistic update?

Step 1 in the flow is called "optimistic" because Client A applies the edit to its own screen immediately, before the server has confirmed anything. The user sees their keystroke appear instantly.

This is what gives Notion its snappy feel. The server confirms the edit in the background, and if something goes wrong, the client rolls back. In practice, rollbacks are extremely rare.

  • Below the main sequence, draw a separate section labeled Reconnect flow.
  • Draw a disconnected client sending its state vector (a summary of which operations it has seen) to the Collaboration Service.
  • Draw an arrow back from the Collaboration Service to the client, labeled "Stream missing operations".

Why include the reconnect flow?

In a real interview, interviewers love to ask: "What happens when a client disconnects and comes back?" Showing the reconnect flow demonstrates that you've thought beyond the happy path.

The state vector lets the server compute exactly which operations the client missed, so it only streams the diff instead of the entire document.

  • Export your diagram as PNG by clicking the hamburger menu (top-left corner) and selecting Export image.
  • Switch back to your Google Doc.
  • Paste the PNG into Section 4, below your written explanation of Notion's hybrid approach.

Your diagram should show five numbered steps flowing between the four actors, with a separate reconnect flow section below.

Diagram looking cluttered?

If the arrows overlap or labels are hard to read, give each actor more horizontal space. In an interview, clarity beats compactness.

Keep the reconnect flow visually separate from the main sequence. A horizontal line or extra vertical space between them makes the diagram easier to follow.

Help me lay out my real-time sync diagram in Excalidraw so the arrows and labels are easy to read.

Document the collaboration trade-offs

Every design decision involves trade-offs. Interviewers expect you to evaluate alternatives, not just present your chosen approach. A comparison table makes these trade-offs scannable at a glance.

  • In Section 4 of your Google Doc, add a "Trade-offs" subsection below the sync flow diagram.
  • Create a comparison table with three columns, one for each conflict resolution approach.

What to include in your comparison table

  • OT: simpler implementation, requires a central server to transform operations, can become a bottleneck at scale.
  • Full CRDT: no central bottleneck, but carries heavier metadata overhead (a unique ID per character). Requires complex garbage collection.
  • Notion's hybrid (block-level LWW + text CRDT): conflicts are rare because users usually edit different blocks. Simpler than full CRDT. The trade-off is no character-level merge across block boundaries.
  • End the subsection with a sentence explaining why Notion's approach is a good fit: in a block editor, the block boundary naturally isolates most edits, making full CRDT overhead unnecessary.

Section 4 is now complete. It should contain the problem statement, Notion's hybrid approach, the sync flow diagram, and the trade-off comparison table.

Make your trade-off table interview-ready

A strong trade-off table names concrete costs, not vague downsides. "Unique ID per character increases storage" is stronger than "more complex." Interviewers are testing whether you understand the real engineering constraints behind each approach.

Your collaboration design captures how Notion keeps edits in sync across users. Next up, you'll tackle the final piece: scaling this system to handle billions of blocks and millions of users.

Design the Scaling and Storage Strategy

In the last step, you designed Notion's real-time collaboration system and analyzed the trade-offs between CRDTs, OT, and Notion's hybrid approach. Your design document now covers how multiple users can edit the same page simultaneously.

Every interviewer follows the deep dives with a scaling question: how does this work for billions of blocks? In this step, you'll design the sharding and caching strategies that keep Notion fast at massive scale.

In this step, get ready to:
  • Design an application-level sharding strategy for PostgreSQL.
  • Design a two-tier caching layer with client-side and server-side components.
  • Write a concluding summary that ties the full system design together.
Design the sharding strategy

Notion stores billions of blocks in PostgreSQL. A single database instance cannot handle that volume of reads and writes.

Sharding distributes data across multiple database instances so no single machine becomes a bottleneck. Notion uses application-level sharding, where the application logic decides which database instance to route each query to.

  • In Section 5 of your Google Doc, add a subheading called Sharding Strategy.
  • Write a paragraph explaining why sharding is necessary. Notion stores billions of blocks, and a single PostgreSQL instance cannot handle the read/write volume at that scale.
  • Describe the sharding approach: Notion uses application-level sharding. The partition key is workspace_id. All blocks belonging to a single workspace live on the same shard.
  • Document the specific numbers: 480 logical shards distributed across 96 physical PostgreSQL instances, with 5 logical shards per instance (as of 2023).
  • Note the composite primary key for sharded tables: (block_id, workspace_id).
  • Describe the routing mechanism: the application maintains a routing table that maps each workspace_id to its physical database instance.

Why workspace_id as the partition key?

Users almost always query data within a single workspace. By putting all of a workspace's blocks on the same shard, most queries hit just one database instance.

This avoids expensive cross-shard joins. In a real interview, explaining why you chose a specific partition key shows you understand the access patterns, not just the sharding technique.

What triggered Notion's move to sharding?

Notion originally ran on a single PostgreSQL instance. As block counts grew, PostgreSQL's VACUUM process started stalling, creating a risk of transaction ID wraparound. Sharding was the fix that allowed Notion to scale from billions to hundreds of billions of blocks.

Design the caching layer

Even with sharding, reading from the database on every request is too slow for a real-time editor. A caching strategy reduces database load and speeds up the operations users perform most often.

  • Below your sharding section, add a subheading called Caching Strategy.
  • Write a brief intro explaining that Notion uses a two-tier caching approach: client-side and server-side.
  • Describe the client-side cache. Notion clients cache blocks locally using IndexedDB (web) or SQLite (desktop and mobile). This enables instant rendering and offline access.
  • Name the two client-side data structures. The RecordCache is an LRU cache of block records. The TransactionQueue holds pending edits waiting for server confirmation.
  • Describe the server-side cache. Redis caches frequently accessed blocks and resolved permissions. Cache invalidation happens whenever a block is edited.

What do RecordCache and TransactionQueue do together?

When a user edits a block, the edit is applied to the RecordCache immediately (the optimistic update you diagrammed in Step 4). The edit is also added to the TransactionQueue, which persists it locally until the server confirms or rejects it.

This two-structure pattern means the user sees instant feedback while the system guarantees no edit is lost, even if the network drops.

  • Add a Cache Invalidation note in your design doc. Explain that this is one of the hardest problems in the system.
  • Describe the permission-caching challenge. When permissions change on a parent page, the cached permissions for all descendant blocks must be invalidated.
  • Explain Notion's approach: the system walks up the parent chain from a block to resolve the effective permissions for a user, then caches the result per user per page in Redis.
  • State the invalidation rule: when permissions change on any page, invalidate the cache for that page and all its descendant pages.

Why is cache invalidation the hardest part?

A single permission change on a top-level page can cascade through thousands of child pages and blocks. The server must find every affected descendant and flush their cached permission entries from Redis.

This is a classic interview talking point. Mentioning it shows the interviewer you understand the real operational cost of hierarchical permissions, not just the data model.

Tie it all together

Your design document now has detailed coverage of every major subsystem. A strong concluding paragraph shows the interviewer you can zoom back out and explain how all the pieces connect.

  • At the bottom of Section 5, write a concluding paragraph that summarizes the full system design.
  • Cover the end-to-end flow: clients connect via HTTPS for read/write operations and WebSocket for real-time collaboration.
  • Name the services: the API Gateway routes requests to the Block Service, Collaboration Service, and Database Service.
  • Summarize the storage layer: blocks are stored in sharded PostgreSQL partitioned by workspace_id, with Redis caching hot data and resolved permissions.
  • Mention the collaboration strategy: real-time editing uses a hybrid approach with optimistic local updates and server-mediated broadcasting.
  • Switch to your Excalidraw tab and review your three diagrams: high-level architecture, block data model, and real-time sync flow.
  • Confirm they tell a coherent story. The architecture diagram shows the components, the data model shows how content is structured, and the sync flow shows how edits travel between users.

Read your document as the interviewer would

Scroll through your entire Google Doc from top to bottom. Each section should flow naturally into the next: requirements define the problem, the architecture proposes a solution, the data model and API define the contracts, collaboration handles the hardest feature, and scaling makes it all work at production volume.

All five sections of your design document are now complete. You have a polished artifact that walks through Notion's architecture the way interviewers expect to see it.

Secret mission

Design the Permissions and Access Control System

This is where system design interviews separate good answers from great ones. Permissions are deceptively complex in a block-based system. Can you design hierarchical permission inheritance that handles tree traversal, caching, and the interaction with the block model?

Clean Up Your Resources

Clean Up Your Resources

Decide whether to keep your resources, come back later, or delete them entirely. This project runs entirely in your browser and on your local disk, so there are no ongoing costs.

Resources you used:

  • Excalidraw .excalidraw file saved to your local disk.
  • Exported PNG diagram files saved to your local disk.
  • Google Doc titled "System Design: Notion" stored in Google Drive.

Keep everything running

No action needed. Choose this if you plan to revisit your design document or refine your diagrams.

  • Your .excalidraw file and exported PNGs remain wherever you saved them on disk.
  • Your Google Doc stays in Google Drive at no cost.
  • Excalidraw also keeps a copy of your most recent canvas in your browser's local storage, so reopening excalidraw.com may restore your last session.

Pause - I'll come back to this later

Close your browser tabs to free up memory. All your files are already saved and will be waiting when you return.

  • Close the Excalidraw browser tab. Your .excalidraw file is already saved to disk.
  • Close the Google Docs tab. Your document auto-saves to Google Drive.
  • To resume, drag your .excalidraw file into excalidraw.com to reload your diagrams. Find your Google Doc in Google Drive.

Delete - I don't want to use this again

Remove all project files and documents to start fresh.

  • Open File Explorer and navigate to the folder where you saved your Excalidraw files.
  • Select the .excalidraw file and all exported PNG diagram files, then delete them.
  • Open Google Drive at drive.google.com.
  • Find the "System Design: Notion" document, right-click it, and move it to the trash.
  • To permanently remove the document, open the trash folder in Google Drive and delete it from there.
  • To clear Excalidraw's cached canvas from your browser, open your browser's settings and clear site data for excalidraw.com.

Nice Work!

Nice Work!

Nice work! You designed Notion's architecture from the ground up, producing a complete system design document and three supporting diagrams covering data modeling, real-time collaboration, and scaling.

You've learned how to:

  • Designed a block-based data model where everything is a block, then defined REST API contracts for creating, reading, updating, and deleting blocks.
  • Designed a real-time collaboration system using Notion's hybrid approach of block-level last-writer-wins combined with character-level CRDTs for text content.
  • Planned a scaling strategy with application-level PostgreSQL sharding using workspace_id as the partition key across 480 logical shards, paired with two-tier caching using client-side IndexedDB and server-side Redis.
  • Secret Mission: Designed a hierarchical permission system with inheritance, resolution algorithms, and caching strategies that separate the render tree from the permission tree.

Ready to quiz yourself?