# makenotion/notion-cookbook architecture

> Architecture diagram of the GitHub repository makenotion/notion-cookbook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/makenotion/notion-cookbook
- Repository: https://github.com/makenotion/notion-cookbook

## Overview

#### Purpose and Repository Shape
Notion Cookbook is a collection of independent, runnable TypeScript/Node.js recipes for the Notion API and Notion Workers. It is not one deployable application: each example, Worker, or agent skill is a separately configured project. The root discovery and operating surfaces are `README.md`, `catalog.json`, and `AGENTS.md`.

#### Recipe Catalog and Selection Boundary
`catalog.json` is the machine-readable directory of runnable projects and supported commands; it is the intended entry point for coding agents. `AGENTS.md` defines the workflow for locating, adapting, and validating a selected recipe. Root scripts operate across projects rather than providing a shared runtime: `scripts/install-projects.sh`, `scripts/typecheck-projects.sh`, and `scripts/test-projects.sh`.

#### Local Notion API Examples
Self-contained Node.js examples demonstrate direct use of the official Notion JavaScript SDK, with per-project dependencies, TypeScript configuration, environment variables, and README-driven commands. Entrypoints are generally project-local scripts such as `examples/database-email-update/index.ts` and `examples/notion-github-sync/index.ts`. The browser/server exception is the Express form app, split between `examples/web-form-with-express/server.ts` and static/UI assets under `examples/web-form-with-express/public`.

#### Notion Worker Runtime
Worker projects are server-side extensions intended for deployment with the Notion Workers CLI (`ntn`) and attachment to Notion Agent connections. Each Worker is independently packaged, with its execution entrypoint conventionally in `src/index.ts`, for example `workers/airflow/src/index.ts`, `workers/duckdb-query/src/index.ts`, and `workers/chart-generator/src/index.ts`. The Worker boundary separates Notion’s invocation/deployment contract from service-specific adapters and workflow logic.

#### Sync Workers: External Source to Managed Notion Data
Sync Workers ingest external provider data, map it into managed Notion databases, and often preserve incremental state. Provider clients and resource modules isolate remote APIs from synchronization orchestration: `workers/github-sync/src/index.ts`, `workers/github-sync/src/github.ts`, `workers/github-sync/src/issues.ts`; `workers/linear-sync/src/index.ts`, `workers/linear-sync/src/linear.ts`, `workers/linear-sync/src/sync-state.ts`; and `workers/snowflake-sync/src/index.ts`, `workers/snowflake-sync/src/transform.ts`, `workers/snowflake-sync/src/schema.ts`. Supported boundaries include GitHub, CRM/support/task systems, warehouse databases, and Notion.

#### Agent Tools and Query/Action Flows
Tool Workers expose repeatable agent-callable operations rather than persistent synchronization. Common structure is entrypoint → authentication/configuration → provider client → domain operation. Examples include read-only database querying in `workers/postgres-query/src/index.ts`, `workers/postgres-query/src/postgres.ts`, `workers/postgres-query/src/sql.ts`; cross-service incident workflows in `workers/sentry-pagerduty-incident-tools/src/index.ts`, `workers/sentry-pagerduty-incident-tools/src/sentry.ts`, `workers/sentry-pagerduty-incident-tools/src/pagerduty.ts`; and deployment actions in `workers/vercel-production-deployment-tools/src/index.ts`, `workers/vercel-production-deployment-tools/src/release.ts`.

#### Event and UI Extension Paths
The webhook pattern accepts external events, verifies/parses them, then writes/upserts Notion records: `workers/zendesk-webhook/src/index.ts`, `workers/zendesk-webhook/src/webhook.ts`, `workers/zendesk-webhook/src/notion.ts`. Custom Blocks are a distinct full-stack extension shape: Worker backend entrypoints under `workers/custom-blocks/habit-tracker/src/index.ts` support Vite/React block clients such as `workers/custom-blocks/habit-tracker/blocks/habit-tracker/src/App.tsx` and Notion-backed client state in `workers/custom-blocks/habit-tracker/blocks/habit-tracker/src/notionStore.ts`.

#### Agent Skills and Documentation Assets
`skills/claude` provides instruction-centric capabilities—knowledge capture, meeting intelligence, research documentation, and specification-to-implementation—rather than executable services. Each skill centers on a `SKILL.md` contract with references, examples, and evaluation fixtures, e.g. `skills/claude/knowledge-capture/SKILL.md`, `skills/claude/meeting-intelligence/SKILL.md`, and `skills/claude/spec-to-implementation/SKILL.md`. Shared user-facing guidance is kept in `docs/` and project-local READMEs.

Main entry points: [`catalog.json`](https://github.com/makenotion/notion-cookbook/blob/main/catalog.json) (Recipe Catalog), [`workers/airflow/src/index.ts`](https://github.com/makenotion/notion-cookbook/blob/main/workers/airflow/src/index.ts) (Notion Worker Runtime), [`workers/github-sync/src/index.ts`](https://github.com/makenotion/notion-cookbook/blob/main/workers/github-sync/src/index.ts) (Sync Worker Orchestration), [`AGENTS.md`](https://github.com/makenotion/notion-cookbook/blob/main/AGENTS.md) (Agent Workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery & Operations"]
  node_readme["Repository README<br/>documentation<br/>[README.md]"]
  node_catalog["Recipe Catalog<br/>project directory<br/>[catalog.json]"]
  node_agents["Agent Workflow<br/>agent guidance<br/>[AGENTS.md]"]
  node_root_scripts["Cross-project Scripts<br/>operations scripts"]
end

subgraph group_examples["Local API Examples"]
  node_node_examples["Direct SDK Recipes<br/>Node.js examples<br/>[index.ts]"]
  node_github_example["GitHub Sync Recipe<br/>Node.js example<br/>[index.ts]"]
  node_express_app["Express Form Server<br/>web server recipe<br/>[server.ts]"]
  node_express_ui["Form UI Assets<br/>static UI"]
end

subgraph group_workers["Notion Workers"]
  node_worker_runtime{{"Notion Worker Runtime<br/>deployment boundary<br/>[index.ts]"}}
  node_sync_orchestrator["Sync Worker Orchestration<br/>sync workflow<br/>[index.ts]"]
  node_github_provider["GitHub Provider Adapter<br/>provider client<br/>[github.ts]"]
  node_sync_state["Incremental Sync State<br/>state management<br/>[sync-state.ts]"]
  node_warehouse_transform["Warehouse Transform &amp; Schema<br/>data mapping<br/>[transform.ts]"]
  node_tool_worker["Agent Tool Worker<br/>agent-callable tools<br/>[index.ts]"]
  node_incident_adapters["Incident Service Adapters<br/>provider clients<br/>[sentry.ts]"]
  node_webhook_worker["Zendesk Webhook Worker<br/>event ingestion<br/>[index.ts]"]
  node_custom_block_backend["Habit Tracker Backend<br/>custom block worker<br/>[index.ts]"]
  node_custom_block_client["Habit Tracker Block Client<br/>Vite/React client<br/>[App.tsx]"]
end

subgraph group_skills["Agent Skills &amp; Docs"]
  node_skill_contracts["Claude Skill Contracts<br/>instruction skills<br/>[SKILL.md]"]
  node_docs["Guidance &amp; Project Docs<br/>documentation"]
end

node_readme -->|"discovers"| node_catalog
node_catalog -->|"selects via"| node_agents
node_agents -->|"validates with"| node_root_scripts
node_catalog -->|"indexes"| node_node_examples
node_catalog -->|"indexes"| node_worker_runtime
node_catalog -.->|"indexes"| node_skill_contracts
node_express_app -->|"serves"| node_express_ui
node_worker_runtime -->|"hosts"| node_sync_orchestrator
node_sync_orchestrator -->|"reads provider data"| node_github_provider
node_sync_orchestrator -->|"preserves progress"| node_sync_state
node_sync_orchestrator -->|"maps source data"| node_warehouse_transform
node_worker_runtime -->|"hosts"| node_tool_worker
node_tool_worker -->|"invokes"| node_incident_adapters
node_worker_runtime -->|"hosts"| node_webhook_worker
node_worker_runtime -->|"hosts"| node_custom_block_backend
node_custom_block_client -->|"calls"| node_custom_block_backend
node_skill_contracts -.->|"uses guidance"| node_docs

click node_readme "https://github.com/makenotion/notion-cookbook/blob/main/README.md"
click node_catalog "https://github.com/makenotion/notion-cookbook/blob/main/catalog.json"
click node_agents "https://github.com/makenotion/notion-cookbook/blob/main/AGENTS.md"
click node_root_scripts "https://github.com/makenotion/notion-cookbook/blob/main/scripts/install-projects.sh"
click node_node_examples "https://github.com/makenotion/notion-cookbook/blob/main/examples/database-email-update/index.ts"
click node_github_example "https://github.com/makenotion/notion-cookbook/blob/main/examples/notion-github-sync/index.ts"
click node_express_app "https://github.com/makenotion/notion-cookbook/blob/main/examples/web-form-with-express/server.ts"
click node_express_ui "https://github.com/makenotion/notion-cookbook/tree/main/examples/web-form-with-express/public"
click node_worker_runtime "https://github.com/makenotion/notion-cookbook/blob/main/workers/airflow/src/index.ts"
click node_sync_orchestrator "https://github.com/makenotion/notion-cookbook/blob/main/workers/github-sync/src/index.ts"
click node_github_provider "https://github.com/makenotion/notion-cookbook/blob/main/workers/github-sync/src/github.ts"
click node_sync_state "https://github.com/makenotion/notion-cookbook/blob/main/workers/linear-sync/src/sync-state.ts"
click node_warehouse_transform "https://github.com/makenotion/notion-cookbook/blob/main/workers/snowflake-sync/src/transform.ts"
click node_tool_worker "https://github.com/makenotion/notion-cookbook/blob/main/workers/postgres-query/src/index.ts"
click node_incident_adapters "https://github.com/makenotion/notion-cookbook/blob/main/workers/sentry-pagerduty-incident-tools/src/sentry.ts"
click node_webhook_worker "https://github.com/makenotion/notion-cookbook/blob/main/workers/zendesk-webhook/src/index.ts"
click node_custom_block_backend "https://github.com/makenotion/notion-cookbook/blob/main/workers/custom-blocks/habit-tracker/src/index.ts"
click node_custom_block_client "https://github.com/makenotion/notion-cookbook/blob/main/workers/custom-blocks/habit-tracker/blocks/habit-tracker/src/App.tsx"
click node_skill_contracts "https://github.com/makenotion/notion-cookbook/blob/main/skills/claude/knowledge-capture/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_catalog,node_agents,node_root_scripts toneBlue
class node_node_examples,node_github_example,node_express_app,node_express_ui toneAmber
class node_worker_runtime,node_sync_orchestrator,node_github_provider,node_sync_state,node_warehouse_transform,node_tool_worker,node_incident_adapters,node_webhook_worker,node_custom_block_backend,node_custom_block_client toneMint
class node_skill_contracts,node_docs toneRose
```

## Components

### Discovery & Operations

- [Repository README](https://github.com/makenotion/notion-cookbook/blob/main/README.md): documentation · Human discovery surface. · `README.md`
- [Recipe Catalog](https://github.com/makenotion/notion-cookbook/blob/main/catalog.json): project directory · Machine-readable runnable project and command directory. · `catalog.json`
- [Agent Workflow](https://github.com/makenotion/notion-cookbook/blob/main/AGENTS.md): agent guidance · Selection, adaptation, and validation workflow. · `AGENTS.md`
- [Cross-project Scripts](https://github.com/makenotion/notion-cookbook/blob/main/scripts/install-projects.sh): operations scripts · Install, typecheck, and test selected projects. · `scripts/install-projects.sh`

### Local API Examples

- [Direct SDK Recipes](https://github.com/makenotion/notion-cookbook/blob/main/examples/database-email-update/index.ts): Node.js examples · Independently configured local Notion API projects. · `examples/database-email-update/index.ts`
- [GitHub Sync Recipe](https://github.com/makenotion/notion-cookbook/blob/main/examples/notion-github-sync/index.ts): Node.js example · `examples/notion-github-sync/index.ts`
- [Express Form Server](https://github.com/makenotion/notion-cookbook/blob/main/examples/web-form-with-express/server.ts): web server recipe · Browser/server exception among local examples. · `examples/web-form-with-express/server.ts`
- [Form UI Assets](https://github.com/makenotion/notion-cookbook/tree/main/examples/web-form-with-express/public): static UI · `examples/web-form-with-express/public`

### Notion Workers

- [Notion Worker Runtime](https://github.com/makenotion/notion-cookbook/blob/main/workers/airflow/src/index.ts): deployment boundary · Workers deploy with ntn and attach to Notion Agent connections. · `workers/airflow/src/index.ts`
- [Sync Worker Orchestration](https://github.com/makenotion/notion-cookbook/blob/main/workers/github-sync/src/index.ts): sync workflow · Maps external data into managed Notion databases. · `workers/github-sync/src/index.ts`
- [GitHub Provider Adapter](https://github.com/makenotion/notion-cookbook/blob/main/workers/github-sync/src/github.ts): provider client · `workers/github-sync/src/github.ts`
- [Incremental Sync State](https://github.com/makenotion/notion-cookbook/blob/main/workers/linear-sync/src/sync-state.ts): state management · `workers/linear-sync/src/sync-state.ts`
- [Warehouse Transform & Schema](https://github.com/makenotion/notion-cookbook/blob/main/workers/snowflake-sync/src/transform.ts): data mapping · `workers/snowflake-sync/src/transform.ts`
- [Agent Tool Worker](https://github.com/makenotion/notion-cookbook/blob/main/workers/postgres-query/src/index.ts): agent-callable tools · Authentication, provider access, and domain operations. · `workers/postgres-query/src/index.ts`
- [Incident Service Adapters](https://github.com/makenotion/notion-cookbook/blob/main/workers/sentry-pagerduty-incident-tools/src/sentry.ts): provider clients · Cross-service Sentry and PagerDuty operations. · `workers/sentry-pagerduty-incident-tools/src/sentry.ts`
- [Zendesk Webhook Worker](https://github.com/makenotion/notion-cookbook/blob/main/workers/zendesk-webhook/src/index.ts): event ingestion · Verifies external events and upserts Notion records. · `workers/zendesk-webhook/src/index.ts`
- [Habit Tracker Backend](https://github.com/makenotion/notion-cookbook/blob/main/workers/custom-blocks/habit-tracker/src/index.ts): custom block worker · `workers/custom-blocks/habit-tracker/src/index.ts`
- [Habit Tracker Block Client](https://github.com/makenotion/notion-cookbook/blob/main/workers/custom-blocks/habit-tracker/blocks/habit-tracker/src/App.tsx): Vite/React client · Uses Notion-backed client state. · `workers/custom-blocks/habit-tracker/blocks/habit-tracker/src/App.tsx`

### Agent Skills & Docs

- [Claude Skill Contracts](https://github.com/makenotion/notion-cookbook/blob/main/skills/claude/knowledge-capture/SKILL.md): instruction skills · Knowledge, meeting, research, and implementation capabilities. · `skills/claude/knowledge-capture/SKILL.md`
- **Guidance & Project Docs**: documentation

## Connections

- Repository README → Recipe Catalog: discovers
- Recipe Catalog → Agent Workflow: selects via
- Agent Workflow → Cross-project Scripts: validates with
- Recipe Catalog → Direct SDK Recipes: indexes
- Recipe Catalog → Notion Worker Runtime: indexes
- Recipe Catalog → Claude Skill Contracts: indexes
- Express Form Server → Form UI Assets: serves
- Notion Worker Runtime → Sync Worker Orchestration: hosts
- Sync Worker Orchestration → GitHub Provider Adapter: reads provider data
- Sync Worker Orchestration → Incremental Sync State: preserves progress
- Sync Worker Orchestration → Warehouse Transform & Schema: maps source data
- Notion Worker Runtime → Agent Tool Worker: hosts
- Agent Tool Worker → Incident Service Adapters: invokes
- Notion Worker Runtime → Zendesk Webhook Worker: hosts
- Notion Worker Runtime → Habit Tracker Backend: hosts
- Habit Tracker Block Client → Habit Tracker Backend: calls
- Claude Skill Contracts → Guidance & Project Docs: uses guidance