# naturelr/blog architecture

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

- Interactive diagram: https://gitdiagram.com/naturelr/blog
- Repository: https://github.com/naturelr/blog

## Overview

##### Project Type and Purpose
- This is a *static website* project combining:
- A Hexo‐based blog (Next theme)
- A docsify‐powered documentation site
- It uses Node.js and Docker locally and in CI for build, then publishes generated HTML to one or more GitHub Pages repos under custom domains (`blog.naturelr.cc`, `docs.naturelr.cc`).

##### Main Components
- Developer Workstation
- Local Node.js + Hexo‐CLI (via global npm)
- Optional Docker container (via `Dockerfile`, `.dockerignore`)
- Local source content (`source/`), theme, configs (`_config.yml`, `_config.next.yml`, `_admin-config.yml`)
- Source Repository
- Content directory (`source/`) with posts, drafts, configs, styles
- Build scripts (Makefile, `deploy.sh`)
- CI config (`.github/workflows/*.yaml`)
- CI/CD Pipeline (GitHub Actions)
- build-env-image: builds the Docker image used in CI
- build-image: builds an image with Node.js, Hexo, docsify setup
- deploy: runs `hexo generate`, `docsify` build (if applicable), pushes `public/` to target Pages repo
- Static Site Generator
- Hexo + Next theme transforms Markdown in `source/_posts`, `source/_drafts` into HTML/CSS/JS
- docsify serves `source/` as a dynamic docs site
- Hosting & Delivery
- GitHub Pages repos (blog and docs)
- Custom domains via CNAME files and DNS
- CDN (GitHub Pages) for global static delivery
- External Services
- npm registry (for theme and plugin installs)
- (Optional) Docker Hub or GitHub Packages for container images

##### Relationships & Data Flows
- Developer edits Markdown → commits to GitHub
- Git push triggers GitHub Actions workflow
- Actions pull code, build Docker image, install npm deps
- Inside container: run `hexo generate` → outputs `public/`; run `docsify` build → outputs docs directory
- Deploy step pushes static output to GitHub Pages branch
- DNS routes requests for `blog.naturelr.cc` / `docs.naturelr.cc` → GitHub Pages servers → end users

##### Architectural Patterns & Principles
- **Separation of Concerns**: content, theme/config, build pipeline, hosting
- **Immutable Builds**: Docker images ensure consistent build environment
- **CI/CD**: all builds and deploys automated via GitHub Actions
- **Static Site Delivery**: no runtime backend—pure HTML/CSS/JS served via CDN
- **Extensibility Points**: Hexo plugins, Next theme customizations, docsify config

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Local Development Environment
    subgraph "Developer Workstation" 
        style Developer fill:#f2f2f2,stroke:#333,stroke-width:1px
        DevNode["Node.js + Hexo-CLI"] 
        DevDocker["Dockerfile / .dockerignore"] 
    end

    %% Source Repository
    subgraph "GitHub Repository" 
        style Repo fill:#ffffff,stroke:#333,stroke-width:1px
        RepoContent["source/ (Markdown, assets)"] 
        RepoConfigs["_config.yml<br>_config.next.yml<br>_admin-config.yml<br>.nojekyll"] 
        RepoPackage["package.json<br>package-lock.json"] 
        RepoScripts["makefile<br>gen_sidebar.sh<br>deploy.sh"] 
        RepoDrawio["drawio/ (diagrams)"] 
        RepoWorkflows[".github/workflows/<br>build-env-image.yaml<br>build-image.yaml<br>deploy.yaml"] 
        RepoMeta["README.md<br>LICENSE<br>source/LICENSE"] 
    end

    %% CI/CD Pipeline
    subgraph "GitHub Actions (CI)" 
        style CI fill:#cce5ff,stroke:#004085,stroke-width:1px
        WorkflowBuildEnv["build-env-image"] 
        WorkflowBuildSite["build-image"] 
        WorkflowDeploy["deploy"] 
    end

    %% Build Environment
    subgraph "Docker Build Environment" 
        style BuildEnv fill:#d4edda,stroke:#155724,stroke-width:1px
        HexoGen["Hexo Generator"] 
        DocsifyBuild["docsify Builder"] 
    end

    %% Hosting & Delivery
    subgraph "Hosting & CDN" 
        style Hosting fill:#fff3cd,stroke:#856404,stroke-width:1px
        PagesBlog["GitHub Pages (blog.naturelr.cc)"] 
        PagesDocs["GitHub Pages (docs.naturelr.cc)"] 
        DNS["DNS / CNAME"] 
        CDN["CDN (GitHub Pages)"] 
    end

    %% End Users
    User["End Users"]

    %% Interactions
    DevNode -->|"edit Markdown\n& configs\n"| RepoContent
    DevDocker -->|"build locally"| HexoGen
    RepoContent -->|"git push"| WorkflowBuildEnv
    RepoConfigs --> WorkflowBuildEnv
    RepoPackage --> WorkflowBuildEnv
    RepoScripts --> WorkflowBuildEnv
    RepoDrawio --> WorkflowBuildEnv
    RepoWorkflows --> WorkflowBuildEnv
    WorkflowBuildEnv -->|"build Docker image"| BuildEnv
    WorkflowBuildSite -->|"run in container"| HexoGen
    WorkflowBuildSite -->|"run in container"| DocsifyBuild
    HexoGen -->|"generate public/"| WorkflowDeploy
    DocsifyBuild -->|"generate docs output"| WorkflowDeploy
    WorkflowDeploy -->|"push static files"| PagesBlog
    WorkflowDeploy -->|"push static files"| PagesDocs
    DNS --> PagesBlog
    DNS --> PagesDocs
    PagesBlog --> CDN
    PagesDocs --> CDN
    CDN -->|"HTTP request"| User

    %% GitHub Actions flow
    WorkflowBuildEnv --> WorkflowBuildSite
    WorkflowBuildSite --> WorkflowDeploy

    %% Click Events
    click DevDocker "https://github.com/naturelr/blog/tree/master/Dockerfile"
    click DevDocker "https://github.com/naturelr/blog/blob/master/.dockerignore"
    click RepoPackage "https://github.com/naturelr/blog/blob/master/package.json"
    click RepoPackage "https://github.com/naturelr/blog/blob/master/package-lock.json"
    click RepoScripts "https://github.com/naturelr/blog/tree/master/makefile"
    click RepoScripts "https://github.com/naturelr/blog/blob/master/gen_sidebar.sh"
    click RepoConfigs "https://github.com/naturelr/blog/blob/master/_config.yml"
    click RepoConfigs "https://github.com/naturelr/blog/blob/master/_config.next.yml"
    click RepoConfigs "https://github.com/naturelr/blog/blob/master/_admin-config.yml"
    click RepoConfigs "https://github.com/naturelr/blog/blob/master/.nojekyll"
    click RepoContent "https://github.com/naturelr/blog/tree/master/source/_posts/"
    click RepoContent "https://github.com/naturelr/blog/tree/master/source/_drafts/"
    click RepoContent "https://github.com/naturelr/blog/blob/master/source/**/*.md"
    click RepoContent "https://github.com/naturelr/blog/tree/master/source/images/"
    click RepoContent "https://github.com/naturelr/blog/tree/master/source/CNAME"
    click RepoContent "https://github.com/naturelr/blog/blob/master/_sidebar.md"
    click RepoDrawio "https://github.com/naturelr/blog/tree/master/drawio/"
    click RepoDrawio "https://github.com/naturelr/blog/blob/master/drawio/README.md"
    click RepoDrawio "https://github.com/naturelr/blog/blob/master/drawio/*.drawio"
    click RepoScripts "https://github.com/naturelr/blog/blob/master/deploy.sh"
    click RepoWorkflows "https://github.com/naturelr/blog/blob/master/.github/workflows/build-env-image.yaml"
    click RepoWorkflows "https://github.com/naturelr/blog/blob/master/.github/workflows/build-image.yaml"
    click RepoWorkflows "https://github.com/naturelr/blog/blob/master/.github/workflows/deploy.yaml"
    click RepoMeta "https://github.com/naturelr/blog/blob/master/README.md"
    click RepoMeta "https://github.com/naturelr/blog/tree/master/LICENSE"
    click RepoMeta "https://github.com/naturelr/blog/tree/master/source/LICENSE"

    %% Styles
    classDef localDev fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef repo fill:#ffffff,stroke:#333,stroke-width:1px
    classDef CI fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef BuildEnv fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef Hosting fill:#fff3cd,stroke:#856404,stroke-width:1px

    class Developer,DevNode,DevDocker localDev
    class RepoContent,RepoConfigs,RepoPackage,RepoScripts,RepoDrawio,RepoWorkflows,RepoMeta repo
    class WorkflowBuildEnv,WorkflowBuildSite,WorkflowDeploy CI
    class HexoGen,DocsifyBuild BuildEnv
    class PagesBlog,PagesDocs,DNS,CDN Hosting
```
