notion-architecture-variants

What this skill does

# Notion Architecture Variants

## Overview

Five validated architecture patterns for using Notion as a backend via the API. Each variant shows a specific use case with real `Client` from `@notionhq/client` code: headless CMS for blogs, project management task tracker, wiki-style knowledge base, form submission handler, and data pipeline source for analytics. Includes database schema design, API integration code, and deployment considerations.

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

## Instructions

### Step 1: Headless CMS (Blog / Content Site)

Use Notion as a content management system — authors write in Notion, your site fetches and renders content via the API.

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

const notion = new Client({ auth: process.env.NOTION_TOKEN });
const CONTENT_DB = process.env.NOTION_CONTENT_DB!;

// Database schema in Notion:
// Title (title), Slug (rich_text), Status (select: Draft/Review/Published),
// Published Date (date), Author (people), Tags (multi_select),
// Excerpt (rich_text), Cover Image (files)

interface BlogPost {
  id: string;
  title: string;
  slug: string;
  status: string;
  publishedDate: string | null;
  author: string;
  tags: string[];
  excerpt: string;
}

// Fetch published posts for the blog index
async function getPublishedPosts(): Promise<BlogPost[]> {
  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,
  });

  return response.results
    .filter((p): p is any => 'properties' in p)
    .map(page => ({
      id: page.id,
      title: page.properties['Title']?.title?.[0]?.plain_text ?? 'Untitled',
      slug: page.properties['Slug']?.rich_text?.[0]?.plain_text ?? page.id,
      status: page.properties['Status']?.select?.name ?? 'Draft',
      publishedDate: page.properties['Published Date']?.date?.start ?? null,
      author: page.properties['Author']?.people?.[0]?.name ?? 'Unknown',
      tags: page.properties['Tags']?.multi_select?.map((t: any) => t.name) ?? [],
      excerpt: page.properties['Excerpt']?.rich_text?.[0]?.plain_text ?? '',
    }));
}

// Fetch full page content as blocks (for rendering)
async function getPostContent(pageId: string): Promise<any[]> {
  const blocks: any[] = [];
  let cursor: string | undefined;

  do {
    const response = await notion.blocks.children.list({
      block_id: pageId,
      page_size: 100,
      start_cursor: cursor,
    });

    blocks.push(...response.results);
    cursor = response.has_more ? (response.next_cursor ?? undefined) : undefined;
  } while (cursor);

  return blocks;
}

// Render blocks to HTML (simplified)
function blockToHtml(block: any): string {
  const type = block.type;
  switch (type) {
    case 'paragraph':
      const text = block.paragraph.rich_text.map((t: any) => t.plain_text).join('');
      return text ? `<p>${text}</p>` : '';
    case 'heading_1':
      return `<h1>${block.heading_1.rich_text.map((t: any) => t.plain_text).join('')}</h1>`;
    case 'heading_2':
      return `<h2>${block.heading_2.rich_text.map((t: any) => t.plain_text).join('')}</h2>`;
    case 'heading_3':
      return `<h3>${block.heading_3.rich_text.map((t: any) => t.plain_text).join('')}</h3>`;
    case 'bulleted_list_item':
      return `<li>${block.bulleted_list_item.rich_text.map((t: any) => t.plain_text).join('')}</li>`;
    case 'code':
      return `<pre><code class="${block.code.language}">${block.code.rich_text.map((t: any) => t.plain_text).join('')}</code></pre>`;
    case 'image':
      const url = block.image.type === 'external' ? block.image.external.url : block.image.file.url;
      return `<img src="${url}" alt="" />`;
    default:
      return `<!-- unsupported block type: ${type} -->`;
  }
}
```

### Step 2: Task Tracker (Project Management)

Use Notion as a project management backend — read/write tasks, update statuses, assign team members.

```typescript
const TASKS_DB = process.env.NOTION_TASKS_DB!;

// Database schema:
// Name (title), Status (select: Backlog/Todo/In Progress/Done),
// Priority (select: P0/P1/P2/P3), Assignee (people),
// Due Date (date), Sprint (select), Labels (multi_select),
// Story Points (number)

interface Task {
  id: string;
  name: string;
  status: string;
  priority: string;
  assignee: string | null;
  dueDate: string | null;
  labels: string[];
}

// Get sprint board view
async function getSprintTasks(sprint: string): Promise<Record<string, Task[]>> {
  const response = await notion.databases.query({
    database_id: TASKS_DB,
    filter: {
      and: [
        { property: 'Sprint', select: { equals: sprint } },
        { property: 'Status', select: { does_not_equal: 'Archived' } },
      ],
    },
    sorts: [{ property: 'Priority', direction: 'ascending' }],
  });

  const tasks = response.results
    .filter((p): p is any => 'properties' in p)
    .map(page => ({
      id: page.id,
      name: page.properties['Name']?.title?.[0]?.plain_text ?? 'Untitled',
      status: page.properties['Status']?.select?.name ?? 'Backlog',
      priority: page.properties['Priority']?.select?.name ?? 'P3',
      assignee: page.properties['Assignee']?.people?.[0]?.name ?? null,
      dueDate: page.properties['Due Date']?.date?.start ?? null,
      labels: page.properties['Labels']?.multi_select?.map((l: any) => l.name) ?? [],
    }));

  // Group by status for board view
  return tasks.reduce((board, task) => {
    (board[task.status] ??= []).push(task);
    return board;
  }, {} as Record<string, Task[]>);
}

// Move task between columns
async function updateTaskStatus(taskId: string, newStatus: string): Promise<void> {
  await notion.pages.update({
    page_id: taskId,
    properties: {
      Status: { select: { name: newStatus } },
    },
  });
}

// Create task from external source (Slack, email, API)
async function createTask(input: {
  name: string;
  priority?: string;
  assigneeId?: string;
  dueDate?: string;
  labels?: string[];
}): Promise<string> {
  const properties: any = {
    Name: { title: [{ text: { content: input.name } }] },
    Status: { select: { name: 'Backlog' } },
  };

  if (input.priority) properties.Priority = { select: { name: input.priority } };
  if (input.assigneeId) properties.Assignee = { people: [{ id: input.assigneeId }] };
  if (input.dueDate) properties['Due Date'] = { date: { start: input.dueDate } };
  if (input.labels) properties.Labels = { multi_select: input.labels.map(name => ({ name })) };

  const page = await notion.pages.create({
    parent: { database_id: TASKS_DB },
    properties,
  });

  return page.id;
}
```

### Step 3: Knowledge Base (Wiki), Form Handler, and Data Pipeline

Three additional patterns for common Notion use cases.

```typescript
// === KNOWLEDGE BASE (WIKI) ===
const WIKI_DB = process.env.NOTION_WIKI_DB!;

// Database schema:
// Title (title), Category (select), Tags (multi_select),
// Last Updated (last_edited_time), Author (created_by)

// Full-text search across wiki articles
async function searchWiki(query: string): Promise<any[]> {
  // Notion's search endpoint searches across all shared content
  const response = await notion.search({
    query,
    filter: { value: 'page', property: 'object' },
    sort: { direction: 'descending', timestamp: 'last_edited_time' },
    page_size: 20,
  });

  return response.results
    .filter((r: any) => r.parent?.database_id === WIKI_DB)
    .map((page: any) => ({
      id: page.id,
      title: page.properties?.['Title']?.title?.[0]?.plain_text ?? 'Untitled',
      lastEdited: page.last_edited_time,
      url: page.url,
    }));
}

// Build table of contents from page blocks
async f