# woongsnote/woongsnote-dev architecture

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

- Interactive diagram: https://gitdiagram.com/woongsnote/woongsnote-dev
- Repository: https://github.com/woongsnote/woongsnote-dev

## Overview

##### Project type and purpose
- This is a **static site/blog** built with **Astro** (a static site generator), using **TypeScript** and **Tailwind CSS**.
- Purpose: to publish technical articles (MDX content), with features like SEO, dark mode, reading-time calculation, comments (via Giscus), RSS and sitemap support.

##### File structure
- Top-level config:
- astro.config.mjs (Astro config)
- content.config.ts (Contentlayer or Astro content config)
- package.json, tsconfig.json, prettier.config.cjs
- public/
- fonts and other static assets
- src/
- content/ (all blog posts in `.mdx`)
- config/ (site-wide settings)
- layouts/ (BaseHead, BaseLayout, PostLayout)
- components/ (UI atoms, molecules, e.g. Article, Header, Footer, Tag, Toc, SocialLink, etc.)
- pages/ (Astro file-system routing: index.astro, about.astro, blog/[slug].astro, 404.astro, robots.txt, rss.xml.js)
- styles/ (global.css, typography.css)
- utils/ (data-util.ts, share-util.ts, types.ts)
- Plugins/scripts:
- remark-reading-time.mjs (reading time metadata)
- rss.xml.js, sitemap generated via Astro or plugin

##### README for additional insights
- The README confirms tech stack (Astro, TS, Tailwind), core features (responsive UI, SEO, dark mode, Giscus comments, sitemap, RSS).
- No pre-drawn architecture—but we know it’s an SSG pipeline with external comment service.

a. Main components
- Content Source: `.mdx` files under src/content
- Content Processor: Astro + content.config.ts (+ remark-reading-time plugin)
- Component Library: src/components + Tailwind CSS
- Layouts & Templates: src/layouts
- Page Router: src/pages (file-based routing)
- Asset Pipeline: src/assets + public/
- Build Engine: Astro’s build command (generates static HTML/CSS/JS)
- Third-Party Services:
- Giscus comment widget (GitHub Discussions integration)
- RSS feed generator (rss.xml.js)
- Sitemap generator (Astro plugin or custom)
- Hosting/Deployment: Vercel (or any static-host)

b. Relationships & data flow
1. MDX files → parsed by Contentlayer/config → frontmatter + AST
2. Plugins (remark-reading-time) enrich AST with metadata
3. Astro compiles pages:
- Routes in src/pages import data & components
- Layouts wrap page content
- Components render UI (Header, Article, Footer, etc.)
- Tailwind CSS applies styling
4. Build output → static assets in `dist/` or `public/`
5. Deploy to hosting → end-user fetches static HTML/CSS/JS
6. At runtime, Giscus script loads comments widget via GitHub API

c. Architectural patterns & design principles
- Static-Site Generation (SSG) pipeline
- Component-based UI (reusable Astro components)
- File-system routing for pages
- Separation of concerns:
- Content vs. Layout vs. Presentation vs. Utilities
- Plugin-driven content transforms (remark plugins)

d. Key technologies & libraries
- Astro (core SSG framework)
- TypeScript
- Tailwind CSS (utility-first styling)
- MDX / Contentlayer (content ingestion)
- remark-reading-time (plugin)
- Giscus (comments)
- RSS & Sitemap generators
- Vercel (recommended deployment target)

##### Final advice
- Be very granular: show each plugin, config file, and directory group as its own node if space allows.
- Essence: content ingestion → compilation → static output → deployment → runtime widget (comments).
- Don’t over-engineer: a clear separation of content, build, and runtime is enough to convey the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Content Source Layer
  subgraph "Content Source" 
    MDX["MDX Files"]:::content
  end
  click MDX "https://github.com/woongsnote/woongsnote-dev/tree/main/src/content/blog/"

  %% Content Processing Layer
  subgraph "Content Processor"
    CLConfig["content.config.ts"]:::processor
    Plugin["remark-reading-time.mjs"]:::processor
    AstroConfig["astro.config.mjs"]:::processor
  end
  click CLConfig "https://github.com/woongsnote/woongsnote-dev/blob/main/src/content.config.ts"
  click Plugin "https://github.com/woongsnote/woongsnote-dev/blob/main/remark-reading-time.mjs"
  click AstroConfig "https://github.com/woongsnote/woongsnote-dev/blob/main/astro.config.mjs"

  %% Build Engine
  subgraph "Build Engine"
    Build["Astro Build"]:::processor
  end

  %% UI, Layouts, Pages, Assets, Styles, Utils
  subgraph "Source Code Modules"
    subgraph "UI Components" 
      CompLib["src/components/"]:::ui
      Comments["Comments Widget"]:::ui
    end
    subgraph "Layouts"
      BaseHead["BaseHead.astro"]:::ui
      BaseLayout["BaseLayout.astro"]:::ui
      PostLayout["PostLayout.astro"]:::ui
    end
    subgraph "Pages & Feeds"
      Index["index.astro"]:::ui
      About["about.astro"]:::ui
      BlogPage["blog/[slug].astro"]:::ui
      NotFound["404.astro"]:::ui
      Robots["robots.txt.ts"]:::ui
      RSS["rss.xml.js"]:::ui
    end
    subgraph "Assets & Public"
      AssetsDir["src/assets/"]:::ui
      Public["public/"]:::ui
    end
    subgraph "Styles & Utilities"
      GlobalCSS["global.css"]:::ui
      Typography["typography.css"]:::ui
      DataUtil["data-util.ts"]:::ui
      ShareUtil["share-util.ts"]:::ui
      Types["types.ts"]:::ui
    end
    SiteConfig["site-config.ts"]:::processor
  end

  click CompLib "https://github.com/woongsnote/woongsnote-dev/tree/main/src/components/"
  click Comments "https://github.com/woongsnote/woongsnote-dev/blob/main/src/components/Article/Comments.astro"
  click BaseHead "https://github.com/woongsnote/woongsnote-dev/blob/main/src/layouts/BaseHead.astro"
  click BaseLayout "https://github.com/woongsnote/woongsnote-dev/blob/main/src/layouts/BaseLayout.astro"
  click PostLayout "https://github.com/woongsnote/woongsnote-dev/blob/main/src/layouts/PostLayout.astro"
  click Index "https://github.com/woongsnote/woongsnote-dev/blob/main/src/pages/index.astro"
  click About "https://github.com/woongsnote/woongsnote-dev/blob/main/src/pages/about.astro"
  click BlogPage "https://github.com/woongsnote/woongsnote-dev/blob/main/src/pages/blog/[slug].astro"
  click NotFound "https://github.com/woongsnote/woongsnote-dev/blob/main/src/pages/404.astro"
  click Robots "https://github.com/woongsnote/woongsnote-dev/blob/main/src/pages/robots.txt.ts"
  click RSS "https://github.com/woongsnote/woongsnote-dev/blob/main/src/pages/rss.xml.js"
  click AssetsDir "https://github.com/woongsnote/woongsnote-dev/tree/main/src/assets/"
  click Public "https://github.com/woongsnote/woongsnote-dev/tree/main/public/"
  click GlobalCSS "https://github.com/woongsnote/woongsnote-dev/blob/main/src/styles/global.css"
  click Typography "https://github.com/woongsnote/woongsnote-dev/blob/main/src/styles/typograpy.css"
  click DataUtil "https://github.com/woongsnote/woongsnote-dev/blob/main/src/utils/data-util.ts"
  click ShareUtil "https://github.com/woongsnote/woongsnote-dev/blob/main/src/utils/share-util.ts"
  click Types "https://github.com/woongsnote/woongsnote-dev/blob/main/src/utils/types.ts"
  click SiteConfig "https://github.com/woongsnote/woongsnote-dev/blob/main/src/config/site-config.ts"

  %% Hosting & Runtime
  subgraph "Hosting & Runtime"
    Vercel["Vercel Hosting"]:::external
    GiscusAPI["Giscus API"]:::external
  end

  %% Data Flows
  MDX -->|"parse MDX\n& frontmatter"| CLConfig
  CLConfig -->|"apply plugins"| Plugin
  Plugin -->|"generate AST"| Build
  AstroConfig -->|"configure build"| Build
  Build -->|"imports components & layouts"| CompLib
  Build --> CompLib
  Build --> BaseHead
  Build --> BaseLayout
  Build --> PostLayout
  Build --> Index
  Build --> About
  Build --> BlogPage
  Build --> NotFound
  Build --> Robots
  Build --> RSS
  Build --> GlobalCSS
  Build --> Typography
  Build --> DataUtil
  Build --> ShareUtil
  Build --> Types
  Build --> AssetsDir
  Build --> Public
  Public -->|"deploy static site"| Vercel
  Public -->|"serves static HTML/CSS/JS"| Vercel
  Vercel -->|"browser load"| GiscusAPI
  Public -->|"client script loads"| GiscusAPI

  %% Styles
  classDef content fill:#E3F2FD,stroke:#90CAF9
  classDef processor fill:#E8F5E9,stroke:#A5D6A7
  classDef ui fill:#FFF3E0,stroke:#FFCC80
  classDef external fill:#F5F5F5,stroke:#BDBDBD
```
