1. Introduction: Notion at Scale

Notion has grown from a simple note-taking application into one of the most powerful all-in-one productivity platforms on the planet. With over 30 million registered users, more than 4 million paying subscribers, and a valuation exceeding $10 billion, Notion represents a masterclass in building flexible, extensible software systems. It serves individuals, startups, and Fortune 500 companies alike, replacing dozens of standalone tools by unifying notes, documents, wikis, databases, project management, and now artificial intelligence into a single coherent workspace.

From a system design perspective, Notion is extraordinarily challenging. Unlike linear document editors like Google Docs or structured databases like Airtable, Notion introduces a unique block-based architecture where every piece of content — a paragraph, an image, a database, a toggle heading, an embed — is an atomic, independently addressable, nestable block. This design gives users infinite composability but creates immense engineering complexity across data modeling, real-time collaboration, permission enforcement, search indexing, and performance optimization.

Consider the fundamental tension: Notion must simultaneously behave like a word processor (rich text editing with inline formatting), a database (structured records with relations, rollups, and formula fields), a project manager (Kanban boards, timelines, sprint tracking), a wiki (hierarchical knowledge bases with cross-linking), and an AI assistant (generating content, answering questions, summarizing long documents). Each of these domains has fundamentally different data access patterns, consistency requirements, and performance characteristics. Unifying them under a single block abstraction is the core engineering challenge.

The scale at which Notion operates adds another dimension of complexity. A single workspace might contain hundreds of thousands of blocks organized in deeply nested hierarchies. Enterprise customers expect sub-100ms page load times while simultaneously running complex database queries across thousands of records. Real-time collaboration means dozens of users might edit the same document concurrently, each making changes that must be merged instantly without conflicts. And with the introduction of Notion AI, the platform must integrate large language model inference into the editing experience with minimal latency, requiring sophisticated prompt engineering, context window management, and streaming response architectures.

This system design guide walks through every major subsystem of Notion's platform. We examine the block-based data model and how it supports infinite nesting. We explore the CRDT-based collaboration engine that enables conflict-free real-time editing. We dissect the database engine that powers views, filters, sorts, and rollups across millions of records. We analyze the search infrastructure that must respect permissions while delivering instant results. We design the AI integration pipeline that powers content generation and knowledge Q&A. And we address operational concerns like caching strategies, offline synchronization, permission enforcement, and import/export pipelines that make the system production-ready at global scale.

Throughout this guide, we focus on senior-level design decisions. We discuss trade-offs between SQL and NoSQL storage, between eager and lazy loading of nested blocks, between operational transforms and CRDTs for collaboration, and between monolithic and microservices deployment architectures. Every design choice is presented with its rationale, alternatives considered, and production implications analyzed. By the end, you will have a thorough understanding of how to design and build a Notion-class productivity platform from the ground up.

Who This Guide Is For

This guide targets senior software engineers, staff engineers, and architects who are preparing for system design interviews at top-tier technology companies or who are building similar productivity tools in production. The content assumes familiarity with distributed systems fundamentals, database internals, and web application architecture. We reference specific technologies but focus primarily on architectural patterns and design trade-offs that transcend any particular technology stack.

2. Platform Overview — Pages, Databases, Wikis, Projects, AI

Before diving into the technical architecture, we must establish a clear understanding of Notion's feature surface and the product domains it encompasses. Notion's power comes from the way it composes a relatively small set of primitives — blocks, pages, and databases — into a remarkably diverse set of use cases. Understanding this composition is essential before we can reason about the data models and infrastructure that support it.

Pages and Nested Hierarchies

At the most fundamental level, Notion is organized into pages. A page is itself a block — specifically, a page block — that can contain an arbitrary number of child blocks. Pages can be nested indefinitely: a page can contain a page, which can contain another page, and so on. This recursive structure allows users to build arbitrarily deep knowledge hierarchies. A typical enterprise workspace might have a top-level page for Engineering, containing pages for Frontend, Backend, and Infrastructure, each containing pages for specific projects, design documents, meeting notes, and runbooks. The left sidebar in Notion's UI presents this hierarchy as a collapsible tree, enabling rapid navigation across thousands of pages.

Block Types and Composability

Notion's content is composed of blocks. As of 2025, Notion supports over 50 distinct block types, organized into several categories. Text blocks include paragraphs, headings (H1, H2, H3), bulleted lists, numbered lists, to-do items, toggle blocks, callout blocks, and quote blocks. Media blocks include images, videos, audio files, PDFs, bookmarks, and embeds. Database blocks include inline databases, linked databases, and database views. Advanced blocks include equations (LaTeX), code blocks with syntax highlighting, tables, table of contents, breadcrumb navigation, column layouts, synced blocks, and template buttons.

Databases and Structured Data

Notion's database feature transforms the platform from a note-taking tool into a structured data management system. A database is a special type of page that contains rows (entries) and columns (properties). Each property has a type — title, text, number, select, multi-select, date, person, file, checkbox, URL, email, phone, relation, rollup, created time, last edited time, created by, last edited by, or formula. Databases support multiple views: table view, board view (Kanban), timeline view (Gantt), calendar view, gallery view, and list view.

Wikis and Team Knowledge Bases

Notion's wiki feature provides structured knowledge management across organizations. Unlike ad-hoc page collections, wikis enforce a hierarchy with a homepage, sub-pages, and cross-linking. Wiki pages can be marked as published to make them accessible across the entire organization. Notion tracks page status (draft, in review, published, archived), ownership, and last-updated timestamps to keep the knowledge base fresh and navigable.

Project Management

Notion has expanded significantly into project management territory. Features include task assignments with due dates, sprint tracking through database views, project timelines using Gantt charts, custom status workflows, and integration with development tools like GitHub and Jira. The project management capabilities are built entirely on top of the database and block primitives, demonstrating the power of Notion's compositional architecture.

Notion AI

The most recent major addition to Notion's platform is Notion AI, which integrates large language models directly into the editing experience. Notion AI can generate entire pages from prompts, summarize long documents, extract action items from meeting notes, translate content between languages, answer questions based on workspace content, and assist with writing tasks. From a system design perspective, AI integration requires careful consideration of context window management, latency optimization (streaming responses), cost management (LLM inference is expensive), and privacy (ensuring workspace data is not leaked to model training pipelines).

Collaboration and Sharing

Every feature in Notion supports real-time collaboration. Multiple users can edit the same page simultaneously, with changes appearing in real-time via colored cursors. Sharing can be configured at the workspace level, team space level, or individual page level. Public sharing allows pages to be published to the web with custom domains. Guest access enables external collaborators to view or edit specific pages without full workspace membership.

3. System Architecture Overview

The system architecture of a Notion-class platform must balance several competing concerns. It must support flexible, deeply nested data structures while maintaining query performance. It must enable real-time collaboration while preserving data consistency. It must enforce fine-grained permissions at every access point while keeping authorization checks fast. And it must scale horizontally to serve millions of users while providing sub-100ms response times.

Client Layer

The client layer encompasses the web application (built with React), the desktop application (built with Electron), and the mobile applications (built with React Native). All three share a common core rendering engine and data synchronization layer. The client maintains a local block tree that mirrors the server-side data structure, enabling instant rendering and offline support. When a user makes an edit, the client applies it locally for immediate visual feedback, then sends the change to the server asynchronously. This optimistic update pattern is critical for perceived performance.

API Gateway

All client requests pass through an API gateway built on Node.js. The gateway handles authentication (verifying JWT tokens), rate limiting (preventing abuse), request routing (directing to the appropriate service), and response caching (serving frequently accessed pages from cache). The gateway uses a ring-buffer rate limiter that enforces per-user limits: 1000 requests per minute for reads, 200 requests per minute for writes, and 50 requests per minute for search queries.

Application Services

The application layer is decomposed into domain-specific services, each responsible for a distinct bounded context. The Page Service manages page CRUD operations and page hierarchy. The Block Service handles individual block creation, updates, deletion, and tree manipulation. The Database Service manages database schemas, views, filters, sorts, formulas, relations, and rollups. The Collaboration Service coordinates real-time editing sessions via WebSockets and manages CRDT state synchronization. The Search Service handles indexing, querying, and ranking of searchable content. The AI Service manages prompt construction, context retrieval, LLM inference, and response streaming. The File Service handles upload, storage, transformation, and delivery of media files. The Permission Service enforces access control at the workspace, team space, page, and block levels.

Data Layer

The data layer uses a polyglot persistence approach. PostgreSQL serves as the primary relational database, storing workspace metadata, user accounts, permission records, database schemas, and page hierarchy. Its ACID transaction support is essential for operations that modify page structure or permission grants. Cassandra provides the distributed storage engine for block data, chosen for its ability to handle massive write throughput and linear horizontal scaling. Redis serves as the caching layer, storing hot pages, user sessions, permission caches, and real-time collaboration state. Elasticsearch powers full-text search with support for fuzzy matching, faceted filtering, and relevance ranking. Amazon S3 stores all uploaded files with CloudFront CDN providing edge-cached delivery. Neo4j stores the page graph, modeling relationships between pages to enable features like the Linked References panel.

Message Infrastructure

Apache Kafka serves as the event streaming backbone, decoupling services and enabling asynchronous processing. Key event streams include block-update events, page-structure events, permission-change events, and AI-request events. Socket.io WebSocket servers handle real-time bidirectional communication for collaborative editing, live cursors, presence indicators, and push notifications.

This architecture provides the separation of concerns, independent scalability, and technology flexibility required to build a production-grade Notion alternative. Each component can be evolved, scaled, and replaced independently as requirements change.

4. Block-Based Data Model — Nested Blocks, Children, Revision History

The block-based data model is the conceptual foundation upon which the entire Notion platform is built. Every piece of content in Notion — from a single character of text to an entire database with thousands of records — is represented as a block. Blocks are organized into a tree structure through parent-child relationships, enabling the infinite nesting that gives Notion its compositional power.

Block Entity Design

Each block is identified by a globally unique ID (UUID v4) and carries a set of core properties shared across all block types, plus type-specific properties that define the block's content and behavior. The core properties include the block ID, workspace ID, parent ID (the ID of the parent block, or null for root blocks), block type, creation timestamp, last modification timestamp, created-by user ID, and last-edited-by user ID.

C#
public class Block
{
    public Guid Id { get; set; }
    public Guid WorkspaceId { get; set; }
    public Guid? ParentId { get; set; }
    public BlockType Type { get; set; }
    public string TypeData { get; set; }
    public List<Guid> Children { get; set; }
    public int Position { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime UpdatedAt { get; set; }
    public Guid CreatedBy { get; set; }
    public Guid UpdatedBy { get; set; }
    public int Version { get; set; }
    public bool IsDeleted { get; set; }
}

public enum BlockType
{
    Paragraph, Heading1, Heading2, Heading3, BulletList,
    NumberedList, ToDo, Toggle, Quote, Callout, Divider,
    Image, Video, Audio, File, Bookmark, Embed, CodeBlock,
    Equation, Table, Database, SyncedBlock, ColumnLayout,
    Breadcrumb, TableOfContents, Template, LinkToPage
}

public class RichTextSegment
{
    public string Text { get; set; }
    public Guid? UserId { get; set; }
    public TextFormatting? Formatting { get; set; }
    public string? Link { get; set; }
    public string? MentionType { get; set; }
    public string? MentionValue { get; set; }
}

Tree Structure and Nesting

The block tree is organized through explicit parent-child references. Each block stores a ParentId pointing to its parent block, and the parent stores an ordered list of Children IDs representing its children in display order. This design enables efficient subtree operations: loading a page means fetching all descendant blocks of the page block; moving a subtree means updating the parent reference of the subtree root. The maximum nesting depth is enforced at 50 levels to prevent performance degradation.

Rich Text Storage

Rich text is stored as an ordered list of RichTextSegment objects, where each segment carries its own formatting attributes. This inline style approach is modeled after how modern collaborative editors like Google Docs represent text. A single paragraph might contain segments like: Hello (plain), world (bold + italic), with (plain, link to URL), Notion (bold, colored blue). Each segment is an independent unit that can be formatted, moved, or deleted without affecting adjacent segments.

Position and Ordering

Block ordering within a parent uses a fractional indexing scheme. Rather than storing integer positions that require renumbering when blocks are inserted, each block is assigned a string-based position key that falls alphabetically between its neighbors. For example, if a parent has children with positions a0, a1, a2, inserting a new block between a0 and a1 assigns it position a0V. This approach eliminates position conflicts in concurrent editing scenarios and avoids the O(n) renumbering cost of integer positions.

Revision History

Every block modification creates a new revision record that captures the before and after states. Revisions are stored in a separate append-only table partitioned by block ID and time range. The revision store captures the full block content at each change, enabling point-in-time recovery and the page history feature. To manage storage costs, revisions are compacted: hourly snapshots for the past 7 days, daily snapshots for the past 30 days, and weekly snapshots for the past year.

This block-based data model provides the foundation for everything that follows. The tree structure enables flexible content organization, the rich text model supports precise formatting, fractional indexing enables conflict-free ordering, and the revision system provides complete audit trails.

5. Real-Time Collaboration — CRDT-Based WebSocket Sync

Real-time collaboration is arguably the most technically challenging feature of a Notion-class platform. When multiple users edit the same page simultaneously, the system must merge their changes consistently, resolve conflicts without data loss, and propagate updates with minimal latency.

Why CRDTs Over Operational Transforms

Traditional collaborative editors like Google Docs use Operational Transforms (OT), where a central server receives operations from clients, transforms them against concurrent operations, and broadcasts the transformed operations to all clients. OT works well but has significant drawbacks: it requires a central server to serialize all operations, it struggles with offline editing, and the transformation logic becomes exponentially complex as operation types increase.

CRDTs solve these problems by designing data structures where concurrent operations are mathematically guaranteed to converge to the same state, regardless of the order in which they are received. Notion uses a variant of the Yjs CRDT library, which represents text as a linked list of characters, each with a unique ID (creator ID + logical timestamp). When two users insert characters at the same position concurrently, the CRDTs ordering rules deterministically resolve the conflict, ensuring both clients converge to the same document state.

WebSocket Protocol Design

The WebSocket protocol handles three types of messages: sync messages (CRDT operations that modify document content), presence messages (cursor positions, selections, and user activity), and control messages (join/leave session, request full state, acknowledge receipt). Each WebSocket connection is associated with a specific page and user. The server maintains an in-memory CRDT state for each active page.

C#
public class CollaborationHub : Hub
{
    private readonly CRDTStore _crdtStore;
    private readonly PresenceManager _presenceManager;

    public async Task JoinPage(string pageId, string userId)
    {
        await Groups.AddToGroupAsync(Context.ConnectionId, pageId);
        var crdtState = await _crdtStore.GetOrCreate(pageId);
        await Clients.Caller.SendAsync("SyncState", crdtState.CurrentState);
        var presence = await _presenceManager.GetPagePresence(pageId);
        await Clients.Caller.SendAsync("PresenceUpdate", presence);
        await Clients.OthersInGroup(pageId).SendAsync("UserJoined", userId);
    }

    public async Task ApplyOperation(string pageId, string userId, CRDTOperation op)
    {
        var validation = ValidateOperation(op);
        if (!validation.IsValid)
        {
            await Clients.Caller.SendAsync("OperationRejected", validation.Reason);
            return;
        }
        var mergedOp = _crdtStore.Apply(pageId, op);
        await Clients.OthersInGroup(pageId)
            .SendAsync("RemoteOperation", mergedOp, userId);
        await _crdtStore.EnqueueForPersistence(pageId, mergedOp);
    }

    public async Task UpdatePresence(string pageId, string userId, CursorPosition cursor)
    {
        await _presenceManager.UpdateCursor(pageId, userId, cursor);
        await Clients.OthersInGroup(pageId)
            .SendAsync("PresenceUpdate", userId, cursor);
    }
}

State Synchronization

When a client joins a page, it receives the current CRDT state from the server. This state is a compressed representation of the document, typically much smaller than the full operation history. The client reconstructs its local document from this state and then applies subsequent operations incrementally. If a client disconnects and reconnects, it sends its last known state vector to the server, which computes a diff containing only the operations the client missed.

Presence and Awareness

Beyond document editing, the collaboration system tracks user presence: cursor positions, text selections, which page each user is viewing, and whether users are actively typing. Presence information is ephemeral and does not need to be persisted. Presence updates are broadcast every 100ms via the WebSocket connection, with throttling applied to reduce bandwidth.

Scaling Collaboration

The collaboration servers are the most stateful component in the system. Each server maintains in-memory CRDT states for all active pages on that node. When a page has more than 50 concurrent editors, it is migrated to a dedicated hot page server with more memory and CPU. The WebSocket connections use sticky sessions via consistent hashing on page ID to ensure all editors of the same page connect to the same server. In production, the collaboration layer handles approximately 500,000 concurrent WebSocket connections, processing 2-3 million operations per second during peak hours.

6. Database Engine — Views, Filters, Sorts, Relations, Rollups

Notion's database engine is one of its most complex subsystems. Unlike traditional relational databases where schemas are rigid and queries are written in SQL, Notion provides a visual, user-configurable database system where anyone can create databases, define property schemas, configure multiple views, and apply filters and sorts without writing code.

Database Schema Model

A Notion database is defined by its schema — an ordered list of property definitions. Each property has a name, type, and type-specific configuration. The schema is stored as a JSON document associated with the database block. The database engine reads this schema and uses it to validate data, enforce type constraints, compute formulas, and resolve relations.

C#
public class DatabaseSchema
{
    public Guid DatabaseId { get; set; }
    public List<PropertyDefinition> Properties { get; set; }
    public Dictionary<string, ViewDefinition> Views { get; set; }
    public DateTime SchemaVersion { get; set; }
}

public enum PropertyType
{
    Title, RichText, Number, Select, MultiSelect, Date,
    Person, Files, Checkbox, URL, Email, Phone,
    Formula, Relation, Rollup, CreatedTime, CreatedBy,
    LastEditedTime, LastEditedBy, UniqueId, Status
}

public class ViewDefinition
{
    public Guid ViewId { get; set; }
    public string Name { get; set; }
    public ViewType Type { get; set; }
    public List<FilterGroup> Filters { get; set; }
    public List<SortDefinition> Sorts { get; set; }
    public List<Guid> VisibleProperties { get; set; }
    public string? GroupBy { get; set; }
}

public enum FilterOperator
{
    Equals, DoesNotEqual, Contains, DoesNotContain,
    StartsWith, EndsWith, IsEmpty, IsNotEmpty,
    GreaterThan, LessThan, GreaterOrEqual, LessOrEqual,
    IsBefore, IsAfter, IsOnOrBefore, IsOnOrAfter,
    IsToday, IsPast, IsFuture
}

Query Execution Pipeline

When a user opens a database view, the system must execute a query that: (1) loads all rows matching the view's filter conditions, (2) sorts the results according to the view's sort definitions, (3) computes derived properties (formulas and rollups), (4) groups results if a group-by column is specified, and (5) paginates the results for efficient rendering.

Relation and Rollup System

Relations link records across databases, creating the relational structure that makes Notion databases powerful. A relation property on database A pointing to database B stores references to records in B. Rollup properties then aggregate data from related records — counting them, summing a numeric property, showing all values, computing averages, or running custom formulas over the related set.

Performance optimization for the database engine focuses on three areas: index design (automatic indexes on frequently filtered/sorted properties), query optimization (evaluating high-selectivity conditions first), and caching (frequently accessed views cached at the query level).

7. Notion AI Integration — Page Generation, Summarization, Q&A

Notion AI represents the integration of large language models directly into the workspace experience. Unlike external AI tools that require users to copy-paste content, Notion AI operates within the document context — reading surrounding content, understanding page structure, and generating output that seamlessly blends with existing content.

Context Window Management

The most critical design challenge is constructing the optimal context window for each LLM request. The context builder must assemble a prompt that includes: the user's explicit request, the current page content, related pages and database entries, workspace-level knowledge base content, and conversation history. The builder allocates token budgets: 40% for page content, 15% for conversation history, 25% for related content via vector search, and 20% for database context.

C#
public class AIContextBuilder
{
    private readonly IBlockRetriever _blockRetriever;
    private readonly IVectorSearchService _vectorSearch;
    private readonly ITokenCounter _tokenCounter;

    public async Task<AIContext> BuildContext(AIRequest request, int maxTokens)
    {
        var context = new AIContext();
        int remaining = maxTokens;

        context.Instruction = request.Instruction;
        remaining -= _tokenCounter.Count(request.Instruction);

        int pageBudget = (int)(maxTokens * 0.4);
        var pageContent = await _blockRetriever.GetPageContent(
            request.PageId, pageBudget);
        context.PageContent = pageContent;
        remaining -= _tokenCounter.Count(pageContent.Serialized);

        if (request.SelectedText != null)
        {
            context.SelectionContext = request.SelectedText;
            remaining -= _tokenCounter.Count(request.SelectedText);
        }

        int relationBudget = (int)(maxTokens * 0.25);
        var related = await _vectorSearch.FindRelevant(
            request.Instruction + " " + pageContent.Serialized,
            request.WorkspaceId, relationBudget);
        context.RelatedContent = related;
        remaining -= _tokenCounter.Count(related.Serialized);

        context.TotalTokensUsed = maxTokens - remaining;
        return context;
    }
}

Retrieval-Augmented Generation

For workspace Q&A, Notion employs a RAG pipeline. When a user asks a question, the system embeds the query, searches the vector index for semantically similar content chunks, retrieves the top-k most relevant chunks, and sends them to the LLM. The pipeline handles chunking documents (256-512 tokens per chunk), maintaining chunk-to-source mappings for citation, handling multi-hop questions, and respecting permissions.

Streaming and Latency

LLM inference generates tokens sequentially, meaning a complete response might take 5-30 seconds. To maintain responsiveness, Notion streams the response token-by-token using Server-Sent Events. The client displays a typing indicator immediately, then renders tokens as they arrive, reducing perceived latency from 10+ seconds to under 200ms (time to first token).

Cost Management

LLM inference is expensive, with GPT-4-class models costing approximately $30 per million input tokens and $60 per million output tokens. For a platform with millions of users, uncontrolled AI usage could generate millions of dollars in monthly API costs. Notion manages costs through per-user rate limiting where free users get limited AI actions and paid users get more allocations, context window optimization by minimizing input tokens through intelligent chunking and compression, model routing to use smaller cheaper models for simple tasks like grammar correction while reserving expensive models for complex generation, caching results for identical or similar queries, and usage analytics tracking per-user and per-workspace AI consumption to identify abuse patterns and optimize pricing tiers.

Privacy and Safety

Workspace data used in AI prompts must never be used for model training. Notion's AI integration uses the model providers' enterprise APIs which guarantee data isolation and do not retain input data for training purposes. All prompts are transmitted over encrypted connections, and workspace content is stripped of personally identifiable information before being included in prompts when possible. The AI service maintains a data processing agreement with each model provider, ensuring compliance with GDPR and SOC 2 requirements. Users can opt out of AI features entirely at the workspace level, and enterprise customers can configure data residency to ensure AI processing occurs within specific geographic regions.

8. Search and Discovery — Full-Text, Filters, Permissions

Search is one of the most critical features in a productivity platform. Users accumulate thousands of pages and database entries over time, and the ability to quickly find specific content is essential. Notion's search system must handle full-text queries across diverse content types, respect complex permission boundaries, support filtering and sorting, and deliver results in under 200 milliseconds.

Indexing Pipeline

The search indexing pipeline processes block-update events from Kafka, extracts searchable content, and updates the Elasticsearch index. For each block, the indexer extracts: full text content, block title, file names and OCR text, code content, database property values, and metadata. The extracted content is tokenized, stemmed, and stored with field-level boosts: title matches weighted 3x, heading matches 2x, body text matches 1x.

C#
public class SearchIndexer
{
    private readonly IElasticClient _elastic;
    private readonly IPermissionChecker _permissionChecker;

    public async Task<SearchResult> SearchAsync(SearchQuery query, Guid userId)
    {
        var accessiblePages = await _permissionChecker
            .GetAccessiblePageIds(userId, query.WorkspaceId);

        var searchRequest = new SearchRequest("notion-search")
        {
            Query = BuildQuery(query),
            Filter = new FilterDescriptor<SearchDocument>()
                .Terms(t => t.Field(f => f.PageId).Terms(accessiblePages)),
            Highlight = new HighlightDescriptor<SearchDocument>()
                .Fields(
                    f => f.Field(d => d.Title).PreTags("<mark>").PostTags("</mark>"),
                    f => f.Field(d => d.Body).PreTags("<mark>").PostTags("</mark>")),
            Size = query.PageSize,
            From = (query.Page - 1) * query.PageSize
        };

        var response = await _elastic.SearchAsync<SearchDocument>(searchRequest);
        return MapToResults(response, query);
    }
}

Permission-Aware Search

Every search query must be filtered by the user's permissions. The permission checker maintains a pre-computed index mapping each page to the set of user groups that can access it. When a search is executed, the system retrieves the list of accessible page IDs and adds a terms filter to the Elasticsearch query, ensuring permission filtering happens at the database level.

Search Features and Operators

Notion's search supports several advanced features beyond basic full-text search. Filters allow users to narrow results by content type (pages, databases, images, code), date range (last modified, created), author, workspace, and specific database properties. Operators enable power-user queries: quoted phrases for exact matching, minus signs for exclusions, OR for union queries, and site: for workspace-scoped searches. Autocomplete suggests page titles and recent searches as users type, using a prefix-based index that returns results in under 50ms. Quick Find provides instant results for known page titles using a client-side cache of the user's most frequently accessed pages.

Search Analytics and Optimization

The search system logs every query including the query text, filters applied, results returned, and which result the user selected. This data drives continuous optimization: queries with no result selections indicate either poor relevance or missing content, queries that select the 10th result or later suggest the ranking algorithm needs adjustment, and frequent queries reveal common information needs that could be addressed through shortcuts or dashboard widgets. A weekly retraining pipeline analyzes search analytics data and adjusts ranking weights, field boosts, and synonym dictionaries to improve relevance over time. The analytics pipeline also tracks zero-result queries to identify content gaps and suggests relevant pages that the user may not have discovered through manual browsing.

9. Template System and Marketplace

Templates are a critical growth mechanism for Notion. They lower the barrier to entry by providing pre-built page structures, database configurations, and workflow setups that users can instantiate with a single click. The template system encompasses template creation tools, a template marketplace, a versioning and distribution system, and a runtime instantiation engine.

Template Data Model

A template is represented as a special page with an associated template definition. The definition includes metadata (title, description, category, preview images, pricing), the template's block tree, database schema definitions, configuration settings, and version history. Templates can be nested — a Project Management System template might include a main dashboard page, a tasks database, a docs database, and a meeting notes page.

Template Instantiation

When a user installs a template, the instantiation engine clones the template's block tree into the user's workspace. This is not a simple deep copy — the engine must generate new UUIDs for all cloned blocks, resolve internal links between cloned blocks, clone database schemas without original data, replace placeholder content (template variables like company_name and date), and preserve hierarchical relationships. The cloning process is transactional — either all blocks are cloned successfully or none are.

Template versioning uses semantic versioning: patch versions for content fixes, minor versions for new optional features, and major versions for structural changes. The update process is incremental, comparing old and new versions and applying only structural differences while respecting user customizations.

10. API and Integrations — Public API, Zapier, Slack

Notion's platform value is amplified by its integration ecosystem. The public API allows developers to programmatically create, read, update, and delete pages, databases, and blocks. Third-party integrations through platforms like Zapier, Make, and n8n connect Notion to thousands of other applications.

API Design

Notion's public API follows RESTful design principles with JSON payloads. Resources are organized hierarchically: /v1/workspaces/{workspace_id}/pages/{page_id}/blocks. Rate limiting is enforced per integration: free integrations get 3 requests per second, paid integrations get 10, and enterprise integrations get 50.

C#
[ApiController]
[Route("v1")]
[ServiceFilter(typeof(ApiKeyAuthFilter))]
public class NotionApiController : ControllerBase
{
    private readonly IPageService _pageService;
    private readonly IBlockService _blockService;
    private readonly IRateLimiter _rateLimiter;
    private readonly IPermissionChecker _permissionChecker;

    [HttpGet("pages/{pageId}")]
    public async Task<IActionResult> GetPage(Guid pageId)
    {
        var apiKey = GetApiKey();
        await _rateLimiter.CheckLimit(apiKey, RateLimitTier.Read);

        if (!await _permissionChecker.HasAccess(
            apiKey.IntegrationId, pageId, AccessLevel.Read))
            return Forbid();

        var page = await _pageService.GetPage(pageId);
        return Ok(PageResponse.FromEntity(page));
    }

    [HttpPost("databases/{databaseId}/query")]
    public async Task<IActionResult> QueryDatabase(
        Guid databaseId, [FromBody] DatabaseQueryRequest request)
    {
        var apiKey = GetApiKey();
        await _rateLimiter.CheckLimit(apiKey, RateLimitTier.Read);

        if (!await _permissionChecker.HasAccess(
            apiKey.IntegrationId, databaseId, AccessLevel.Read))
            return Forbid();

        var results = await _databaseService.Query(
            databaseId, request.ToQuery());
        return Ok(DatabaseQueryResponse.FromResults(results));
    }
}

Webhook and Event System

For real-time integrations, Notion provides a webhook system that pushes events to registered endpoints. Events include page.created, page.updated, page.deleted, database.row.created, database.row.updated, and comment.created. Events are delivered as JSON payloads with signature verification, unique event IDs for idempotency, and exponential backoff for failed deliveries.

The integration layer processes approximately 50,000 API requests per second from third-party integrations. The webhook delivery system processes 100,000 events per minute with dedicated delivery workers managing retry logic, signature computation, and dead-letter queue processing.

11. File Upload and Media Management

Notion supports images, videos, audio, documents (PDF, DOCX), and generic file attachments. File uploads occur through the editor (drag-and-drop), the public API, clipboard paste, and integrations. The file management system must handle large files efficiently, provide fast CDN delivery, and respect workspace storage quotas.

Upload Pipeline

File uploads use a pre-signed URL pattern: the client requests a time-limited S3 pre-signed URL, uploads directly to S3, and S3 triggers processing. This avoids routing large payloads through application servers.

Storage Quotas

Each workspace has a storage quota based on subscription tier. The storage service tracks per-workspace usage by summing file sizes including derivatives. Usage is calculated hourly and exposed through workspace settings. Notifications are sent at 80% and 95% usage thresholds.

All file delivery goes through CloudFront CDN with edge locations in 40+ regions. Configuration includes gzip and Brotli compression, HTTP/2 multiplexing, and origin shield to reduce S3 request costs.

12. Permission and Access Control — Workspace, Page-Level

Notion's permission system must enforce access control at multiple granularity levels — workspace, team space, page, and block — while remaining fast enough to not impact page load times. The system must support complex hierarchies where permissions are inherited from parent pages but can be overridden at child pages.

Permission Model

Notion implements a hierarchical permission model with four levels. At the workspace level, all members have access with roles (Owner, Admin, Member, Guest). At the team space level, team spaces group pages with restricted access. At the page level, individual pages can be shared with specific users with access levels: Full Access, Can Edit, Can Comment, and Can View. Page-level permissions inherit from parent pages by default but can be explicitly overridden.

C#
public class PermissionChecker
{
    private readonly IPermissionStore _store;
    private readonly ICacheService _cache;

    public async Task<PermissionLevel> CheckAccess(
        Guid userId, Guid resourceId, ResourceType resourceType)
    {
        var cacheKey = $"perm:{userId}:{resourceId}";
        var cached = await _cache.GetAsync<PermissionLevel>(cacheKey);
        if (cached.HasValue) return cached.Value;

        var permission = await ComputeAccess(userId, resourceId, resourceType);
        await _cache.SetAsync(cacheKey, permission, TimeSpan.FromSeconds(30));
        return permission;
    }

    private async Task<PermissionLevel> ComputeAccess(
        Guid userId, Guid resourceId, ResourceType resourceType)
    {
        var userGroups = await _store.GetUserGroups(userId);
        var direct = await _store.GetDirectPermission(resourceId, userId, userGroups);
        if (direct != null) return direct.Value;

        var currentId = resourceId;
        var currentType = resourceType;

        while (currentId != Guid.Empty)
        {
            var parent = await _store.GetParent(currentId, currentType);
            if (parent == null) break;

            var parentPerm = await _store.GetDirectPermission(
                parent.Id, userId, userGroups);
            if (parentPerm != null)
            {
                var hasOverride = await _store.HasPermissionOverride(
                    currentId, currentType);
                if (!hasOverride) return parentPerm.Value;
            }
            currentId = parent.Id;
            currentType = parent.Type;
        }

        return PermissionLevel.None;
    }
}

public enum PermissionLevel
{
    None = 0, CanView = 1, CanComment = 2,
    CanEdit = 3, FullAccess = 4, Owner = 5
}

Permission checks are cached in Redis with a 30-second TTL. When permissions are modified, affected cache entries are invalidated using a publish-subscribe pattern. For deeply nested hierarchies, the system pre-computes effective permission sets for each user on the workspace root.

Audit Logging

All permission changes are logged to an append-only audit log capturing the actor, target, action, old and new permission levels, and timestamp. Audit logs are retained for 1 year on Business plans and 7 years on Enterprise plans. Enterprise customers can export audit logs through the admin API for compliance purposes.

13. Offline Support and Sync

Offline support is essential for a productivity platform used across desktop, mobile, and web. Users expect to read, edit, and create content regardless of network connectivity, with changes automatically syncing when connectivity is restored.

Client-Side Storage

The client maintains a local SQLite database (desktop/mobile) or IndexedDB (web) storing recently accessed pages (last 100, up to 50K blocks), favorited pages, page metadata for navigation, and user profile information. The local store uses version vectors for conflict detection.

C#
public class OfflineSyncEngine
{
    private readonly LocalBlockStore _localStore;
    private readonly ISyncApiClient _syncClient;

    public async Task<SyncResult> SyncAsync(Guid workspaceId)
    {
        var result = new SyncResult();
        var localVersion = await _localStore.GetVersionVector(workspaceId);

        var remoteChanges = await _syncClient.GetChanges(
            workspaceId, localVersion);

        foreach (var change in remoteChanges)
        {
            var localBlock = await _localStore.GetBlock(change.BlockId);
            if (localBlock == null)
            {
                await _localStore.UpsertBlock(change.Block);
                result.PullCount++;
            }
            else if (localBlock.Version < change.Block.Version)
            {
                if (localBlock.IsDirty)
                {
                    var merged = await MergeBlocks(localBlock, change.Block);
                    await _localStore.UpsertBlock(merged);
                    result.Conflicts++;
                }
                else
                {
                    await _localStore.UpsertBlock(change.Block);
                    result.PullCount++;
                }
            }
        }

        var dirtyBlocks = await _localStore.GetDirtyBlocks(workspaceId);
        foreach (var block in dirtyBlocks)
        {
            var pushResult = await _syncClient.PushBlock(block);
            if (pushResult.Success)
            {
                block.IsDirty = false;
                await _localStore.UpsertBlock(block);
                result.PushCount++;
            }
        }
        return result;
    }
}

Conflict Resolution

When a conflict is detected, the resolver applies a strategy based on block type. For text blocks, the CRDT merge algorithm combines changes without data loss. For structural changes, the most recent change wins with the losing change preserved in history. For database cells, each cell is merged independently.

The offline sync system ensures Notion remains functional regardless of network conditions, providing a seamless experience bridging online and offline usage.

14. Performance Optimization — Lazy Loading, Virtual Scrolling

Performance is a defining characteristic of a great productivity tool. Users interact with Notion dozens of times per day, and even small latency penalties compound into significant productivity losses. A page that takes 2 seconds instead of 200ms costs a user 30+ minutes per year in waiting.

Lazy Block Loading

Notion pages can contain thousands of blocks, but the visible viewport shows only 15-20 blocks. When a page opens, only the first 50 blocks are fetched. As the user scrolls, additional blocks are fetched in batches of 50. Blocks beyond the load boundary render as skeleton placeholders until loaded.

Virtual Scrolling for Databases

Database views with thousands of rows use virtual scrolling: only rows visible in the viewport (plus a buffer) are rendered. As the user scrolls, rows entering the viewport are rendered and rows leaving are removed. The virtual scroller maintains a fixed-height container representing the full dataset, keeping DOM node count constant at 30-50 rows regardless of dataset size.

Frontend Performance

The React-based client uses code splitting (only current page code loaded), React.memo and useMemo (prevent unnecessary re-renders), Web Workers (CPU-intensive operations off main thread), and requestAnimationFrame (batch DOM updates aligned with paint cycle). These keep main thread response time under 16ms during normal editing.

Backend Performance

Server-side strategy focuses on hot-path optimization. Page loading fetches the page block and first-level children in a single query. Database queries use prepared statements and connection pooling. WebSocket collaboration keeps CRDT state in memory for sub-millisecond operations. Circuit breakers protect against cascading failures.

Performance budgets are enforced: FCP under 1.2s, LCP under 2.5s, FID under 100ms, CLS under 0.1 on the client; p50 under 50ms, p95 under 200ms, p99 under 500ms on the server.

15. Multi-Workspace and Team Management

Notion supports multi-workspace where a single user account belongs to multiple workspaces. Each workspace is completely isolated with its own pages, databases, members, settings, and billing.

Team Spaces

Within a workspace, team spaces provide organization and access control. Team spaces group pages and databases around specific teams (Engineering, Marketing). Team spaces can be open or closed (requiring approval). Pages within a team space are accessible to team members but not to other workspace members.

Workspace Provisioning

Enterprise customers require automated user provisioning via SCIM 2.0. When a user is added to the identity provider, they are automatically provisioned with a Notion account and added to the appropriate workspace. When deprovisioned, their account is immediately deactivated. SCIM also synchronizes group memberships, automatically adding users to appropriate team spaces.

Content transfer between workspaces is supported for migrations: the system clones selected pages including block trees, databases, and file references. File attachments are copied to the target workspace's storage bucket. The transfer is non-destructive and runs asynchronously for large operations.

Workspace Analytics and Insights

Enterprise administrators need visibility into workspace usage patterns to optimize adoption and identify underutilized resources. The analytics dashboard provides metrics on active users (daily, weekly, monthly), content growth trends (pages created, blocks edited, files uploaded), search query patterns (top queries, zero-result queries), storage consumption (by content type, by user, over time), and integration usage (which integrations are active, API call volumes). Analytics data is aggregated from event logs using a batch processing pipeline that runs hourly, with results stored in a dedicated analytics database optimized for time-series queries. Dashboard widgets render charts and tables using a client-side visualization library, with data refreshed every 15 minutes for near-real-time visibility into workspace health and engagement metrics.

16. Import/Export and Migration Tools

Data portability is a core principle. Users must bring existing content into Notion and export content for backup, compliance, or migration. Notion supports imports from over a dozen formats and exports to several formats.

Import Pipeline

The import pipeline converts content from external formats into Notion's block-based data model. Each import source has a dedicated parser. The pipeline handles Evernote ENEX files (preserving notebooks as pages and tags as properties), Markdown files (converting syntax to blocks), Microsoft Word DOCX files (preserving headings, tables, and images), Confluence spaces (maintaining page hierarchies and labels), Google Docs (converting collaborative edits to blocks), Trello boards (mapping cards to database entries), and CSV/TSV files (creating database entries from rows).

C#
public class ImportPipeline
{
    private readonly Dictionary<string, IImportParser> _parsers;
    private readonly IBlockService _blockService;
    private readonly IFileService _fileService;

    public async Task<ImportResult> ImportAsync(ImportRequest request)
    {
        var parser = _parsers[request.SourceFormat];
        var parsed = await parser.Parse(request.FileStream);

        var result = new ImportResult();
        var rootPage = await _blockService.CreatePage(
            request.WorkspaceId, parsed.Title);

        foreach (var parsedBlock in parsed.Blocks)
        {
            var block = await ConvertToBlock(parsedBlock, request.WorkspaceId);
            await _blockService.AppendBlock(rootPage.Id, block);
            result.BlocksImported++;

            if (parsedBlock.HasAttachments)
            {
                foreach (var attachment in parsedBlock.Attachments)
                {
                    var fileRef = await _fileService.UploadFile(
                        request.WorkspaceId, attachment);
                    await _blockService.UpdateBlockFile(block.Id, fileRef);
                    result.FilesImported++;
                }
            }
        }

        result.RootPageId = rootPage.Id;
        return result;
    }
}

Export Formats

Notion exports content as Markdown (individual page files in a ZIP archive), CSV (database entries as spreadsheet rows), HTML (formatted pages with embedded images), or PDF (rendered pages with formatting preserved). The export system runs asynchronously for large workspaces, generating a download link that is emailed to the user when ready.

Migration Tools

For enterprise migrations, Notion provides a Migration API that enables programmatic content transfer. The API supports batch operations (creating 1000 blocks per request), webhook notifications for progress tracking, and rollback capabilities. The migration service handles idempotency (safe to retry), partial failure recovery (failed blocks are retried independently), and progress reporting (percentage complete with ETA estimation).

The bidirectional import/export capability ensures that Notion never creates a data lock-in situation. Users can freely move content in and out of the platform, which builds trust and encourages adoption.

Migration Validation

After import completion, the migration system runs a validation pass that checks for common issues: broken internal links where a page references another page that failed to import, orphaned blocks that lost their parent reference during conversion, missing file attachments where uploaded files could not be downloaded from the source, and encoding issues where special characters were corrupted during format conversion. The validation report is presented to the user with clear descriptions of each issue and suggested remediation steps. For critical issues like broken links, the system offers automatic repair by searching the imported content for the most likely target page based on title similarity. This validation step ensures that imported content is immediately usable rather than requiring extensive manual cleanup by the user.

17. Notion Sync Protocol and Conflict Resolution

The synchronization protocol is the nervous system of Notion's collaborative architecture, governing how changes flow between clients, servers, and other clients in real time. While the CRDT-based collaboration system described earlier handles concurrent text editing, the broader sync protocol must address a much wider range of synchronization challenges: structural changes to the block tree, database schema modifications, permission updates, file uploads, and offline-to-online transitions. Designing a unified sync protocol that handles all these scenarios efficiently and correctly is one of the most complex engineering challenges in building a Notion-class platform.

Protocol Architecture Overview

Notion's sync protocol operates on three layers: the transport layer (WebSocket connections with automatic reconnection and message ordering), the operation layer (CRDT operations for text and monotonic sequence numbers for structural changes), and the persistence layer (asynchronous writes to the primary database with conflict detection). Each layer is designed to handle network partitions, message reordering, and duplicate delivery gracefully.

Operation Types and Classification

Notion's sync protocol distinguishes between two fundamental operation categories: concurrent operations and total-order operations. Concurrent operations can be applied in any order and still converge to the same state, thanks to CRDT mathematics. These include text insertions, text deletions, formatting changes within rich text segments, and cursor position updates. Total-order operations require strict serialization to maintain correctness. These include block creation, block deletion, block moves (changing parent or position), database schema changes, permission modifications, and page creation/deletion.

C#
public class SyncOperation
{
    public Guid OperationId { get; set; }
    public Guid UserId { get; set; }
    public Guid PageId { get; set; }
    public OperationCategory Category { get; set; }
    public long SequenceNumber { get; set; }
    public DateTime Timestamp { get; set; }
    public string Payload { get; set; }
    public Guid? DependsOn { get; set; }
    public OperationStatus Status { get; set; }
}

public enum OperationCategory
{
    Concurrent,    // CRDT: text edits, formatting
    TotalOrder,    // Serialized: structure, permissions
    Metadata       // Non-critical: presence, typing indicators
}

public class OperationQueue
{
    private readonly ConcurrentDictionary<Guid, SortedList<long, SyncOperation>>
        _pendingByPage;
    private readonly SequenceGenerator _seqGen;

    public async Task<SyncOperation> Enqueue(SyncOperation op)
    {
        if (op.Category == OperationCategory.TotalOrder)
        {
            op.SequenceNumber = await _seqGen.Next(op.PageId);
            op.DependsOn = await _seqGen.GetLastApplied(op.PageId);
        }
        else
        {
            op.SequenceNumber = DateTime.UtcNow.Ticks;
        }

        var pageOps = _pendingByPage.GetOrAdd(
            op.PageId, _ => new SortedList<long, SyncOperation>());
        lock (pageOps)
        {
            pageOps[op.SequenceNumber] = op;
        }
        return op;
    }
}

Sequence Number Generation

For total-order operations, the protocol uses a centralized sequence generator that assigns monotonically increasing sequence numbers per page. This ensures a global total order for structural operations within a single page, preventing conflicting block moves or schema changes from being applied out of order. The sequence generator is hosted on the collaboration server that owns the page (determined by consistent hashing on page ID), eliminating the need for distributed consensus. In case of server failure, the sequence generator can be reconstructed by scanning the operation log for the highest applied sequence number.

Conflict Detection and Resolution

When a client sends a total-order operation, the server validates it against the current state. The validation checks include: does the referenced block still exist (not deleted), does the parent block exist and is the operation's user permitted to modify it, is the operation's dependency (DependsOn) satisfied (the operation it depends on has been applied), and does the operation conflict with another operation that was applied concurrently. If validation passes, the operation is applied and broadcast. If validation fails, the server sends a rejection with the reason and the current state, prompting the client to rebase its operation.

Offline-to-Online Synchronization

The offline-to-online transition is the most complex sync scenario. When a client reconnects after being offline, it may have accumulated a mix of concurrent and total-order operations. The sync protocol handles this through a three-phase reconciliation: first, the client sends its version vector to the server, identifying all operations it has applied locally; second, the server computes the diff (operations the server has that the client lacks, and operations the client has that the server lacks); third, the client and server exchange operations in dependency order, applying each operation after its dependencies are satisfied.

C#
public class ReconciliationEngine
{
    private readonly IOperationStore _store;
    private readonly IConflictResolver _resolver;

    public async Task<ReconciliationResult> Reconcile(
        Guid pageId, VersionVector clientVector)
    {
        var serverVector = await _store.GetServerVector(pageId);
        var result = new ReconciliationResult();

        var serverOnly = await _store.GetOperations(
            pageId, serverVector.Exclude(clientVector));
        var clientOnly = await _store.GetOperations(
            pageId, clientVector.Exclude(serverVector));

        var merged = new List<SyncOperation>();
        foreach (var op in serverOnly.Concat(clientOnly).OrderBy(o => o.SequenceNumber))
        {
            if (op.Category == OperationCategory.TotalOrder)
            {
                var conflict = merged.FirstOrDefault(m =>
                    m.Category == OperationCategory.TotalOrder &&
                    m.ConflictsWith(op));

                if (conflict != null)
                {
                    var resolved = await _resolver.Resolve(conflict, op);
                    merged.Add(resolved);
                    result.ConflictsResolved++;
                }
                else
                {
                    merged.Add(op);
                }
            }
            else
            {
                merged.Add(op);
            }
        }

        result.OperationsToApply = merged;
        result.ClientOperationsAccepted = clientOnly.Count(
            op => !serverOnly.Any(s => s.OperationId == op.OperationId));
        return result;
    }
}

Performance Optimization and Batching

The sync protocol optimizes performance through operation batching, delta compression, and priority queuing. Operation batching groups multiple consecutive operations into a single network message, reducing WebSocket overhead. Delta compression sends only the changed portion of a block rather than the entire block, critical for large database rows or long text blocks. Priority queuing ensures that high-priority operations (permission changes, block deletions) are processed before low-priority operations (presence updates, cursor movements).

The sync protocol's design ensures that Notion remains responsive under all network conditions while maintaining data correctness. The combination of CRDTs for concurrent operations, sequence-based serialization for structural operations, and a robust reconciliation engine for offline transitions creates a synchronization system that scales from individual note-taking to enterprise-wide collaboration with thousands of concurrent editors.

18. Interview Q&A — 10 Questions

Q1: How would you handle editing a page with 100,000 blocks without loading all of them into memory?

Use lazy loading with a two-tier strategy. The initial page load fetches the page block and its first 50 direct children. Each child block is loaded on-demand as the user scrolls to it. For deeply nested structures, load child blocks only when their parent toggle is expanded. Maintain a block cache with LRU eviction policy, keeping recently accessed blocks in memory and evicting blocks that haven't been accessed in the last 5 minutes. For the data layer, use Cassandra's partition-by-page strategy where all blocks on a page are stored in the same partition, enabling efficient range queries for sequential loading.

Q2: How do you ensure real-time collaboration works correctly when two users move the same block to different locations simultaneously?

Structural operations like block moves are serialized through the collaboration server, unlike text edits which use CRDTs. The server assigns monotonically increasing sequence numbers to structural operations, creating a total order. The first move to arrive at the server is applied; the second receives a conflict notification. The client then fetches the block's current location and updates its local state. This approach prevents split-brain scenarios where a block might appear in two locations simultaneously. The key insight is that while CRDTs excel at text content, structural operations require serialization for correctness.

Q3: Design the search system to handle permission-aware queries across millions of documents in under 200ms.

Pre-compute permission mappings and store them as Elasticsearch filters. When a search query arrives, retrieve the user's accessible page IDs from Redis (pre-computed and cached with 30-second TTL). Add this as a terms filter to the Elasticsearch query. Use a two-phase ranking approach: first pass applies BM25 relevance with permission filtering using Elasticsearch's native filter context (which leverages the bitset cache for fast filter evaluation). Second pass applies custom ranking signals (recency, user affinity, popularity) on the top 100 results. Cache the top 10 queries per user for instant repeated searches.

Q4: How would you design the database formula engine to handle circular references?

Implement a dependency graph for formula properties. When a formula is defined, analyze its expression to extract referenced properties. Build a directed acyclic graph (DAG) of property dependencies. Before evaluating formulas, run a topological sort on the dependency graph. If a cycle is detected during graph construction, reject the formula with a clear error message identifying the circular dependency path. For runtime evaluation, use memoization with a cycle detection guard: track the evaluation stack and throw an exception if a property is encountered that's already being evaluated. This prevents stack overflow while providing a clear error to the user.

Q5: How do you handle the offline-to-online transition when both client and server have conflicting changes?

Implement a three-way merge using the last common sync point as the base. When the client reconnects, it sends its version vector to the server. The server computes the diff between the client's version vector and the current state, identifying all changes made on the server while the client was offline. For each modified block, perform a three-way merge: compare the client's version and the server's version against the last known common version. If both modified different parts of the same block (e.g., different paragraphs of a text block), merge automatically. If both modified the same part, flag as a conflict and present both versions to the user for manual resolution.

Q6: Explain how you would scale the real-time collaboration system to support 100,000 concurrent editors on a single page.

Use a hierarchical fan-out architecture. The page's collaboration state is managed by a primary server that processes all operations sequentially. Each operation is validated, applied to the CRDT state, and broadcast. For 100K clients, direct WebSocket broadcast from a single server is infeasible. Instead, use a two-tier broadcast: the primary server sends operations to 100 relay servers (each managing 1,000 connections), and each relay fans out to its connected clients. The relay servers maintain a synchronized CRDT state that is updated by receiving operations from the primary. For presence updates (cursors, selections), use a separate lightweight channel with aggressive throttling (updates only sent when cursor moves more than 5 pixels or 200ms has elapsed).

Q7: How would you implement Notion's "Linked References" feature that shows all pages linking to the current page?

Maintain a reverse index of page links. When a page creates a link to another page (via @mention, page link block, or relation property), write an entry to a link_index table mapping (target_page_id, source_page_id). When a user opens a page, query the link_index for all entries where target_page_id equals the current page. Cache the results in Redis with a 5-minute TTL, invalidated when any page creates or removes a link. For performance at scale, partition the link_index by target_page_id in Cassandra, enabling efficient point queries. The Neo4j graph database provides an alternative path for complex link traversal queries like "find all pages within 3 hops that link to this page."

Q8: How would you ensure data consistency when a user deletes a workspace that has active real-time collaborations?

Implement a graceful shutdown sequence. First, prevent new users from joining the workspace's collaboration sessions. Then, send a workspace_deleted event to all connected clients via their WebSocket connections, prompting them to save locally and disconnect. Wait up to 30 seconds for all clients to acknowledge the disconnection. For any clients that don't disconnect within the timeout, force-close their WebSocket connections. Then execute the workspace deletion: soft-delete all blocks, revoke all permissions, archive file attachments after a 30-day retention period, and purge the workspace's data from all caches and search indexes. The deletion is irreversible after the retention period.

Q9: Design the template instantiation system to handle templates with embedded databases containing complex relations.

Process template instantiation in multiple passes. First pass: clone all page blocks and database blocks, creating a mapping from old IDs to new IDs. Second pass: update all internal references (page links, cross-links, block references) to use the new IDs from the mapping. Third pass: for databases with relation properties, update the relation targets to point to the newly cloned related databases (not the original template databases). Fourth pass: validate all references resolve correctly, logging any broken links. The entire process runs within a database transaction to ensure atomicity. For large templates (1000+ blocks), process in batches with savepoints for partial rollback capability.

Q10: How would you design the system to handle a Notion page being shared as a public website with custom domain?

Use a CDN-first architecture. When a page is published to the web, generate static HTML snapshots and store them in S3 behind CloudFront. Configure CloudFront with a custom domain (CNAME record pointing to CloudFront distribution). When the page is updated, invalidate the CDN cache for that page's path and regenerate the static snapshot. For pages with dynamic content (embedded databases, live updates), serve a JavaScript bundle that hydrates the static HTML and establishes a WebSocket connection for live updates. The public page serving path bypasses the application servers entirely, hitting CloudFront which serves from S3 cache. Cache invalidation uses the CloudFront invalidation API with a 1-second TTL for recently modified pages.