# yyycc/whatsoever architecture

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

- Interactive diagram: https://gitdiagram.com/yyycc/whatsoever
- Repository: https://github.com/yyycc/whatsoever

## Overview

##### Project Type and Purpose
- This is a Gatsby‐based static site generator (SSG) built with TypeScript.
- Its primary purpose is to render a blog/documentation site from MDX content and React components, producing fully static HTML/CSS/JS at build time and hydrating it in the browser.

##### High‐Level Architecture Components
a. Source Content Layer
- MDX/Markdown files under `blog/` and `src/pages/`
- Static assets in `src/images/` and stylesheets (`.scss`, `css`)
b. Plugin & Transformer Layer
- `gatsby-config.ts`: defines plugins (e.g. `gatsby-source-filesystem`, MDX plugin, remark plugins) and site metadata
- Custom plugin in `plugins/gatsby-remark-code-buttons` for adding code‐copy buttons
- Transformers: `gatsby-transformer-remark`/`gatsby-plugin-mdx` that turn MDX into GraphQL nodes
c. Data Layer (GraphQL)
- Gatsby’s in‐memory GraphQL schema generated at build time from filesystem and plugin nodes
- Queries in page templates to pull frontmatter, HTML AST, image data, etc.
d. Page Generation Layer
- `gatsby-node.ts`: uses Node APIs (`onCreateNode`, `createPages`) to build pages programmatically (e.g. dynamic blog‐post pages using `{mdx.frontmatter__slug}.tsx`)
- Templates under `src/pages` and shared components under `src/components` produce static HTML
e. Client Application Layer
- React components (`header`, `footer`, `blog-list`, `common-*`) compiled into JS bundles
- Hydration/runtime hooks in `gatsby-browser.ts` (e.g. wrapRootElement)
f. Server‐Side Rendering & Deployment
- `gatsby-ssr.ts` for injecting `<head>` tags, styles
- Final output: static `/public` folder with HTML, JS, CSS ready for any static host (Gatsby Cloud, Netlify, etc.)

##### Relationships & Data Flow
1. Filesystem → Gatsby Source Plugins
2. Source Plugins → Transformer Plugins
- Transformer plugins convert raw files into GraphQL nodes.
3. Transformer Plugins → GraphQL Schema
- All nodes are stitched into Gatsby’s schema.
4. GraphQL Queries in Page Templates
- Page templates/components query data at build time.
5. Page Generation (`createPages`)
- Gatsby Node API uses query results to generate static HTML pages.
6. SSR & Asset Injection
- `gatsby-ssr.ts` injects global CSS, metadata.
7. Client Hydration
- `gatsby-browser.ts` sets up React context/hooks for interactivity.
8. Deployment
- Final `/public` folder served as static site.

##### Architectural Patterns & Design Principles
- Plugin Architecture: clear extension points via Gatsby Node APIs
- Component-Based UI: React + modular SCSS for style encapsulation
- Static Site Generation: pre-render everything at build time for performance
- GraphQL Data Layer: decouples content from presentation

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Source Content Layer
  subgraph "Source Content Layer"
    SC1["MDX/Markdown Files"]:::content
    SC2["Static Assets (Images)"]:::content
    SC3a["src/style.scss"]:::content
    SC3b["src/styles/"]:::content
    SC3c["src/normalize.css"]:::content
  end

  %% Plugin & Transformer Layer
  subgraph "Plugin & Transformer Layer"
    Cfg["gatsby-config.ts"]:::plugin
    GPFS["gatsby-source-filesystem"]:::plugin
    MDX["gatsby-plugin-mdx / remark"]:::plugin
    CustomP["gatsby-remark-code-buttons"]:::plugin
  end

  %% Data Layer
  GraphQL["GraphQL Schema"]:::data

  %% Page Generation Layer
  subgraph "Page Generation Layer"
    NodeAPI["gatsby-node.ts"]:::process
    Templates1["Dynamic MDX Pages"]:::process
    Templates2["Blog Listing Pages"]:::process
    Templates3["Static Pages"]:::process
  end

  %% SSR & Deployment
  SSR["gatsby-ssr.ts"]:::process
  Output["/public Folder (Static Site)"]:::output

  %% Data & Hooks Layer
  subgraph "Data & Hooks Layer"
    Hook1["use-site-metadata"]:::data
    Hook2["use-blog-home"]:::data
    DataUtil["shared data utilities"]:::data
    Util["common utils"]:::data
  end

  %% Client Runtime Layer
  subgraph "Client Runtime"
    BrowserAPI["gatsby-browser.ts"]:::runtime
    BrowserApp["Browser"]:::runtime
    subgraph "React Components"
      Layout["Layout & UI Components"]:::runtime
      SEO["SEO Component"]:::runtime
      Header["Header Component"]:::runtime
      Footer["Footer Component"]:::runtime
      BlogList["Blog List Preview"]:::runtime
      Category["Category Badges"]:::runtime
      CommonAI["Common AI Examples"]:::runtime
      CommonReading["Common Reading List"]:::runtime
      CommonSC["Common Source-Code Block"]:::runtime
      CommonStories["Common Stories Snippets"]:::runtime
      Timeline["Timeline Display"]:::runtime
      Info["Info Panels"]:::runtime
      FrontEnd["Front-End Topics"]:::runtime
    end
  end

  %% Build Pipeline Flow
  SC1 --> GPFS
  SC2 --> GPFS
  SC3a --> GPFS
  SC3b --> GPFS
  SC3c --> GPFS
  Cfg --> GPFS
  Cfg --> MDX
  Cfg --> CustomP
  GPFS --> MDX
  MDX --> GraphQL
  GraphQL --> NodeAPI
  NodeAPI --> Templates1
  NodeAPI --> Templates2
  NodeAPI --> Templates3
  Templates1 --> SSR
  Templates2 --> SSR
  Templates3 --> SSR
  SSR --> Output

  %% Runtime Flow
  Output --> BrowserApp
  BrowserApp -->|"hydrates"| Layout
  BrowserApp --> BrowserAPI
  BrowserAPI --> Layout
  Layout --> SEO
  Layout --> Header
  Layout --> Footer
  Layout --> BlogList
  BlogList --> Category
  BlogList --> CommonAI
  BlogList --> CommonReading
  BlogList --> CommonSC
  BlogList --> CommonStories
  BlogList --> Timeline
  BlogList --> Info
  BlogList --> FrontEnd

  %% Data & Hooks Integration
  Layout --> Hook1
  BlogList --> Hook2
  Layout --> DataUtil
  Layout --> Util

  %% Click Events
  click SC1 "https://github.com/yyycc/whatsoever/tree/main/blog/"
  click SC2 "https://github.com/yyycc/whatsoever/tree/main/src/images/"
  click SC3a "https://github.com/yyycc/whatsoever/blob/main/src/style.scss"
  click SC3b "https://github.com/yyycc/whatsoever/tree/main/src/styles/"
  click SC3c "https://github.com/yyycc/whatsoever/blob/main/src/normalize.css"
  click Cfg "https://github.com/yyycc/whatsoever/blob/main/gatsby-config.ts"
  click CustomP "https://github.com/yyycc/whatsoever/tree/main/plugins/gatsby-remark-code-buttons/"
  click NodeAPI "https://github.com/yyycc/whatsoever/blob/main/gatsby-node.ts"
  click SSR "https://github.com/yyycc/whatsoever/blob/main/gatsby-ssr.ts"
  click BrowserAPI "https://github.com/yyycc/whatsoever/blob/main/gatsby-browser.ts"
  click Templates1 "https://github.com/yyycc/whatsoever/blob/main/src/pages/blog/{mdx.frontmatter__slug}.tsx"
  click Templates2 "https://github.com/yyycc/whatsoever/tree/main/src/pages/blog/"
  click Templates3 "https://github.com/yyycc/whatsoever/tree/main/src/pages/"
  click Layout "https://github.com/yyycc/whatsoever/blob/main/src/components/layout.tsx"
  click SEO "https://github.com/yyycc/whatsoever/blob/main/src/components/seo.tsx"
  click Header "https://github.com/yyycc/whatsoever/blob/main/src/components/header/header.tsx"
  click Footer "https://github.com/yyycc/whatsoever/blob/main/src/components/footer/footer.tsx"
  click BlogList "https://github.com/yyycc/whatsoever/blob/main/src/components/blog-list/blog-list.tsx"
  click Category "https://github.com/yyycc/whatsoever/blob/main/src/components/category/category.tsx"
  click CommonAI "https://github.com/yyycc/whatsoever/blob/main/src/components/common-ai/common-ai.tsx"
  click CommonReading "https://github.com/yyycc/whatsoever/blob/main/src/components/common-reading/common-reading.tsx"
  click CommonSC "https://github.com/yyycc/whatsoever/blob/main/src/components/common-source-code/common-source-code.tsx"
  click CommonStories "https://github.com/yyycc/whatsoever/blob/main/src/components/common-stories/common-stories.tsx"
  click Timeline "https://github.com/yyycc/whatsoever/blob/main/src/components/timeline/timeline.tsx"
  click Info "https://github.com/yyycc/whatsoever/blob/main/src/components/info/info.tsx"
  click FrontEnd "https://github.com/yyycc/whatsoever/blob/main/src/components/front-end/front-end.tsx"
  click Hook1 "https://github.com/yyycc/whatsoever/blob/main/src/hooks/use-site-metadata.tsx"
  click Hook2 "https://github.com/yyycc/whatsoever/blob/main/src/hooks/use-blog-home.tsx"
  click DataUtil "https://github.com/yyycc/whatsoever/blob/main/src/components/data.ts"
  click Util "https://github.com/yyycc/whatsoever/blob/main/src/utils/common.ts"

  %% Styles
  classDef content fill:#D0E6A5,stroke:#333,stroke-width:1px
  classDef plugin fill:#FFDD94,stroke:#333,stroke-width:1px
  classDef data fill:#9EC1CF,stroke:#333,stroke-width:1px
  classDef process fill:#C3FBD8,stroke:#333,stroke-width:1px
  classDef runtime fill:#FFE0E0,stroke:#333,stroke-width:1px
  classDef output fill:#E0E0E0,stroke:#333,stroke-width:1px
```
