# phil-opp/blog_os architecture

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

- Interactive diagram: https://gitdiagram.com/phil-opp/blog_os
- Repository: https://github.com/phil-opp/blog_os

## Overview

##### Project type and purpose
- This is a **static documentation/blog site** („Blog OS“) that hosts the “Writing an OS in Rust” tutorial series. It’s not a traditional full-stack app but a **static site generator pipeline** combining Markdown content, templates, asset preprocessing, CI/CD, and Docker.

##### File‐structure breakdown
- Top level
- `.github/` – GitHub Actions workflows (build blog, link checks, scheduled rebuilds)
- `docker/` – Dockerfile + entrypoint for a reproducible build environment
- `scripts/` – convenience scripts (`merge.fish`, `push.fish`)
- `README.md`, licensing, CI config
- `blog/` folder (site source)
- `config.toml` – static site generator configuration
- `content/` – Markdown posts in multiple editions and translations
- `templates/` – HTML templates (base layouts, sections, macros)
- `sass/` – SCSS styles, per‐edition
- `requirements.txt` – Python dependencies for that hook
- CI/CD
- `.github/workflows/` – workflows for building the blog, checking links, scheduled nightly builds

##### Key README insights
- Each OS tutorial post lives in its own Git branch (`post-XX`) and is built on demand via `git worktree`.
- The site is generated from the `blog/` folder, then deployed (likely to GitHub Pages).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    Developer["Developers"]:::actor

    %% Repository and Source
    subgraph "GitHub Repository"
        RepoRoot["GitHub Repo"]:::code
    end

    subgraph "Source Code & Content"
        config["config.toml"]:::code
        before["before_build.py"]:::code
        req["requirements.txt"]:::code
        content["content/"]:::code
        diagrams["diagrams/"]:::code
        templates["templates/"]:::code
        sass["sass/"]:::code
        staticAssets["static/"]:::code
        typos["typos.toml"]:::code
    end

    %% CI Workflows
    subgraph "CI / GitHub Actions"
        CI_Build["blog.yml"]:::ci
        CI_Check["check-links.yml"]:::ci
        CI_Sched["scheduled-builds.yml"]:::ci
    end

    %% Docker Environment
    subgraph "Docker Build Environment"
        Dockerfile["Dockerfile"]:::build
        Entrypoint["entrypoint.sh"]:::build
        Aliases[".bash_aliases"]:::build
    end

    %% Generator and Scripts
    Generator["Static Site Generator"]:::build
    subgraph "Scripts"
        Merge["merge.fish"]:::scripts
        Push["push.fish"]:::scripts
    end

    %% Hosting and Users
    subgraph "Hosting / Deployment"
        Host["GitHub Pages / CDN"]:::deploy
    end
    EndUser["End Users (Browser)"]:::user

    %% External Services
    subgraph "External Services"
        Gitter["Gitter Chat"]:::ext
        Giscus["Giscus Comments"]:::ext
    end

    %% Connections
    Developer -->|"push"| RepoRoot
    RepoRoot --> config
    RepoRoot --> before
    RepoRoot --> req
    RepoRoot --> content
    RepoRoot --> diagrams
    RepoRoot --> templates
    RepoRoot --> sass
    RepoRoot --> staticAssets
    RepoRoot --> typos
    RepoRoot --> Merge
    RepoRoot --> Push
    RepoRoot --> CI_Build
    RepoRoot --> CI_Check
    RepoRoot --> CI_Sched
    RepoRoot --> Dockerfile
    RepoRoot --> Entrypoint
    RepoRoot --> Aliases

    CI_Build -->|"start container"| Dockerfile
    Dockerfile -->|"use entrypoint"| Entrypoint
    Entrypoint -->|"load aliases"| Aliases
    Dockerfile --> Generator
    before --> Generator
    config --> Generator
    content --> Generator
    templates --> Generator
    sass --> Generator
    staticAssets --> Generator

    Generator -->|"generate site"| Host
    CI_Build -->|"deploy"| Host
    EndUser -->|"request/serve"| Host

    Host -.->|embed| Giscus
    Host -.->|chat link| Gitter

    %% Click Events
    click CI_Build "https://github.com/phil-opp/blog_os/blob/main/.github/workflows/blog.yml"
    click CI_Check "https://github.com/phil-opp/blog_os/blob/main/.github/workflows/check-links.yml"
    click CI_Sched "https://github.com/phil-opp/blog_os/blob/main/.github/workflows/scheduled-builds.yml"
    click Dockerfile "https://github.com/phil-opp/blog_os/tree/main/docker/Dockerfile"
    click Entrypoint "https://github.com/phil-opp/blog_os/blob/main/docker/entrypoint.sh"
    click Aliases "https://github.com/phil-opp/blog_os/blob/main/docker/.bash_aliases"
    click Merge "https://github.com/phil-opp/blog_os/blob/main/scripts/merge.fish"
    click Push "https://github.com/phil-opp/blog_os/blob/main/scripts/push.fish"
    click config "https://github.com/phil-opp/blog_os/blob/main/blog/config.toml"
    click before "https://github.com/phil-opp/blog_os/blob/main/blog/before_build.py"
    click req "https://github.com/phil-opp/blog_os/blob/main/blog/requirements.txt"
    click content "https://github.com/phil-opp/blog_os/tree/main/blog/content/"
    click diagrams "https://github.com/phil-opp/blog_os/tree/main/blog/diagrams/"
    click templates "https://github.com/phil-opp/blog_os/tree/main/blog/templates/"
    click sass "https://github.com/phil-opp/blog_os/tree/main/blog/sass/"
    click staticAssets "https://github.com/phil-opp/blog_os/tree/main/blog/static/"
    click typos "https://github.com/phil-opp/blog_os/blob/main/blog/typos.toml"

    %% Styles
    classDef code fill:#AED6F1,stroke:#2980B9;
    classDef build fill:#ABEBC6,stroke:#27AE60;
    classDef ci fill:#ABEBC6,stroke:#1D8348;
    classDef scripts fill:#ABEBC6,stroke:#1D8348;
    classDef deploy fill:#FAD7A0,stroke:#D68910;
    classDef user fill:#E5E7E9,stroke:#566573;
    classDef ext fill:#E5E7E9,stroke:#616A6B;
    classDef actor fill:#ABEBC6,stroke:#1D8348;
```
