# brettchalupa/projectbook architecture

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

- Interactive diagram: https://gitdiagram.com/brettchalupa/projectbook
- Repository: https://github.com/brettchalupa/projectbook

## Overview

##### Main Components
- Content Repository (Markdown Files):
- Various directories under src (e.g., command-line-interfaces, games, general-graphical-apps, libraries, web-apps, web-components, websites). These contain the chapters, introductions, and supplemental materials that form the body of the book.
- mdBook Engine:
- This is the build system that converts Markdown content into a static website. It processes the book’s configuration (book.toml) and the SUMMARY.md for navigation/control flow.
- Development & Build Tools:
- Rust and Cargo (as mdBook is installed via Cargo).
- Build scripts or the GitHub Action deployed workflow (in .github/workflows) that automatically builds and deploys the static site when code is pushed.
- Static Hosting Environment:
- GitHub Pages (with configurations like CNAME files and .nojekyll files in the src folder).
- Theme/Template Configuration:
- The custom theme files (under the “theme” directory) that define the look and feel of the published site.
- Deployment Pipeline:
- Continuous integration via GitHub Actions (gh-pages.yml) that handles building the book and publishing it to GitHub Pages.

##### Relationships & Interactions
- The Markdown content (organized into multiple directories) is the source input.
- mdBook consumes these files (guided by SUMMARY.md and book.toml) to generate a static HTML website.
- The GitHub Action workflow monitors changes on the main branch; once changes are pushed, the workflow triggers the mdBook build process and deploys the updated site to GitHub Pages.
- The theme files are referenced by mdBook during the build to ensure consistent styling.
- The deployed site then serves these static pages to end-users (learners and contributors).

##### Architectural Patterns & Design Principles
- Separation of Concerns: Content management (Markdown files) is distinct from the build process (mdBook) and the deployment pipeline (GitHub Actions).
- Static Site Generation: Promotes scalability and simplicity by pre-rendering content.
- Modular Organization: Each category of project ideas (CLI apps, games, libraries, etc.) is separated into its directory structure, which reflects a compartmentalized approach.
- Automation: Use of GitHub workflows ensures continuous integration and deployment, reducing manual intervention.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content Repository Subgraph
    subgraph "Content Repository - Project Ideas Repository"
        CMD["Command-Line Interfaces"]:::content
        GAMES["Games"]:::content
        GAPP["Graphical Apps"]:::content
        LIBS["Libraries"]:::content
        WEBAPPS["Web Apps"]:::content
        WEBCOMP["Web Components"]:::content
        WEBS["Websites"]:::content
    end

    %% Static Site Generation Subgraph
    subgraph "Static Site Generation"
        MD["mdBook Engine (Static Site Generator)"]:::process
        BT["book.toml (Configuration)"]:::config
        STN["src/SUMMARY.md (Navigation)"]:::config
        THEME["Custom Theme (Handlebars)"]:::template
        RUST["Rust & Cargo (Build Tools)"]:::tool
    end

    %% CI/CD Pipeline Node
    PIPELINE["CI/CD Pipeline (GitHub Actions)"]:::ci

    %% Static Hosting Environment
    HOSTING["Static Hosting (GitHub Pages)"]:::hosting
    subgraph "Hosting Configurations"
        NOJEK[".nojekyll File"]:::hosting
        CNAME_SRC["CNAME in src"]:::hosting
        CNAME["CNAME File"]:::hosting
    end

    %% Connections from Content Repository to mdBook Engine
    CMD --> MD
    GAMES --> MD
    GAPP --> MD
    LIBS --> MD
    WEBAPPS --> MD
    WEBCOMP --> MD
    WEBS --> MD

    %% Connections from configuration files to mdBook Engine
    BT --> MD
    STN --> MD

    %% Connections from Theme and Tools to mdBook Engine
    THEME --> MD
    RUST --> MD

    %% Output from mdBook Engine to CI/CD Pipeline
    MD --> PIPELINE

    %% Deployment from CI/CD Pipeline to Static Hosting
    PIPELINE --> HOSTING

    %% Hosting Configuration files feed into Static Hosting
    NOJEK --> HOSTING
    CNAME_SRC --> HOSTING
    CNAME --> HOSTING

    %% Click Events for Components
    click CMD "https://github.com/brettchalupa/projectbook/tree/main/src/command-line-interfaces"
    click GAMES "https://github.com/brettchalupa/projectbook/tree/main/src/games"
    click GAPP "https://github.com/brettchalupa/projectbook/tree/main/src/general-graphical-apps"
    click LIBS "https://github.com/brettchalupa/projectbook/tree/main/src/libraries"
    click WEBAPPS "https://github.com/brettchalupa/projectbook/tree/main/src/web-apps"
    click WEBCOMP "https://github.com/brettchalupa/projectbook/tree/main/src/web-components"
    click WEBS "https://github.com/brettchalupa/projectbook/tree/main/src/websites"
    click BT "https://github.com/brettchalupa/projectbook/blob/main/book.toml"
    click STN "https://github.com/brettchalupa/projectbook/blob/main/src/SUMMARY.md"
    click PIPELINE "https://github.com/brettchalupa/projectbook/blob/main/.github/workflows/gh-pages.yml"
    click THEME "https://github.com/brettchalupa/projectbook/tree/main/theme"
    click NOJEK "https://github.com/brettchalupa/projectbook/blob/main/src/.nojekyll"
    click CNAME_SRC "https://github.com/brettchalupa/projectbook/tree/main/src/CNAME"
    click CNAME "https://github.com/brettchalupa/projectbook/tree/main/CNAME"

    %% Styles
    classDef content fill:#b3cde0,stroke:#03396c,stroke-width:2px;
    classDef process fill:#ccebc5,stroke:#006400,stroke-width:2px;
    classDef config fill:#decbe4,stroke:#6a51a3,stroke-width:2px;
    classDef template fill:#fed9a6,stroke:#ff8c00,stroke-width:2px;
    classDef tool fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef ci fill:#fbb4ae,stroke:#d11149,stroke-width:2px;
    classDef hosting fill:#b0b0b0,stroke:#666666,stroke-width:2px;
```
