# shingzhanho/hku-notes architecture

> Architecture diagram of the GitHub repository shingzhanho/hku-notes, 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/shingzhanho/hku-notes
- Repository: https://github.com/shingzhanho/hku-notes

## Overview

##### Project type and purpose
- This is neither a classic frontend/backend web-app nor a microservices system. It’s a static-site generation pipeline for LaTeX-based course notes, managed as an open-source tool with CI/CD.
- Purpose: store LaTeX/Markdown notes in Git, automatically compile them into a static documentation site via GitHub Actions, and publish (e.g., to GitHub Pages).

##### File structure
- Top-level directories:
- `.github/workflows` → CI/CD pipeline definitions
- `build/` → Python-based build orchestration, metadata extraction utilities (`mttools`), helper scripts, requirement lists
- `src/` → Source content: LaTeX and Markdown for each course
- `site/` → Generated static site (`mkdocs.yml` + `docs/` folder)
- Key patterns:
- ETL/pipeline style: source → transform → site output
- Custom Python package (`build/mttools`) for metadata extraction
- Use of MkDocs (and possibly custom MkDocs Material theme) to convert Markdown into HTML
- CI/CD config (`.github/workflows/build-and-deploy.yml`) triggers `build/` scripts and publishes `site/` output.

##### README for additional insights
- Confirms: personal revision resource manager, compilation + distribution online via GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Repository
    Repo["Source Repository (Git)"]:::repo

    %% CI/CD
    CI["GitHub Actions\n(CI/CD Orchestrator)"]:::ci

    %% Build Environment
    Env["Build Environment"]:::ci

    %% Environment Configuration Files
    apt["apt-packages.txt"]:::config
    req1["mkdocs-material-pkgs.txt"]:::config
    req2["python-minted-pkgs.txt"]:::config

    %% Source Content
    src["src/\n(LaTeX & Markdown)"]:::data

    %% Build Scripts & Tools
    subgraph "Build Scripts & Pipeline Orchestration"
        direction TB
        configure["configure-env-vars.sh"]:::tool
        getMeta["get-metadata.py"]:::tool
        resolve["resolve-targets.py"]:::tool
        genPage["generate-pages.py"]:::tool
        buildTargets["build-targets.txt"]:::tool
    end

    %% Custom Metadata Extraction Library
    subgraph "mttools Library"
        direction TB
        mt_init["__init__.py"]:::library
        mt_metadata["metadata.py"]:::library
        mt_base_parser["metadata_base_parser.py"]:::library
        mt_reader["metadata_reader.py"]:::library
        mt_v1["metadata_v1_parser.py"]:::library
    end

    %% MkDocs Configuration & Generator
    mkdocsCfg["site/mkdocs.yml"]:::config
    MkDocs["MkDocs Static Site Generator"]:::transform

    %% Site Output
    subgraph "Generated Static Site Output"
        direction TB
        siteDocs["site/docs/"]:::output
        downloads["site/docs/downloads/"]:::output
        extraCss["site/docs/stylesheets/extra.css"]:::output
    end

    %% Deployment
    GitHubPages["GitHub Pages\n(Deployment Target)"]:::deploy

    %% Flow
    Repo -->|"push triggers"| CI
    CI -->|"provisions"| Env
    Env -->|installs| apt
    Env -->|installs| req1
    Env -->|installs| req2
    Env -->|"runs"| configure
    Env -->|"runs"| getMeta
    Env -->|"runs"| resolve
    Env -->|"runs"| genPage
    Env -->|"reads"| buildTargets

    src -->|"inputs to"| getMeta
    mt_init & mt_metadata & mt_base_parser & mt_reader & mt_v1 -->|"library used by"| getMeta
    getMeta -->|"metadata for"| resolve
    resolve -->|"targets for"| genPage
    genPage -->|"pages to"| MkDocs
    mkdocsCfg -->|"configures"| MkDocs

    MkDocs -->|"generates"| siteDocs
    MkDocs -->|"generates"| downloads
    MkDocs -->|"applies stylesheet"| extraCss
    siteDocs -->|"deploys to"| GitHubPages

    %% Click Events
    click Repo "https://github.com/shingzhanho/hku-notes/blob/master/."
    click CI "https://github.com/shingzhanho/hku-notes/blob/master/.github/workflows/build-and-deploy.yml"
    click apt "https://github.com/shingzhanho/hku-notes/blob/master/build/apt-packages.txt"
    click req1 "https://github.com/shingzhanho/hku-notes/blob/master/build/python-requirement-lists/mkdocs-material-pkgs.txt"
    click req2 "https://github.com/shingzhanho/hku-notes/blob/master/build/python-requirement-lists/python-minted-pkgs.txt"
    click configure "https://github.com/shingzhanho/hku-notes/blob/master/build/configure-env-vars.sh"
    click getMeta "https://github.com/shingzhanho/hku-notes/blob/master/build/get-metadata.py"
    click resolve "https://github.com/shingzhanho/hku-notes/blob/master/build/resolve-targets.py"
    click genPage "https://github.com/shingzhanho/hku-notes/blob/master/build/generate-pages.py"
    click buildTargets "https://github.com/shingzhanho/hku-notes/blob/master/build/build-targets.txt"
    click mt_init "https://github.com/shingzhanho/hku-notes/blob/master/build/mttools/__init__.py"
    click mt_metadata "https://github.com/shingzhanho/hku-notes/blob/master/build/mttools/metadata.py"
    click mt_base_parser "https://github.com/shingzhanho/hku-notes/blob/master/build/mttools/readers/metadata_base_parser.py"
    click mt_reader "https://github.com/shingzhanho/hku-notes/blob/master/build/mttools/readers/metadata_reader.py"
    click mt_v1 "https://github.com/shingzhanho/hku-notes/blob/master/build/mttools/readers/metadata_v1_parser.py"
    click src "https://github.com/shingzhanho/hku-notes/tree/master/src/"
    click mkdocsCfg "https://github.com/shingzhanho/hku-notes/blob/master/site/mkdocs.yml"
    click siteDocs "https://github.com/shingzhanho/hku-notes/tree/master/site/docs/"
    click downloads "https://github.com/shingzhanho/hku-notes/tree/master/site/docs/downloads/"
    click extraCss "https://github.com/shingzhanho/hku-notes/blob/master/site/docs/stylesheets/extra.css"
    click GitHubPages "https://github.com/shingzhanho/hku-notes/tree/master/site/"

    %% Styles
    classDef repo fill:#D0E8FF,stroke:#00529B,color:#00529B;
    classDef ci fill:#E6FFE6,stroke:#2E7D32,color:#2E7D32;
    classDef config fill:#FFF4E5,stroke:#E65100,color:#E65100;
    classDef data fill:#E8EAF6,stroke:#3F51B5,color:#3F51B5;
    classDef tool fill:#FFF0F5,stroke:#C2185B,color:#C2185B;
    classDef library fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A;
    classDef transform fill:#FFF3E0,stroke:#EF6C00,color:#EF6C00;
    classDef output fill:#FCE4EC,stroke:#AD1457,color:#AD1457;
    classDef deploy fill:#EDE7F6,stroke:#5E35B1,color:#5E35B1;
```
