# lawrennd/old_talks architecture

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

- Interactive diagram: https://gitdiagram.com/lawrennd/old_talks
- Repository: https://github.com/lawrennd/old_talks

## Overview

##### Project type and purpose
- This is a static‐site “talks” generator for Neil Lawrence’s lecture and seminar materials.
- Source content is organized as Markdown + macros; build tools transform it into HTML (talk pages, slides, notebooks).

##### File structure
- Top‐level files:
- README.md – explains build dependencies (gpp, makemd)
- Makefiles, shell scripts, custom Python under `/maketalk`
- Content directories: each `_subject/` folder (e.g. `_ai`, `_data-science`, `_ml`, etc.) with:
- Markdown talk files
- `_config.yml` – subject‐specific configuration
- `includes/` – reusable fragments
- Build orchestration: multiple `make-*.mk`, `maketalk/` preprocessor modules

##### Key insights from README
- Uses `gpp` (generic preprocessor) + Python package `makemd` to interpret macros in Markdown.
- Build flow: Markdown → gpp macros → makemd → HTML, slides, notebooks

##### Main components
a. Source content layer
b. Preprocessing & build engine
- gpp preprocessor
- makemd Python package
- Custom scripts in `maketalk/`
- Makefiles and shell wrappers (`make-*.mk`, `recompile_lectures.sh`, etc.)
c. Output artifacts
- Generated HTML pages (talks, index.html)
- Slide decks under `slides/` (HTML, PDF, PPTX)
- Jupyter notebooks (`.ipynb`)
d. Deployment/Hosting
- Static web server (e.g., GitHub Pages, Nginx)

##### Relationships & interactions
- Developer edits source Markdown → triggers `make talk` (or top‐level `make-*`)
- Makefile calls `gpp` to expand macros → passes to `makemd` → invokes `maketalk` modules to produce intermediate Markdown/HTML
- Final static tree is served by web server

##### Architectural patterns & principles
- Content‐centric pipeline (Content → Transform → Serve)
- Separation of concerns:
- Content vs. build logic vs. runtime assets
- Layered build pipeline with small, reusable macros and includes

##### Technologies & frameworks
- gpp (generic preprocessor)
- Python + makemd
- GNU Make / shell scripts
- Reveal.js for slides
- Jupyter notebooks

##### Detailed elements
- Build orchestrator (Makefiles + `maketalk/`)
- Preprocessor & macro engine (gpp → makemd → custom Python modules)
- Output folders (`output/html/`, `slides/`, `notebooks/`)
- Hosting layer (static web server or CDN)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Content Layer
    subgraph "Source Content Layer"
        direction TB
        SC1["_ai"]:::source
        SC2["_data-science"]:::source
        SC3["_ml"]:::source
        SC4["_includes"]:::source
        SC1 --> SC1inc["_ai/includes"]:::source
        SC2 --> SC2inc["_data-science/includes"]:::source
        SC3 --> SC3inc["_ml/includes"]:::source
    end

    %% Build Orchestrator
    subgraph "Build Orchestrator"
        direction TB
        BF1["Makefile"]:::build
        BF2["make-talk.mk"]:::build
        BF3["make-slides.mk"]:::build
        BF4["make-markdown.mk"]:::build
        BF5["recompile_lectures.sh"]:::build
        BF1 --> BF2
        BF1 --> BF3
        BF1 --> BF4
        BF1 --> BF5
    end

    %% Build Engine & Preprocessor
    subgraph "Build Engine & Preprocessor"
        direction TB
        BE1["gpp Preprocessor"]:::build
        BE2["makemd Integration (mdpp.py)"]:::build
        BE3["maketalk Modules"]:::build
        BE4["slides/reveal.js"]:::asset
        BE5["scripts/ballworld"]:::asset
        BE1 --> BE2
        BE2 --> BE3
    end

    %% Output Artifacts
    subgraph "Output Artifacts"
        direction TB
        O1["slides/ (HTML, PDF, PPTX)"]:::output
        O2["_notebooks/"]:::output
        O3["_ai/notebooks/"]:::output
        O4["_data-science/notebooks/"]:::output
        O5["index.html & talk pages"]:::output
    end

    %% Hosting Layer
    subgraph "Deployment / Hosting"
        direction TB
        H["Static Web Server (GitHub Pages/Nginx)"]:::hosting
    end

    %% Data Flow
    SC1 -->|edit & commit| BF1
    SC2 -->|edit & commit| BF1
    SC3 -->|edit & commit| BF1
    SC4 -->|includes & macros| BF1

    BF2 -->|invoke gpp| BE1
    BF2 -->|bundle static assets| BE4
    BF2 -->|bundle static assets| BE5

    BE3 -->|make slides| O1
    BE3 -->|make notebooks| O2
    BE3 -->|generate HTML| O5

    BE4 -->|copy assets| O1
    BE5 -->|copy assets| O1

    O1 -->|serve content| H
    O5 -->|serve content| H

    %% Click Events
    click SC1 "https://github.com/lawrennd/old_talks/tree/gh-pages/_ai/"
    click SC2 "https://github.com/lawrennd/old_talks/tree/gh-pages/_data-science/"
    click SC3 "https://github.com/lawrennd/old_talks/tree/gh-pages/_ml/"
    click SC4 "https://github.com/lawrennd/old_talks/tree/gh-pages/_includes/"
    click SC1inc "https://github.com/lawrennd/old_talks/tree/gh-pages/_ai/includes/"
    click SC2inc "https://github.com/lawrennd/old_talks/tree/gh-pages/_data-science/includes/"
    click SC3inc "https://github.com/lawrennd/old_talks/tree/gh-pages/_ml/includes/"
    click BF1 "https://github.com/lawrennd/old_talks/tree/gh-pages/Makefile"
    click BF2 "https://github.com/lawrennd/old_talks/blob/gh-pages/make-talk.mk"
    click BF3 "https://github.com/lawrennd/old_talks/blob/gh-pages/make-slides.mk"
    click BF4 "https://github.com/lawrennd/old_talks/blob/gh-pages/make-markdown.mk"
    click BF5 "https://github.com/lawrennd/old_talks/blob/gh-pages/recompile_lectures.sh"
    click BE3 "https://github.com/lawrennd/old_talks/tree/gh-pages/maketalk/"
    click BE3 "https://github.com/lawrennd/old_talks/blob/gh-pages/maketalk/make_talk.py"
    click BE3 "https://github.com/lawrennd/old_talks/blob/gh-pages/maketalk/flags.py"
    click BE3 "https://github.com/lawrennd/old_talks/blob/gh-pages/maketalk/dependencies.py"
    click BE3 "https://github.com/lawrennd/old_talks/blob/gh-pages/maketalk/mdpp.py"
    click BE3 "https://github.com/lawrennd/old_talks/blob/gh-pages/maketalk/ndlml.py"
    click BE3 "https://github.com/lawrennd/old_talks/blob/gh-pages/maketalk/talkfield.py"
    click BE3 "https://github.com/lawrennd/old_talks/blob/gh-pages/maketalk/extractdate_talk.py"
    click SC4 "https://github.com/lawrennd/old_talks/blob/gh-pages/_includes/color-scheme.gpp"
    click BE4 "https://github.com/lawrennd/old_talks/tree/gh-pages/slides/reveal.js/"
    click BE5 "https://github.com/lawrennd/old_talks/tree/gh-pages/scripts/ballworld/"
    click O1 "https://github.com/lawrennd/old_talks/tree/gh-pages/slides/"
    click O2 "https://github.com/lawrennd/old_talks/tree/gh-pages/_notebooks/"
    click O3 "https://github.com/lawrennd/old_talks/tree/gh-pages/_ai/notebooks/"
    click O4 "https://github.com/lawrennd/old_talks/tree/gh-pages/_data-science/notebooks/"

    %% Styles
    classDef source fill:#D0E6FF,stroke:#3399FF,color:#000;
    classDef build fill:#D6FFD6,stroke:#33CC33,color:#000;
    classDef asset fill:#E6FFDA,stroke:#66CC00,color:#000;
    classDef output fill:#FFD8A8,stroke:#FF9933,color:#000;
    classDef hosting fill:#DDDDDD,stroke:#888888,color:#000;
```
