# s20024/plog architecture

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

- Interactive diagram: https://gitdiagram.com/s20024/plog
- Repository: https://github.com/s20024/plog

## Overview

##### Project type and purpose
- This is a **static blogging site** built with the Astro framework.
- It reads MDX/MD files from the `src/content` folders, compiles them through Astro + React/TypeScript components, and outputs static HTML/CSS/JS to be served on a CDN or GitHub Pages under a custom domain (`CNAME`).
- There is no traditional backend or database; content is filesystem-based and the site is generated at build time.

##### File structure
- Top-level config files: `astro.config.mjs`, `package.json`, `tsconfig.json`, `.github/workflows/deploy.yml`
- `public/`: holds static assets (images, fonts) which are copied verbatim to the site root.
- `src/` subdivides into:
- `components/`: React/TSX and Astro UI components (e.g., `PostCard.astro`, `Profile.tsx`)
- `layouts/`: Astro layouts (e.g., `BaseLayout.astro`) and shared UI wrappers
- `content/`: file-based posts in `mdx`/`md` under subdirectories (`news/`, `plog/`, `memo/`)
- `pages/`: Astro routing by filename, with dynamic `[...slug].astro` pages for each content type and static pages (`about.astro`, `index.astro`, `rss.xml.js`)
- `styles/`: global SCSS
- `consts.ts` & `content.config.ts`: central configuration and metadata

##### README for additional insights
- Astro CLI is used to run dev server (`npm run dev`), build (`npm run build`), and preview.
- Uses Prettier for formatting.
- No mention of external APIs except Google Analytics included in `src/components/layout/GoogleAnalytics.astro`.

a. Main components
- Developer Environment (VSCode, Node.js, Astro CLI)
- Content Source (Markdown/MDX files under `src/content`)
- UI Component Library (`src/components`, `src/layouts`)
- Static Site Generator (Astro)
- Public Assets (`public/`)
- Build Output (`dist/`)
- Hosting/CDN (GitHub Pages or similar)
- External Service: Google Analytics

b. Relationships and interactions
- Developer edits content & components → commits to GitHub
- CI Workflow triggers on push → runs Astro build → places static output in `dist/` → deploys to hosting
- At runtime, end users request pages → CDN serves prebuilt HTML/CSS/JS → pages may load GA snippet

c. Architectural patterns and principles
- **Jamstack** (pre-rendered static pages + CDN)
- **Component-based UI** (React/TSX + Astro Islands)
- **Filesystem-based routing** (Astro’s pages directory)
- **Separation of concerns** (content vs. layout vs. presentation components)

d. Key technologies/frameworks
- Astro (static site generator)
- React (used inside Astro for UI Islands)
- TypeScript
- SCSS Modules for styling
- MDX for content
- GitHub Actions for CI/CD
- GitHub Pages (implied by `CNAME`)
- Prettier

##### Elements
- **Clear labels**: “MDX Content,” “Astro Engine,” “React Components,” “Static Assets,” “GitHub Actions,” “CDN / GitHub Pages,” “Google Analytics.”
- From Developer → GitHub repo
- From Repo → GitHub Actions → Astro build → Deployment
- From CDN → End User
- From served pages → Google Analytics
- Green for code/artifacts (MDX, TSX, SCSS)
- Blue for processes (Build step, CI/CD)
- Orange for hosting infra (CDN, Pages)
- Gray for third-party service (GA snippet)

##### Detail without over-splitting
- End-to-end data flow: edit → build → deploy → serve → analytics.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        Developer["Developer"]:::external
        DevTools["VSCode + Node.js + Astro CLI"]:::external
    end

    %% Source Components
    subgraph "Source Repositories"
        GitHubRepo["GitHub Repository"]:::infra
        ContentSource["Content Source<br/>(MDX/MD files)"]:::artifact
        UIComponents["UI Components<br/>(React/TSX & Astro)"]:::artifact
        Layouts["Layout Components<br/>(Astro layouts & wrappers)"]:::artifact
        StaticAssets["Static Assets<br/>(images, fonts)"]:::artifact
        GlobalStyles["Global Styles<br/>(SCSS)"]:::artifact
        SiteConfig["Site Configuration<br/>(astro.config.mjs, content.config.ts, consts.ts, tsconfig.json)"]:::artifact
        FilesystemRouting["Filesystem-based Routing<br/>(Astro pages & dynamic routes)"]:::artifact
    end

    %% Build Pipeline
    subgraph "Build & Deployment"
        GitHubActions["GitHub Actions<br/>(CI/CD)"]:::process
        AstroBuild["Astro Build<br/>(Astro & React compile)"]:::process
        Dist["Build Output<br/>(dist/)"]:::artifact
        Hosting["CDN / GitHub Pages"]:::infra
        CustomDomain["Custom Domain<br/>(CNAME)"]:::infra
    end

    %% Runtime
    subgraph "Runtime"
        EndUser["End Users<br/>(Browsers)"]:::infra
        GA["Google Analytics"]:::external
    end

    %% Connections
    Developer --> DevTools
    Developer -->|commits code| GitHubRepo
    DevTools --> GitHubRepo

    GitHubRepo -->|triggers build| GitHubActions
    ContentSource --> AstroBuild
    UIComponents --> AstroBuild
    Layouts --> AstroBuild
    StaticAssets --> AstroBuild
    GlobalStyles --> AstroBuild
    SiteConfig --> AstroBuild
    FilesystemRouting --> AstroBuild

    GitHubActions --> AstroBuild
    AstroBuild --> Dist
    Dist --> Hosting
    Hosting --> EndUser
    Hosting --> CustomDomain
    EndUser -->|loads GA snippet| GA

    %% Click Events
    click ContentSource "https://github.com/s20024/plog/tree/main/src/content/"
    click StaticAssets "https://github.com/s20024/plog/tree/main/public/"
    click UIComponents "https://github.com/s20024/plog/tree/main/src/components/"
    click Layouts "https://github.com/s20024/plog/tree/main/src/layouts/"
    click GlobalStyles "https://github.com/s20024/plog/blob/main/src/styles/global.scss"
    click SiteConfig "https://github.com/s20024/plog/blob/main/astro.config.mjs"
    click SiteConfig "https://github.com/s20024/plog/blob/main/src/content.config.ts"
    click SiteConfig "https://github.com/s20024/plog/blob/main/src/consts.ts"
    click SiteConfig "https://github.com/s20024/plog/blob/main/tsconfig.json"
    click FilesystemRouting "https://github.com/s20024/plog/tree/main/src/pages/"
    click GitHubActions "https://github.com/s20024/plog/blob/main/.github/workflows/deploy.yml"
    click GA "https://github.com/s20024/plog/blob/main/src/components/layout/GoogleAnalytics.astro"
    click CustomDomain "https://github.com/s20024/plog/tree/main/CNAME"

    %% Styles
    classDef artifact fill:#a8f0c6,stroke:#333,stroke-width:1px
    classDef process fill:#84c1ff,stroke:#333,stroke-width:1px
    classDef infra fill:#f5b971,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
