# yousefalqafaz/github-slideshow architecture

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

- Interactive diagram: https://gitdiagram.com/yousefalqafaz/github-slideshow
- Repository: https://github.com/yousefalqafaz/github-slideshow

## Overview

##### Project type and purpose
- This is a *static-site presentation* repository built on Jekyll and Reveal.js, used by the GitHub Learning Lab bot to teach Git/GitHub concepts via an interactive slide deck.

##### File structure
- Top-level files:
- Gemfile/Gemfile.lock → Ruby dependencies (Jekyll).
- package-lock.json, node_modules → JavaScript dependencies (Reveal.js).
- _config.yml → Jekyll configuration.
- index.html, _layouts/, _includes/, _posts/ → Jekyll’s typical directory layout for templating and content.
- script/ → custom CLI scripts for setup, build (cibuild), serve, and stage.
- Notice the use of two build toolchains: Ruby/Jekyll for site generation, and Node/Reveal.js for slides.

##### README for additional insights
- The purpose is to serve as a GitHub Learning Lab course.
- It leverages the open-source Reveal.js project.
- Interaction with the “Learning Lab bot” occurs through GitHub Issues/PRs (external service).

##### Main components
a. Source Layer (Developer machine & Git repository)
- Markdown posts (_posts/*.md), HTML layouts/includes, configuration files.
- Gemfile, package-lock.json.
b. Build Layer (CI / Local build)
- Jekyll engine (Ruby) reads source + _config.yml → static HTML.
- Reveal.js (Node) assets integrated into the layout → slide deck HTML/CSS/JS.
- Custom scripts (script/cibuild, script/server, script/stage) orchestrate build, test, and staging.
c. Hosting Layer
- GitHub Pages (or another static host) serves the generated files.
d. Client Layer
- Web browser loads index.html → Reveal.js presents slides.
e. External Service
- GitHub Learning Lab bot interacts via GitHub API (issues/PR comments).

##### Relationships and data flows
1. Developer edits source → commits to Git → pushes to GitHub.
2. On push, CI (or script/cibuild) runs:
- `bundle install` → Jekyll build → produces `_site/`.
- `npm install` / `npm run build` → bundles Reveal.js assets.
3. script/stage or GitHub Pages takes `_site/` → deploys to production.
4. End user’s browser requests slides → fetches static files from hosting → Reveal.js renders.
5. Learning Lab bot monitors repository via GitHub API → posts issues/PR comments → user interacts.

##### Architectural patterns and design principles
- Static Site Generator (SSG) pattern.
- Clear separation of concerns:
- Content (Markdown) vs. Presentation (layouts/includes).
- Build toolchains isolated in scripts.
- Infrastructure as code: build and deploy scripts version-controlled.

##### Essential elements
- Don’t omit the dual build toolchains (Ruby/Jekyll + Node/Reveal.js).
- Content directory structure feeding into Jekyll.
- Custom scripts orchestrating CI steps.
- Learning Lab bot as an external service to reflect the interactive teaching aspect.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Layer
    subgraph "Source Layer" 
        direction TB
        SRC_MD["_posts/"]:::source
        SRC_LAYOUTS["_layouts/"]:::source
        SRC_INCLUDES["_includes/"]:::source
        SRC_CONFIG["_config.yml"]:::source
        SRC_RUBY["Gemfile & Gemfile.lock"]:::source
        SRC_NODE["package-lock.json & node_modules/"]:::source
        SRC_INDEX["index.html"]:::source
    end

    %% Build Layer
    subgraph "Build Layer" 
        direction TB
        SETUP["script/setup"]:::build
        CIBUILD["script/cibuild"]:::build
        SERVER["script/server"]:::build
        STAGE["script/stage"]:::build
        JEKYLL["Jekyll Engine (Ruby)"]:::build
        REVEAL["Reveal.js Bundler (Node)"]:::build
    end

    %% Hosting Layer
    subgraph "Hosting Layer" 
        direction TB
        HOST["GitHub Pages (_site/)"]:::hosting
    end

    %% Client Layer
    subgraph "Client Browser" 
        direction TB
        BROWSER["Web Browser"]:::client
    end

    %% External Bot
    subgraph "External Service" 
        direction TB
        BOT["GitHub Learning Lab Bot"]:::external
    end

    %% Connections
    SRC_MD -->|"git push"| CIBUILD
    SRC_LAYOUTS --> CIBUILD
    SRC_INCLUDES --> CIBUILD
    SRC_CONFIG --> CIBUILD
    SRC_RUBY --> CIBUILD
    SRC_NODE --> CIBUILD
    SRC_INDEX --> CIBUILD

    CIBUILD -->|"bundle exec jekyll build"| JEKYLL
    CIBUILD -->|"npm install & npm run build"| REVEAL
    JEKYLL --> HOST
    REVEAL --> HOST

    HOST -->|"HTTPS GET"| BROWSER
    BOT -->|"<GitHub API>"| CIBUILD
    BOT -->|"<GitHub API>"| SRC_MD
    BOT -->|"<GitHub API>"| SRC_INDEX

    %% Click Events
    click SRC_MD "https://github.com/yousefalqafaz/github-slideshow/tree/master/_posts/"
    click SRC_LAYOUTS "https://github.com/yousefalqafaz/github-slideshow/tree/master/_layouts/"
    click SRC_INCLUDES "https://github.com/yousefalqafaz/github-slideshow/tree/master/_includes/"
    click SRC_CONFIG "https://github.com/yousefalqafaz/github-slideshow/blob/master/_config.yml"
    click SRC_RUBY "https://github.com/yousefalqafaz/github-slideshow/tree/master/Gemfile"
    click SRC_RUBY "https://github.com/yousefalqafaz/github-slideshow/blob/master/Gemfile.lock"
    click SRC_NODE "https://github.com/yousefalqafaz/github-slideshow/blob/master/package-lock.json"
    click SRC_NODE "https://github.com/yousefalqafaz/github-slideshow/tree/master/node_modules/"
    click SRC_INDEX "https://github.com/yousefalqafaz/github-slideshow/blob/master/index.html"
    click SETUP "https://github.com/yousefalqafaz/github-slideshow/tree/master/script/setup"
    click CIBUILD "https://github.com/yousefalqafaz/github-slideshow/tree/master/script/cibuild"
    click SERVER "https://github.com/yousefalqafaz/github-slideshow/tree/master/script/server"
    click STAGE "https://github.com/yousefalqafaz/github-slideshow/tree/master/script/stage"

    %% Styles
    classDef source fill:#e6ffed,stroke:#2ca02c,stroke-width:2px
    classDef build fill:#e7f0fd,stroke:#1f77b4,stroke-width:2px
    classDef hosting fill:#fff4e6,stroke:#ff7f0e,stroke-width:2px
    classDef client fill:#f0f0f0,stroke:#7f7f7f,stroke-width:2px
    classDef external fill:#f3e6ff,stroke:#9467bd,stroke-width:2px
```
