# weareoutman/plain-blog architecture

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

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

## Overview

##### Main Components Identification
- CLI/Entry Point – Represent the command-line interface that triggers the build process. In the file tree, this is found in the plain-blog/bin folder (plain-blog.js).
- SiteContext (defines the context/environment for site generation)
- Core processing modules (e.g., the job orchestration in job.jsx)
- Utility modules (under plain-blog/lib/utils) that provide ancillary functions like metadata extraction, hashing, URL handling, image processing, and CSS transformation.
- Loaders Pipeline – This project uses multiple custom module loaders to process different file types:
- CSS Loader (plain-blog/lib/loaders/css-loader)
- File Loader (plain-blog/lib/loaders/file-loader)
- JSX Loader (plain-blog/lib/loaders/jsx-loader)
- MDX Loader (plain-blog/lib/loaders/mdx-loader), including additional reprocessing steps (e.g., toc extraction, image handling, link rewriting)
- Raw Loader (plain-blog/lib/loaders/raw-loader)
How these loaders plug into the Node.js module hooks mechanism.
- Templates – Show the rendering components. There are two sets of templates:
- The core templates located under plain-blog/templates (Article.jsx, Footer.jsx, Header.jsx, Home.jsx, Page.jsx)
- The website’s own components and styling (website/src/components, website/src/styles.css) along with content files in the website/content directory.
- Website/Content Repository – Represent the external content source. This is managed under the website directory and includes:
- The “content” folder (with markdown and MDX blog posts and pages)
- Configuration files (e.g., plain.config.js in the website root) and static assets (website/assets).

##### Relationships and Interactions
- The CLI component (plain-blog/bin/plain-blog.js) acts as the entry point and invokes the core library functions.
- The core library sets up Node.js module hooks, registering the various custom loaders to process the specific file types during the build.
- The loaders intercept module imports during runtime/build time and transform content formats (JSX/MDX/Markdown/CSS/Raw files) to the appropriate output.
- Utility functions support the loaders and transformation steps.
- Once the content is processed, the templates are used to render the final output HTML.
- The website folder provides the end-user content and configurations, which are fed into the core engine to generate the static blog.

##### Architectural Patterns and Design Principles
- Modular Loader Pipeline – Separates file type processing by isolating custom loaders in their own subdirectories. This provides flexibility and clarity in extending or modifying the build process.
- Separation of Concerns – Clean split between the core engine that handles build orchestration and the website-specific content and theming.
- Zero Client-Side JavaScript Philosophy – Emphasize that the architectural decisions are based on emitting static HTML/CSS without bundling client scripts, reducing client complexity.
- Use of Node.js Module Hooks – A modern approach to intercept module loading, making the system efficient at build time.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Plain Blog Engine"
        CLI["CLI Entry Point"]:::processing

        subgraph "Core Library"
            SCT["SiteContext (build config)"]:::processing
            JOB["Job Processing"]:::processing
            UTILS["Utility Modules"]:::processing
        end

        subgraph "Loaders Pipeline"
            CSS["CSS Loader"]:::processing
            FILE["File Loader"]:::processing
            JSX["JSX Loader"]:::processing
            MDX["MDX Loader (reprocess_toc_imgs_links)"]:::processing
            RAW["Raw Loader"]:::processing
        end
    end

    subgraph "Static Site Output"
        subgraph "Templates & Renderer"
            CORE_TEMPLATES["Core Templates (Article,Footer,Header,Home,Page)"]:::rendering
            WEBSITE_COMPONENTS["Website Components"]:::rendering
            STYLES["Styles"]:::rendering
        end
        subgraph "Content Repository"
            CONTENT["Content (MD/MDX posts)"]:::storage
            CONFIG["Configuration Files"]:::storage
            ASSETS["Assets"]:::storage
        end
    end

    %% Relationships and Data Flow
    CLI -->|"initiates"| SCT
    CLI -->|"initiates"| JOB

    CONTENT -->|"supplies"| UTILS
    CONFIG -->|"supplies"| UTILS
    ASSETS -->|"supplies"| UTILS

    UTILS -->|"registers_loader"| CSS
    UTILS --> FILE
    UTILS --> JSX
    UTILS --> MDX
    UTILS --> RAW

    CSS -->|"transforms"| CORE_TEMPLATES
    FILE --> CORE_TEMPLATES
    JSX --> CORE_TEMPLATES
    MDX --> CORE_TEMPLATES
    RAW --> CORE_TEMPLATES

    UTILS -->|"passes_config"| CORE_TEMPLATES
    CORE_TEMPLATES --> WEBSITE_COMPONENTS
    CORE_TEMPLATES --> STYLES

    classDef processing stroke:#000,fill:#ADD8E6,stroke-width:2px,color:#000;
    classDef rendering stroke:#000,fill:#90EE90,stroke-width:2px,color:#000;
    classDef storage stroke:#000,fill:#FFFF99,stroke-width:2px,color:#000;

    %% Click Events
    click CLI "https://github.com/weareoutman/plain-blog/blob/main/plain-blog/bin/plain-blog.js"
    click SCT "https://github.com/weareoutman/plain-blog/blob/main/plain-blog/lib/SiteContext.js"
    click JOB "https://github.com/weareoutman/plain-blog/blob/main/plain-blog/lib/job.jsx"
    click UTILS "https://github.com/weareoutman/plain-blog/tree/main/plain-blog/lib/utils"
    click CSS "https://github.com/weareoutman/plain-blog/tree/main/plain-blog/lib/loaders/css-loader"
    click FILE "https://github.com/weareoutman/plain-blog/tree/main/plain-blog/lib/loaders/file-loader"
    click JSX "https://github.com/weareoutman/plain-blog/tree/main/plain-blog/lib/loaders/jsx-loader"
    click MDX "https://github.com/weareoutman/plain-blog/tree/main/plain-blog/lib/loaders/mdx-loader"
    click RAW "https://github.com/weareoutman/plain-blog/tree/main/plain-blog/lib/loaders/raw-loader"
    click CORE_TEMPLATES "https://github.com/weareoutman/plain-blog/tree/main/plain-blog/templates"
    click WEBSITE_COMPONENTS "https://github.com/weareoutman/plain-blog/tree/main/website/src/components"
    click STYLES "https://github.com/weareoutman/plain-blog/blob/main/website/src/styles.css"
    click CONTENT "https://github.com/weareoutman/plain-blog/tree/main/website/content"
    click CONFIG "https://github.com/weareoutman/plain-blog/blob/main/website/plain.config.js"
    click ASSETS "https://github.com/weareoutman/plain-blog/tree/main/website/assets"
```
