# expoli/notionnext architecture

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

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

## Overview

This project is a Next.js–based static blog system that leverages the Notion API as its content source. It dynamically builds pages using a rich set of React components (with a heavy emphasis on theming) and serverless API routes. The overall architecture combines both static-site generation and on-demand API functionality, integrating several external services (e.g., comment systems, analytics, and various plugins) and a multi-theme system.

##### Main Components
- Browser / Client: The end-user interface that makes HTTP requests.
- Next.js Server: Serves as both the SSR/SSG engine and the server-rendered “backend” via API routes (found under the /pages/api folder). It handles page rendering, middleware, routing, and integration with external APIs.
- Notion API: The external content source that the application pulls blog posts, pages, and metadata from. This integration is abstracted within the library under /lib/notion.
- Theming / UI Components: Your views are composed of a huge collection of components (in /components) and theme implementations (in /themes) which provide the presentation layer.
- External Services & Plugins: This includes comment systems (Twikoo, Giscus, Gitalk, etc.), analytics (Busuanzi, Gtag, etc.), and other external script integrations defined in both components and configuration files.
- Caching & Utility Modules: In /lib/cache and related utilities for performance improvements (in-memory cache, redis cache, etc.).
- Deployment Pipeline: Vercel handles deployment, and there are GitHub workflows and Docker configurations that are part of the DevOps pipeline.

##### Relationships and Interactions
- The Browser interacts with the Next.js application deployed on Vercel by requesting pages.
- For each page request, Next.js might perform static site generation or server-side rendering. During page generation, the Next.js backend calls the Notion API (via modules in /lib/notion) to fetch native content and metadata.
- Various components from the /components and theme-specific directories in /themes assemble the final rendered page.
- API routes (under /pages/api) provide functionality such as authentication callbacks, caching measures, and subscription endpoints.
- External services (like comment providers) integrate through both client-side scripts and server-side configuration (see components like Twikoo.js, Giscus.js, Utterances.js, etc.).
- Caching layers and plugins (in /lib/cache and /lib/plugins) manage performance and optimization, storing it in Redis or memory where appropriate.
- The deployment pipeline (Dockerfile, GitHub workflows) automates tests, build, and deployment targeting Vercel.

##### Key Architectural Patterns and Design Principles
- Separation of concerns between UI (themes/components), business logic (lib and conf directories), and API/integration layers (pages/api, lib/notion).
- Use of serverless functions via Next.js API routes.
- Modular theming: Multiple themes exist as independent modules under /themes to allow extensive customization.
- Use of external configuration files (in conf and in configuration files like next.config.js) for centralized settings.
- Emphasis on caching and performance (caching modules, static generation).

##### Relevant Technologies, Frameworks, and Libraries
- Next.js for SSR/SSG.
- React for component-driven UI.
- Tailwind CSS (with associated config files like tailwind.config.js) for styling.
- Notion API integration via modules located in /lib/notion.
- Various analytics and comment libraries integrated as components.
- Serverless deployment (Vercel) with CI/CD automation (GitHub Actions under .github/workflows).

##### Details to Be Included
- Clear labels for each module and component.
- Notation of technologies where relevant (e.g., “Next.js SSR”, “React Components”, “Notion API”, “Vercel Deployment”).
- Optionally, illustrate the filesystem structure indicating where key modules like /components, /lib/notion, /themes, and /pages/api reside.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Browser / Client (User Interface)"]:::client

    %% Server Layer
    subgraph "Server Layer"
        subgraph "Next.js Server"
            SSR["Next.js SSR/SSG"]:::server
            API["Next.js API Routes"]:::api
        end
        Notion["Notion API Integration"]:::external
        Cache["Caching & Utility Modules"]:::cache
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Theming / UI Components"]:::frontend
    end

    %% External Services & Plugins
    Ext["External Services & Plugins"]:::external

    %% Deployment Pipeline
    Deployment["Deployment Pipeline"]:::deployment

    %% Data Flows
    Browser -->|"requests"| SSR
    Browser -->|"AJAX calls"| API

    SSR -->|"fetches content"| Notion
    SSR -->|"renders page"| UI
    SSR -->|"uses caching"| Cache

    API -->|"processes data"| Cache
    API -->|"integrates with"| Ext

    UI -->|"includes scripts from"| Ext

    %% Deployment flow
    Deployment -->|"deploys to"| SSR
    Deployment -->|"deploys configuration to"| API

    %% Click Events
    click SSR "https://github.com/expoli/notionnext/blob/main/pages/_app.js"
    click SSR "https://github.com/expoli/notionnext/blob/main/pages/_document.js"
    click API "https://github.com/expoli/notionnext/tree/main/pages/api"
    click Notion "https://github.com/expoli/notionnext/tree/main/lib/notion"
    click UI "https://github.com/expoli/notionnext/tree/main/components"
    click UI "https://github.com/expoli/notionnext/tree/main/themes"
    click Ext "https://github.com/expoli/notionnext/blob/main/components/Twikoo.js"
    click Ext "https://github.com/expoli/notionnext/blob/main/components/Giscus.js"
    click Ext "https://github.com/expoli/notionnext/blob/main/components/Gitalk.js"
    click Cache "https://github.com/expoli/notionnext/tree/main/lib/cache"
    click Cache "https://github.com/expoli/notionnext/tree/main/lib/utils"
    click Deployment "https://github.com/expoli/notionnext/tree/main/.github/workflows"
    click Deployment "https://github.com/expoli/notionnext/tree/main/Dockerfile"
    click Deployment "https://github.com/expoli/notionnext/blob/main/vercel.json"

    %% Styles
    classDef client fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef server fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef api fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef external fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef frontend fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef cache fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef deployment fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
```
