# munuchapterhkn/eta-kappa-notes architecture

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

- Interactive diagram: https://gitdiagram.com/munuchapterhkn/eta-kappa-notes
- Repository: https://github.com/munuchapterhkn/eta-kappa-notes

## Overview

##### Project type and purpose
- Eta Kappa Notes is neither a web application nor a microservice-based system. It is a static‐content generation pipeline for academic notes, supporting two document composition engines (LaTeX and Typst) plus Python‐driven figure generation. The goal is to standardize and automate the production of high-quality PDFs (and related assets) from source notes and templates.

##### File structure
- Top-level directories:
- notes/ – course material in .tex (.latex) plus resource subfolders
- guide/ – tutorial and starter docs split into guide/latex/ and guide/typst/
- lib/ – shared templates (LaTeX .cls/.tex, Typst .typ) and build configurations
- Key files:
- pyproject.toml & requirements.txt – Python scripts dependencies
- typst.toml – Typst configuration
- .vscode/settings.json (implied) & latexmkrc – build tool settings
- Patterns:
- “content + template → compiler → output” for both LaTeX and Typst
- Python scripts in guide/latex/res/py generate figures used in notes and guide

##### README for additional insights
- Supported backends: LaTeX (via latexmk, TeX Live, Inkscape) and Typst (v0.12+)
- Python environment for programmatic figures
- Contribution workflow revolves around editing source notes/templates and rebuilding

a. Main components
1) Content Repositories:
– notes/ (course .tex + assets)
– guide/ (tutorial source in .tex and .typ, plus embedded Python scripts)
2) Template Library:
– lib/latex (HKNdocument.cls, preamble/postamble, latexmkrc)
– lib/typst (funcs.typ, template.typ, typst.toml)
3) Build Engines:
– LaTeX Engine (latexmk → pdflatex/xelatex + Inkscape)
– Typst Compiler
– Python Runner (virtualenv, scripts in guide/latex/res/py)
4) Shared Resources:
– resources/imgs (logos, ideogram)
5) Outputs:
– PDF artifacts: notes PDFs, guide.pdf
6) Developers’ Tools:
– VS Code + LaTeX Workshop extension
– CI pipeline (optional)

b. Relationships and data flows
– Content Repositories and Template Library feed into Build Engines.
– Python Runner may generate intermediate assets (SVGs, PDFs) placed into resources or directly referenced.
– Build Engines consume both content and templates, invoking external tools (Inkscape) as needed.
– Outputs are deposited in the file tree alongside source or into designated output folders.

c. Architectural patterns & design principles
– Pipeline pattern (“read sources → transform → write outputs”)
– Configuration-as-code for build tools (latexmkrc, typst.toml)
– Separation of concerns: content vs. presentation (templates) vs. tooling
– Reproducibility: versioned tool versions, virtual environments

d. Key technologies & frameworks
– LaTeX (TeX Live distribution, latexmk, Inkscape for SVG→PDF)
– Typst (v0.12+, typst.toml)
– Python 3.x + pip dependencies (requirements.txt)
– VS Code + LaTeX Workshop for local builds

- Blue for source directories (notes/, guide/)
- Green for template libraries (lib/)
- Orange for build engines (LaTeX, Typst, Python)
- Gray for external tools (Inkscape, virtualenv)
- Purple for outputs (PDFs, images)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Content Repositories
    subgraph "Content Repositories"
        CR1["notes/"]:::source
        CR2["guide/latex/"]:::source
        CR3["guide/typst/"]:::source
    end

    %% Template Library
    subgraph "Template Library"
        TL1["lib/latex/"]:::template
        LCLS["HKNdocument.cls"]:::template
        PRE["_preamble.tex"]:::template
        POST["_postamble.tex"]:::template
        CC["cclicense.tex"]:::template
        LMKRC["latexmkrc"]:::template

        TL2["lib/typst/"]:::template
        FUNCS["funcs.typ"]:::template
        TEMPLT["template.typ"]:::template
    end

    %% Build Engines
    subgraph "Build Engines"
        BE1["LaTeX Engine\n(latexmk)"]:::engine
        BE2["Typst Compiler"]:::engine
        BE3["Python Runner"]:::engine
    end

    %% External Tools
    subgraph "External Tools"
        ET1["Inkscape"]:::external
        ET2["virtualenv"]:::external
    end

    %% Configuration Files
    subgraph "Configuration"
        CF1["latexmkrc"]:::config
        CF2["typst.toml"]:::config
        CF3["pyproject.toml"]:::config
        CF4["requirements.txt"]:::config
        CF5[".vscode/settings.json"]:::config
    end

    %% Shared Resources
    subgraph "Shared Resources"
        SR1["resources/imgs/"]:::resource
        SR2["guide/latex/res/svg/"]:::resource
        SR3["notes/*/res/svg/"]:::resource
    end

    %% Outputs
    subgraph "Outputs"
        O1["notes PDF"]:::output
        O2["guide PDF"]:::output
        O3["SVG/PNG diagrams"]:::output
    end

    %% Relationships
    CR1 -->|" .tex + .cls"| BE1
    CR2 -->|" .tex + .cls"| BE1
    TL1 --> BE1
    CF1 --> BE1
    SR1 --> BE1
    ET1 --> BE1
    BE1 -->|"PDF"| O1
    BE1 -->|"PDF"| O2

    CR3 -->|" .typ + template"| BE2
    TL2 --> BE2
    CF2 --> BE2
    SR1 --> BE2
    BE2 -->|"PDF"| O2
    BE2 -->|"diagrams"| O3

    CR2 --> BE3
    CR3 --> BE3
    CF3 --> BE3
    CF4 --> BE3
    CF5 --> BE3
    ET2 --> BE3
    BE3 --> SR2
    BE3 --> SR3
    SR2 --> BE1
    SR3 --> BE1
    BE3 --> BE2

    %% Click Events
    click CR1 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/notes/"
    click CR2 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/guide/latex/"
    click CR3 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/guide/typst/"
    click TL1 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/lib/latex/"
    click LCLS "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/lib/latex/HKNdocument.cls"
    click PRE "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/lib/latex/_preamble.tex"
    click POST "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/lib/latex/_postamble.tex"
    click CC "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/lib/latex/cclicense.tex"
    click LMKRC "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/lib/latex/latexmkrc"
    click TL2 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/lib/typst/"
    click FUNCS "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/lib/typst/funcs.typ"
    click TEMPLT "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/lib/typst/template.typ"
    click CF1 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/lib/latex/latexmkrc"
    click CF2 "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/typst.toml"
    click CF3 "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/pyproject.toml"
    click CF4 "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/requirements.txt"
    click CF5 "https://github.com/munuchapterhkn/eta-kappa-notes/blob/main/.vscode/settings.json"
    click CR2 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/guide/latex/res/py/"
    click CR3 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/guide/typst/example_notes/*/res/py/"
    click SR1 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/resources/imgs/"
    click SR2 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/guide/latex/res/svg/"
    click SR3 "https://github.com/munuchapterhkn/eta-kappa-notes/tree/main/notes/*/res/svg/"

    %% Styles
    classDef source fill:#D0E8FF,stroke:#007ACC,color:#000
    classDef template fill:#DFFFD0,stroke:#33A532,color:#000
    classDef engine fill:#FFE4C4,stroke:#FF8C00,color:#000
    classDef external fill:#F0F0F0,stroke:#888,color:#333
    classDef config fill:#E8E8E8,stroke:#555,color:#000
    classDef resource fill:#F5E6FF,stroke:#9B30FF,color:#000
    classDef output fill:#E6E6FA,stroke:#800080,color:#000
```
