# jerry050512/typst-notes architecture

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

- Interactive diagram: https://gitdiagram.com/jerry050512/typst-notes
- Repository: https://github.com/jerry050512/typst-notes

## Overview

##### Project type and purpose
- This is a “documentation repository” of course notes written in Typst, with an automated CI/CD pipeline that compiles `.typ` files into PDF and publishes them to GitHub Releases.
- Key purpose: maintain, compile, and distribute PDF versions of notes for multiple courses.

##### File structure
- Top-level directories for each course:
- Circuits-and-Electronics
- Control-Engineering
- Microcomputer
- Pattern-Recoginition-and-Machine-Learning
- Signals-and-Systems
- Each course folder contains:
- `note.typ` (lecture notes)
- `practice.typ` (practice exercises)
- an `assets/` subfolder for images or supplementary files
- Repository-level:
- `.github/workflows/compile-and-release.yml` – GitHub Actions workflow definition
- `WORKFLOW.md` – detailed workflow documentation
- `test-workflow.sh` – helper script for scanning and building
- `template/` – shared Typst templates and configurations
- `README.md` – project overview, installation, and usage instructions

##### README for additional insights
- Explains how to compile manually with `typst compile input.typ [output.pdf]`
- Describes automated workflow:
- Automatically finds all `note.typ` and `practice.typ` files
- Names PDFs as `{directory}-{filetype}.pdf`
- Publishes to GitHub Releases on pushes to `main` or tagged commits
- Mentions external dependency: the Typst compiler and required Chinese fonts

##### Main components and interactions (
a. Components
1. Developer workstation (local environment)
2. GitHub repository (source of truth)
3. CI/CD pipeline – GitHub Actions runner
4. Build script (`test-workflow.sh`)
5. Typst compiler (installed on runner)
6. Source directories (per-course `.typ` files + assets)
7. Shared Typst template (`template/`)
8. Artifact store – GitHub Releases (PDF outputs)
9. Users (downloaders of PDFs)
b. Relationships / Data flow
- Developer commits `.typ` files → pushes to GitHub
- Push triggers GitHub Actions workflow
- Runner executes `compile-and-release.yml` → calls `test-workflow.sh`
- Script scans each course folder for `.typ` files and invokes Typst compiler with the template
- Generates PDFs named by `{course}-{note/practice}.pdf`
- Uploads artifacts to GitHub Releases (draft or new version depending on tag)
- Users retrieve compiled PDFs from Releases
c. Architectural patterns
- CI/CD pipeline (automation)
- Convention-over-configuration: folder naming and file patterns drive script logic
- Single repository for both source and deployment artifacts (via GitHub Releases)
d. Key technologies
- Typst (document compiler)
- GitHub Actions (CI/CD)
- Bash (shell script)
- GitHub Releases (artifact hosting)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Layer
    subgraph "Source Layer"
        direction TB
        Repo["GitHub Repository"]:::external
        subgraph "Source Directories"
            direction TB
            CE["Circuits-and-Electronics/"]:::source
            Ctrl["Control-Engineering/"]:::source
            Micro["Microcomputer/"]:::source
            PRML["Pattern-Recoginition-and-Machine-Learning/"]:::source
            SS["Signals-and-Systems/"]:::source
        end
        subgraph "Templates"
            direction TB
            CompTyp["components.typ"]:::source
            ConfTyp["conf.typ"]:::source
        end
        README["README.md"]:::source
        WORKFLOW_DOC["WORKFLOW.md"]:::source
        WorkflowFile[".github/workflows/compile-and-release.yml"]:::source
        ScriptSrc["test-workflow.sh"]:::source
    end

    %% Build Layer
    subgraph "Build Layer"
        direction TB
        GH_ACTIONS["GitHub Actions Runner"]:::process
        CIWF["CI/CD Workflow"]:::process
        BuildScript["Build Script"]:::process
        Typst["Typst Compiler"]:::process
    end

    %% Artifact Layer
    subgraph "Artifact Layer"
        direction TB
        PDFs["PDF Artifacts"]:::output
        Releases["GitHub Releases"]:::output
    end

    %% External Entities
    Dev["Developer Workstation"]:::external
    User["Users"]:::external

    %% Connections
    Dev -->|"push commit"| Repo
    Dev -->|"manual compile"| Typst
    Repo -->|"on push or tag"| CIWF
    CIWF -->|"runs on"| GH_ACTIONS
    GH_ACTIONS -->|"reads workflow"| WorkflowFile
    GH_ACTIONS -->|"executes"| BuildScript
    BuildScript -->|"scans source"| CE
    BuildScript -->|"scans source"| Ctrl
    BuildScript -->|"scans source"| Micro
    BuildScript -->|"scans source"| PRML
    BuildScript -->|"scans source"| SS
    BuildScript -->|"uses templates"| CompTyp
    BuildScript -->|"uses templates"| ConfTyp
    BuildScript -->|"invokes"| Typst
    Typst -->|"generates"| PDFs
    PDFs -->|"upload"| Releases
    Releases -->|"download"| User

    %% Click Events
    click WorkflowFile "https://github.com/jerry050512/typst-notes/blob/main/.github/workflows/compile-and-release.yml"
    click WORKFLOW_DOC "https://github.com/jerry050512/typst-notes/blob/main/WORKFLOW.md"
    click ScriptSrc "https://github.com/jerry050512/typst-notes/blob/main/test-workflow.sh"
    click CompTyp "https://github.com/jerry050512/typst-notes/blob/main/template/components.typ"
    click ConfTyp "https://github.com/jerry050512/typst-notes/blob/main/template/conf.typ"
    click CE "https://github.com/jerry050512/typst-notes/tree/main/Circuits-and-Electronics/"
    click Ctrl "https://github.com/jerry050512/typst-notes/tree/main/Control-Engineering/"
    click Micro "https://github.com/jerry050512/typst-notes/tree/main/Microcomputer/"
    click PRML "https://github.com/jerry050512/typst-notes/tree/main/Pattern-Recoginition-and-Machine-Learning/"
    click SS "https://github.com/jerry050512/typst-notes/tree/main/Signals-and-Systems/"
    click README "https://github.com/jerry050512/typst-notes/blob/main/README.md"

    %% Styles
    classDef source fill:#ADD8E6,stroke:#000;
    classDef process fill:#90EE90,stroke:#000;
    classDef output fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
