Notion Architecture Variants Skill

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:

| Variant | Use case | Core operation | | --------- | ---------- | ---------------- | | Headless CMS | Blog / content site | Query Status = Published, render blocks to HTML | | Task Tracker | Project management | Group by status for a board, pages.update on move | | Knowledge Base | Wiki / internal docs | Workspace search filtered to the wiki database | | Form Handler | Contact / lead capture | One pages.create per submission | | Data Pipeline | Analytics / ETL source | Paginate on a last_edited_time watermark |

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 object_not_found even with a valid token. Never hard-code the token; read it from the environment.

Instructions

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.
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.
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.
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.
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

| Issue | Cause | Solution | | ------- | ------- | ---------- | | Empty rich_text array | Property has no content | Always check ?.[0]?.plain_text ?? '' | | object_not_found on query | Database not shared with integration | Share database in Notion UI | | Image URLs expire | Notion-hosted files have temporary URLs | Cache or proxy images | | Search returns unrelated pages | search is workspace-wide | Filter by parent.database_id | | Form message too long | rich_text max 2000 chars | Truncate with .substring(0, 2000) | | Pipeline duplicates | Re-processing same records | Track last_edited_time watermark |

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.

Agent Skills: Notion Architecture Variants

Install this agent skill to your local

Skill Files