Notion Architecture Variants

Overview

Five validated architecture patterns for using Notion as a backend via the API, each with database schema design, integration code, and deployment tradeoffs. The full copy-ready code for every variant lives in references/implementation.md; this page gives the decision framework, the shared skeleton, and one worked example so you can pick the right pattern and drill into depth on demand.

The five variants:

Prerequisites

• @notionhq/client v2.x installed (npm install @notionhq/client)
• Python: notion-client installed (pip install notion-client)
• NOTION_TOKEN environment variable set
• Notion databases created and shared with your integration

Authentication

All variants authenticate the same way: an internal integration token in the

NOTION_TOKEN environment variable, passed as auth when constructing the

client (new Client({ auth: process.env.NOTION_TOKEN }) / Client(auth=...)).

Create the integration at notion.so/my-integrations, then **share each database

with the integration** from its Notion page — an unshared database returns

objectnotfound even with a valid token. Never hard-code the token; read it

from the environment.

Instructions

1. Pick the variant that matches your workload using the decision helper in

references/examples.md — content authoring vs.

real-time status vs. high read volume each point to a different pattern.

1. Model the database schema in Notion for that variant (property names and

types are documented inline with each variant's code). Share the database

with your integration.

1. Read any existing integration module, then Write the client setup:

construct one Client with auth: process.env.NOTION_TOKEN and reference

each database by its own NOTION*DB env var.

1. Implement the variant's operations from

references/implementation.md — copy the

TypeScript (or Python equivalent) for CMS fetch/render, task board grouping,

wiki search, form intake, or pipeline extraction.

1. Handle the edge cases in the table below (empty rich_text, unshared

databases, expiring image URLs, rate limits) before shipping.

The shared client skeleton every variant builds on:

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });
const CONTENT_DB = process.env.NOTION_CONTENT_DB!; // one env var per database

// Query published rows (CMS index example — full code in references/implementation.md)
const response = await notion.databases.query({
  database_id: CONTENT_DB,
  filter: { property: 'Status', select: { equals: 'Published' } },
  sorts: [{ property: 'Published Date', direction: 'descending' }],
  page_size: 100,
});

See references/implementation.md for the complete

implementation of all five variants (TypeScript + Python).

Output

• Headless CMS with post fetching, block rendering, and slug routing
• Task tracker with sprint board view, status updates, and task creation
• Knowledge base with full-text search and table of contents generation
• Form submission handler with validation and status tracking
• Data pipeline extractor with property flattening for analytics

Error Handling

Examples

Pick a variant with the recommendArchitecture decision helper, which maps

author type, update frequency, and read volume onto the right pattern (CMS vs.

task tracker vs. data pipeline). The full helper plus an at-a-glance selection

table are in references/examples.md.

recommendArchitecture({ contentAuthors: 'non-technical', updateFrequency: 'daily', readVolume: 'low' });
// → "CMS: Non-technical authors + infrequent updates = perfect Notion CMS fit"

Resources

• references/implementation.md — full code for all five variants (TypeScript + Python)
• references/examples.md — architecture decision helper + selection table
• Notion API Introduction
• Notion Database Properties
• Notion Block Types
• Notion Search

Next Steps

For common mistakes across all architectures, see notion-known-pitfalls.

For scaling any architecture, see notion-load-scale.