notion-reference-architecture

# 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. It covers multi-integration setups (reader + writer tokens), event-driven processing, headless CMS patterns, and comprehensive 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 ### Step 1: Establish the Client Singleton with Retry and Rate Limiting The client layer wraps `@notionhq/client` in a singleton pattern with built-in retry logic. Notion's SDK handles basic retries, but you need explicit rate limiting and configurable timeouts for production use. ``` my-notion-app/ ├── src/ │ ├── notion/ │ │ ├── client.ts # Singleton + retry + rate limiter │ │ ├── types.ts # Domain types mapped from Notion properties │ │ ├── extractors.ts # Type-safe property extraction helpers │ │ └── e...