# tangly1024/notionnext architecture

> Architecture diagram of the GitHub repository tangly1024/notionnext, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tangly1024/notionnext
- Repository: https://github.com/tangly1024/notionnext

## Overview

##### Project type and purpose
- This is a full-stack, static-rendered blog system built with Next.js that sources content from Notion via the Notion API.
- It runs on Vercel, uses serverless API routes for dynamic features (authentication, subscriptions, caching), and pre-renders pages (SSG/ISR).

##### Key architectural components
a. Client (Browser)
- Renders React pages, requests static assets (HTML/CSS/JS) from the CDN.
- Interacts with dynamic endpoints (search, subscribe, auth callbacks).
- Loads comment widgets and analytics scripts (Twikoo, Giscus, Google Analytics, etc.).
b. CDN / Static Hosting (Vercel Edge)
- Delivers pre-rendered pages, public assets (images, CSS, JS).
- Caches static HTML and pages (ISR).
c. Next.js Application
- Pages folder: UI routes (/, /category, /tag, /dashboard, etc.) with getStaticProps/Paths.
- API routes under pages/api:
– /auth (OAuth callback to Notion for sign-in)
– /cache (warm or purge caches)
– /subscribe, /user (user-related operations)
- Middleware: global request handling, redirects.
d. Content Source (Notion API)
- External service providing page blocks, metadata, categories, tags.
- Custom wrapper in lib/notion to fetch and transform data.
e. Caching Layer
- In-memory (lib/cache/memory_cache.js)
- Local file (lib/cache/local_file_cache.js) for SSG builds
- Redis (lib/cache/redis_cache.js) for shared or production caches
- Cache manager to orchestrate multi-tier cache.
f. Plugins & Utilities
- Conf directory: site configuration, theme selection, plugin toggles.
- lib/plugins: markdown enhancements (math via mhchem, word count), search indexing (Algolia).
- lib/utils: date formatting, slug generation, sitemap/rss.
g. Themes & UI Components
- Large library of independent React components (components/) for BI, animations, comment systems, etc.
- The “themes” folder: pre-built themes (next, medium, hexo…) exporting theme config, styles, and overrides.

##### External Services & Integrations
- Notion API (primary data store)
- GitHub Actions & Docker (CI/CD pipelines, image builds)
- Vercel (deployment & edge functions)
- Analytics (Ackee, Busuanzi, Gtag)
- Comment systems (Twikoo, Giscus, Gitalk, Utterances)
- Search (Algolia)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Frontend
    subgraph "User Facing" 
        Browser["Browser (React UI)"]:::frontend
    end
    subgraph "CDN / Static Hosting (Vercel Edge)" 
        CDN["Edge CDN (HTML/CSS/JS)"]:::frontend
        PublicAssets["Public Assets"]:::frontend
    end

    %% Next.js Build and Runtime
    subgraph "Next.js Build Time (SSG)" 
        PageRoutes["Page Routes\ngetStaticProps/Paths"]:::backend
        NotionWrapper["Notion API Wrapper"]:::backend
        CacheManager["Cache Manager"]:::cache
        MemCache["In-Memory Cache"]:::cache
        FileCache["Local File Cache"]:::cache
        RedisCache["Redis Cache"]:::cache
        Plugins["Plugins"]:::backend
        Utils["Utilities"]:::backend
        Conf["Site & Plugin Config"]:::backend
        GlobalConfig["Global Configs"]:::backend
    end

    subgraph "Next.js Runtime (ISR / API)" 
        APIRoutes["API Routes"]:::backend
        OAuthCallback["OAuth Callback"]:::backend
        CacheAPI["Cache Endpoint"]:::backend
        SubscribeAPI["Subscribe Endpoint"]:::backend
        UserAPI["User Endpoint"]:::backend
        Middleware["Global Middleware"]:::backend
    end

    %% Data Plane
    subgraph "Data Plane" 
        NotionAPI["Notion REST API"]:::external
        RedisCacheDb["Redis"]:::cache
        Algolia["Algolia Search"]:::external
        Comments["Comment Systems"]:::external
        Analytics["Analytics"]:::external
    end

    %% CI/CD
    subgraph "CI/CD & Deployment"
        GitHubActions["GitHub Actions"]:::external
        Docker["Docker Build"]:::external
        Vercel["Vercel Deployment"]:::external
    end

    %% Styles & Themes
    subgraph "UI & Theming"
        Components["React Components"]:::frontend
        Themes["Themes"]:::frontend
        ThemeLoader["Default Theme Loader"]:::frontend
        Styles["Global Styles"]:::frontend
        TailwindConfig["Tailwind Config"]:::frontend
    end

    %% Connections
    Browser -->|HTTPS Fetch| CDN
    Browser -->|Dynamic Fetch| APIRoutes
    Browser -->|Loads Scripts| Analytics
    Browser -->|Loads Widgets| Comments
    CDN -->|Serves| Browser
    CDN -->|Caches| PageRoutes

    PageRoutes -->|Fetch Data| CacheManager
    CacheManager --> MemCache
    CacheManager --> FileCache
    CacheManager --> RedisCache
    CacheManager -->|Fallback| NotionAPI
    NotionWrapper -->|Calls| NotionAPI
    Plugins --> Utils
    Conf --> Plugins
    GlobalConfig --> PageRoutes
    GlobalConfig --> APIRoutes

    APIRoutes --> OAuthCallback
    APIRoutes --> CacheAPI
    APIRoutes --> SubscribeAPI
    APIRoutes --> UserAPI
    APIRoutes -->|Uses| Middleware

    OAuthCallback -->|Fetch| NotionAPI
    CacheAPI -->|Manage| CacheManager
    SubscribeAPI -->|Store| NotionAPI
    UserAPI -->|Manage| NotionAPI

    RedisCacheDb --> RedisCache
    Algolia --> Plugins
    Comments --> Plugins
    Analytics --> Plugins

    GitHubActions --> Docker
    Docker --> Vercel
    Vercel --> CDN
    Vercel --> APIRoutes

    Components --> Browser
    ThemeLoader --> PageRoutes
    Themes --> ThemeLoader
    Styles --> Browser
    TailwindConfig --> Styles

    %% Click Events
    click PageRoutes "https://github.com/tangly1024/notionnext/tree/main/pages/"
    click APIRoutes "https://github.com/tangly1024/notionnext/tree/main/pages/api/"
    click OAuthCallback "https://github.com/tangly1024/notionnext/blob/main/pages/api/auth/callback/notion.ts"
    click CacheAPI "https://github.com/tangly1024/notionnext/blob/main/pages/api/cache.js"
    click SubscribeAPI "https://github.com/tangly1024/notionnext/blob/main/pages/api/subscribe.js"
    click UserAPI "https://github.com/tangly1024/notionnext/blob/main/pages/api/user.ts"
    click Middleware "https://github.com/tangly1024/notionnext/blob/main/middleware.ts"
    click NotionWrapper "https://github.com/tangly1024/notionnext/tree/main/lib/notion/"
    click CacheManager "https://github.com/tangly1024/notionnext/blob/main/lib/cache/cache_manager.js"
    click MemCache "https://github.com/tangly1024/notionnext/blob/main/lib/cache/memory_cache.js"
    click FileCache "https://github.com/tangly1024/notionnext/blob/main/lib/cache/local_file_cache.js"
    click RedisCache "https://github.com/tangly1024/notionnext/blob/main/lib/cache/redis_cache.js"
    click Plugins "https://github.com/tangly1024/notionnext/tree/main/lib/plugins/"
    click Utils "https://github.com/tangly1024/notionnext/tree/main/lib/utils/"
    click Conf "https://github.com/tangly1024/notionnext/tree/main/conf/"
    click GlobalConfig "https://github.com/tangly1024/notionnext/blob/main/blog.config.js"
    click GlobalConfig "https://github.com/tangly1024/notionnext/blob/main/next.config.js"
    click GlobalConfig "https://github.com/tangly1024/notionnext/blob/main/next-sitemap.config.js"
    click Components "https://github.com/tangly1024/notionnext/tree/main/components/"
    click Themes "https://github.com/tangly1024/notionnext/tree/main/themes/"
    click ThemeLoader "https://github.com/tangly1024/notionnext/blob/main/themes/theme.js"
    click PublicAssets "https://github.com/tangly1024/notionnext/tree/main/public/"
    click Styles "https://github.com/tangly1024/notionnext/tree/main/styles/"
    click TailwindConfig "https://github.com/tangly1024/notionnext/blob/main/tailwind.config.js"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef cache fill:#D1C4E9,stroke:#7E57C2,color:#4A148C
```
