# transitive-bullshit/nextjs-notion-starter-kit architecture

> Architecture diagram of the GitHub repository transitive-bullshit/nextjs-notion-starter-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/transitive-bullshit/nextjs-notion-starter-kit
- Repository: https://github.com/transitive-bullshit/nextjs-notion-starter-kit

## Overview

##### Project type and purpose
- This is a full-stack, content-driven website starter kit built with Next.js (React + TypeScript) that uses Notion as a headless CMS.
- It powers both static and dynamic pages (SSG, SSR, and serverless API routes) and is designed for deployment on Vercel.

##### File structure
- Top-level folders:
- components/ – shared React UI components (ErrorPage, NotionPage, Table of Contents, etc.)
- lib/ – service-layer utilities (Notion API client, image preview generator, sitemap, search, Redis cache, config)
- pages/ – Next.js routes:
◦ pages/[pageId].tsx – dynamic page rendering from Notion
◦ pages/api/ – serverless endpoints (search-notion, social-image)
◦ pages/_app, _document, _error – bootstrapping & error pages
- styles/ – global, Notion, syntax highlighting CSS
- site.config.ts – single config file controlling all site behavior
- .env.example & .github/workflows – deployment & build configurations
- Key config/build files: next.config.js, tsconfig.json, ESLint/Prettier, Vercel GitHub Action.

##### README for additional insights
- Describes architecture choices:
- Next.js + React for rendering
- react-notion-x for Notion content
- Vercel OG image generation for social images
- Optional Redis caching for preview images
- API end-points for search & OG image generation
- Highlights dynamic/static routing, preview images, dark mode, analytics, and environment variables.

##### Main components & relationships
a. Client (Browser/Mobile)
- Requests pages, triggers navigation (Next.js client router)
- Sends search queries (CMD+K) to /api/search-notion
- Fetches social images at /api/social-image?id=...
b. Next.js Application (Vercel Serverless)
- getStaticProps / getServerSideProps: fetch page data via lib/notion.ts + lib/get-canonical-page-id, build HTML/JSON
- React components (components/) render UI, assemble Notion blocks (react-notion-x)
- Serverless API functions in pages/api handle search & dynamic OG image generation
c. Notion API
- Source of truth for page content & metadata
- Accessed via lib/notion-api.ts using Notion SDK
d. Redis Cache (optional)
- Caches generated preview (low-quality placeholder) images to speed up builds
- Accessed via lib/preview-images.ts when isRedisEnabled
e. Vercel Edge / CDN
- Caches static assets (public/, autogenerated sitemap.xml, robots.txt, built pages)
- Edge function for OG image generation
f. External Services
- Fathom / PostHog (optional analytics)
- GitHub Actions for CI/CD (build + optional Redis env secrets)

##### Architectural patterns & design principles
- Separation of concerns: UI components vs. data-fetching libs vs. config
- Hybrid rendering: SSG for most pages, SSR/ISR for dynamic content, serverless API for specialized endpoints
- Single source of configuration (site.config.ts)
- Stateless serverless functions & CDN for scale
- Optional caching layer (Redis) to avoid re-fetching or re-processing heavy assets

##### Detail
- Every major lib in the data flow (preview-images, search-notion, map-page-url)
- Static asset pipeline (styles/, public/, Google Fonts bootstrap)
- Distinguish build-time (SSG, sitemap.xml) vs. runtime (SSR, API calls)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    Browser["Browser / Mobile"]:::frontend

    %% CDN / Edge
    subgraph "Vercel Edge / CDN"
        CDN["CDN Cache (static assets)"]:::edge
        OGEdge["Edge Function: OG Image Generator"]:::edge
    end

    %% Next.js Application
    subgraph "Next.js Application (Vercel Serverless)"
        SSR["Next.js SSR / SSG"]:::backend
        Router["Next.js Client Router"]:::frontend
        API["API Routes (pages/api)"]:::backend
    end

    %% React UI Components
    subgraph "React UI Components" 
        Components["Shared Components"]:::frontend
        NotionPage["NotionPage Component"]:::frontend
        ErrorPage["Error & 404 Pages"]:::frontend
        PageHead["Page Layout & Metadata Components"]:::frontend
        Loading["Loading State Components"]:::frontend
    end

    %% Libs / Service Layer
    subgraph "Libraries (lib/)"
        NotionClient["Notion API Client"]:::external
        DataLayer["Notion Data Layer & Helpers"]:::external
        Canonical["Canonical Page ID Resolver"]:::external
        Preview["Preview Image Generation"]:::external
        SearchLib["Search Integration"]:::external
        Sitemap["Sitemap Generation"]:::external
        URLMap["URL Mapping Helpers"]:::external
        SocialBuilder["Social Image URL Builder"]:::external
        Tweets["Tweets & Embeds Helpers"]:::external
        Config["Site Configuration"]:::external
        Bootstrap["Client Bootstrap & Dark Mode"]:::external
        Types["Type Definitions"]:::external
    end

    %% External Services & Data Sources
    subgraph "External Services"
        NotionAPI["Notion API"]:::external
        Redis["Redis Cache (optional)"]:::external
        Analytics["Fathom / PostHog"]:::external
    end

    %% Deployment & Build
    subgraph "Deployment & Build"
        CI["GitHub Actions"]:::backend
        SiteConfig["site.config.ts"]:::external
        BuildFiles["Build & Config Files"]:::external
    end

    %% Connections
    Browser -->|"Request page"| CDN
    CDN --> SSR
    SSR -->|getStaticProps / getServerSideProps| DataLayer
    DataLayer --> NotionAPI
    SSR --> Components
    Components --> NotionPage
    Components --> ErrorPage
    Components --> PageHead
    Components --> Loading
    SSR --> Preview
    Preview --> Redis
    SSR --> Sitemap
    SSR --> URLMap
    SSR --> SocialBuilder
    SSR --> Tweets
    SSR --> Config
    SSR --> Bootstrap
    SSR --> Types
    Browser -->|"Client-side nav"| Router
    Router -->|"search query"| API
    API -->|"search-notion.ts"| SearchLib
    SearchLib --> NotionAPI
    API -->|"social-image.ts"| OGEdge
    OGEdge --> Preview
    OGEdge --> Config
    SSR -->|"sitemap.xml.tsx & robots.txt.tsx"| BuildFiles
    CI -->|"Deploy"| SSR
    CI --> SiteConfig

    %% Click Events - React UI Components
    click Components "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/tree/main/components/"
    click NotionPage "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/NotionPage.tsx"
    click ErrorPage "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/ErrorPage.tsx"
    click ErrorPage "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/Page404.tsx"
    click PageHead "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/PageHead.tsx"
    click PageHead "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/PageActions.tsx"
    click PageHead "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/PageAside.tsx"
    click PageHead "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/PageSocial.tsx"
    click PageHead "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/Footer.tsx"
    click Loading "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/Loading.tsx"
    click Loading "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/components/LoadingIcon.tsx"

    %% Click Events - Libs
    click NotionClient "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/notion-api.ts"
    click DataLayer "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/notion.ts"
    click DataLayer "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/resolve-notion-page.ts"
    click Canonical "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/get-canonical-page-id.ts"
    click Preview "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/preview-images.ts"
    click SearchLib "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/search-notion.ts"
    click Sitemap "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/get-site-map.ts"
    click URLMap "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/map-page-url.ts"
    click URLMap "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/map-image-url.ts"
    click SocialBuilder "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/get-social-image-url.ts"
    click Tweets "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/get-tweets.ts"
    click Tweets "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/get-page-tweet.ts"
    click Tweets "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/oembed.ts"
    click Config "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/site.config.ts"
    click Config "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/site-config.ts"
    click Config "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/config.ts"
    click Bootstrap "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/bootstrap-client.ts"
    click Bootstrap "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/use-dark-mode.ts"
    click Types "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/types.ts"
    click Types "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/next-env.d.ts"
    click Types "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/lib/reset.d.ts"

    %% Click Events - Next.js Routes
    click SSR "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/[pageId].tsx"
    click SSR "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/index.tsx"
    click SSR "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/feed.tsx"
    click SSR "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/404.tsx"
    click SSR "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/_error.tsx"
    click SSR "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/_app.tsx"
    click SSR "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/_document.tsx"
    click SSR "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/robots.txt.tsx"
    click SSR "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/sitemap.xml.tsx"
    click API "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/api/search-notion.ts"
    click API "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/pages/api/social-image.tsx"

    %% Click Events - Assets & Config
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/next.config.js"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/tsconfig.json"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/.eslintrc.json"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/eslint.config.js"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/.prettierignore"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/.editorconfig"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/.github/workflows/build.yml"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/public/manifest.json"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/styles/global.css"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/styles/notion.css"
    click BuildFiles "https://github.com/transitive-bullshit/nextjs-notion-starter-kit/blob/main/styles/prism-theme.css"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#D6F5D6,stroke:#28A745,color:#216E20;
    classDef external fill:#FFE4B5,stroke:#FF8C00,color:#A35400;
    classDef edge fill:#E8E8E8,stroke:#6C757D,color:#343A40;
```
