notion-reference-architecture

name	notion-reference-architecture
description	Design and implement a production-ready Notion integration architecture with proper layering, caching, error handling, and testing strategies. Use when designing a new Notion integration, reviewing existing project structure, establishing architecture standards for a Notion application, or migrating from ad-hoc API calls to a layered architecture. Trigger with "notion architecture", "notion project structure", "notion reference architecture", "notion integration design", "notion layered architecture", or "notion service pattern".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(npx:*)
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion","architecture"]
compatibility	Designed for Claude Code

Notion Reference Architecture

Overview

Production-grade architecture for Notion integrations using @notionhq/client. This skill defines a four-layer architecture — client singleton, repository pattern, service layer, and caching — that scales from simple scripts to enterprise applications, with multi-integration setups, event-driven processing, and testing strategies.

Notion API version: 2022-06-28 | Rate limit: 3 requests/second per integration | Max page size: 100

Prerequisites

• Node.js 18+ with TypeScript strict mode enabled
• @notionhq/client v2.x installed (npm install @notionhq/client)
• A Notion internal integration created at https://www.notion.so/my-integrations
• NOTION_TOKEN environment variable set with the integration token
• Target databases/pages shared with the integration via "Add connections"

Instructions

Build the architecture in four layers, bottom-up. Each layer depends only on the ones below it, so wire them in order. The full copy-ready code for every layer lives in the implementation reference — scaffold the project layout first, then follow the steps below.

Step 1: Client singleton with retry and rate limiting

Wrap @notionhq/client in a singleton with explicit rate limiting (Notion caps at 3 req/s per integration) and exponential-backoff retry. Expose separate reader and writer clients so a read-heavy and a write-scoped integration can run side by side and double effective throughput.

// src/notion/client.ts — skeleton (full code in the implementation reference)
export function getReaderClient(): Client { /* singleton, NOTION_READER_TOKEN ?? NOTION_TOKEN */ }
export function getWriterClient(): Client { /* singleton, NOTION_WRITER_TOKEN ?? NOTION_TOKEN */ }
export async  rateLimitedCall<T>(:  <T>): <T> {  }
   withRetry<T>(:  <T>, maxRetries = ): <T> {  }