# hott/book architecture

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

- Interactive diagram: https://gitdiagram.com/hott/book
- Repository: https://github.com/hott/book

## Overview

##### Project type and purpose
- This is a LaTeX‐based textbook repository (“HoTT Book”) whose sole purpose is to maintain source files, automate the build of a complex multi‐output PDF book (and errata), and publish nightly/official builds.

##### File structure
- Top‐level:
- .github/workflows/ci.yml and .travis.yml → CI/CD definitions
- Makefile → orchestrates all build targets (`hott-*.pdf`, errata, version.tex)
- Numerous `.tex` files (chapters, frontmatter, backmatter), `.sty` style files, `.bib` reference database
- cover/ directory with image assets and symbols script
- other/ directory with helper scripts (Python, Agda) for indices, errata filtering
- Patterns: single monolithic repo, Make‐driven build automation, separation of source (tex + styles + scripts) vs. outputs (PDFs).

##### README for additional insights
- Describes target build variants (online, ebook, print, arXiv), required LaTeX packages, usage of `make`, nightly builds, distribution channels (website, GitHub wiki).
- Emphasizes that `version.tex` is generated on-the-fly by the Makefile.

1. Source Repository (GitHub)
– `.tex`, `.sty`, `.bib`, scripts, Makefile, CI configs
2. Local Development Environment
– Developer machine running TeXLive + make + editor
3. Build Engine
– Make utility + LaTeX engines (pdfLaTeX/XeLaTeX) + Python/Agda scripts
4. CI/CD Systems
– GitHub Actions (`ci.yml`), Travis CI (`.travis.yml`)
5. External Dependencies
– TeXLive packages, Python runtime, Agda
6. Output Artifacts
– Multi‐format PDFs (hott-online.pdf, hott-ebook.pdf, …), errata.pdf, versioned tex outputs
7. Distribution Channels
– GitHub Wiki (nightly builds), homotopytypetheory.org, arXiv, Lulu.com

- Developer → pushes to → GitHub Repo
- GitHub Repo → triggers → CI/CD Systems
- CI/CD Systems → invoke → Build Engine (Make + TeXLive + scripts)
- Build Engine → consumes → Source files + External dependencies
- Build Engine → produces → Output Artifacts
- Output Artifacts → published to → Distribution Channels
- Developer (locally) → runs → Makefile → Build Engine → Output Artifacts

c. Architectural patterns & design principles:
- Single‐source monolithic content repository
- Make‐driven declarative build pipeline
- Continuous integration for documentation
- Automated version injection (`version.tex`)
- Separation of concerns: source vs. build vs. distribution

d. Key technologies, frameworks, libraries:
- LaTeX (pdfLaTeX/XeLaTeX), TeXLive packages
- GNU Make
- GitHub Actions & Travis CI
- Python (other/*.py)
- Agda (example code)
- Creative-Commons licensing metadata

##### Key detail reminders
- Build targets (`hott-*.pdf`, errata, version.tex).
- Scripts in `/other` and their roles (index helper, errata filter).
- Both GitHub Actions and Travis CI flows, even if one is deprecated.
- Distribution to multiple channels (wiki, website, arXiv, Lulu).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer
    Developer["Developer Machine\n(TeXLive + make + Editor)"]:::dev

    %% Source Repository
    subgraph "Source Repository" 
        SR["GitHub Repo\n(.tex, .sty, .bib, scripts, CI configs, Makefile)"]:::source
        click SR "https://github.com/hott/book/tree/master//"
        MakefileNode["Makefile\n(orchestrates PDF builds)"]:::source
        click MakefileNode "https://github.com/hott/book/tree/master//Makefile"
        subgraph "LaTeX Sources" 
            FT["front.tex"]:::source
            click FT "https://github.com/hott/book/blob/master//front.tex"
            MT["main.tex"]:::source
            click MT "https://github.com/hott/book/blob/master//main.tex"
            IT["introduction.tex"]:::source
            click IT "https://github.com/hott/book/blob/master//introduction.tex"
            BT["basics.tex"]:::source
            click BT "https://github.com/hott/book/blob/master//basics.tex"
            ET["equivalences.tex"]:::source
            click ET "https://github.com/hott/book/blob/master//equivalences.tex"
            %% ... other .tex files
        end
        subgraph "Style Files"
            GY["geometry.sty"]:::source
            click GY "https://github.com/hott/book/blob/master//geometry.sty"
            CR["cleveref.sty"]:::source
            click CR "https://github.com/hott/book/blob/master//cleveref.sty"
            MAC["macros.tex"]:::source
            click MAC "https://github.com/hott/book/blob/master//macros.tex"
            SYM["symbols.tex"]:::source
            click SYM "https://github.com/hott/book/blob/master//symbols.tex"
            MP["mathpartir.sty"]:::source
            click MP "https://github.com/hott/book/blob/master//mathpartir.sty"
            IX["ifxetex.sty"]:::source
            click IX "https://github.com/hott/book/blob/master//ifxetex.sty"
        end
        Ref["references.bib"]:::source
        click Ref "https://github.com/hott/book/blob/master//references.bib"
        subgraph "Cover Assets"
            CoverDir["/cover"]:::source
            click CoverDir "https://github.com/hott/book/tree/master//cover"
            SymPy["symbols.py"]:::source
            click SymPy "https://github.com/hott/book/blob/master//cover/torus/symbols.py"
            TorusImg["torus-clipped.xcf"]:::source
            click TorusImg "https://github.com/hott/book/blob/master//cover/torus/torus-clipped.xcf"
        end
        subgraph "Helper Scripts"
            OtherDir["/other"]:::source
            click OtherDir "https://github.com/hott/book/tree/master//other"
            IH["index-helper.py"]:::source
            click IH "https://github.com/hott/book/blob/master//other/index-helper.py"
            FR["frequency.py"]:::source
            click FR "https://github.com/hott/book/blob/master//other/frequency.py"
            AG["prelim.agda"]:::source
            click AG "https://github.com/hott/book/blob/master//other/prelim.agda"
        end
        subgraph "Errata Scripts"
            FE["filter-errata"]:::source
            click FE "https://github.com/hott/book/tree/master//filter-errata"
            ME["mark-errata"]:::source
            click ME "https://github.com/hott/book/tree/master//mark-errata"
            CE["check-errata"]:::source
            click CE "https://github.com/hott/book/tree/master//check-errata"
        end
        CI1[".github/workflows/ci.yml"]:::ci
        click CI1 "https://github.com/hott/book/blob/master//.github/workflows/ci.yml"
        CI2[".travis.yml"]:::ci
        click CI2 "https://github.com/hott/book/blob/master//.travis.yml"
    end

    %% CI/CD Systems
    subgraph "CI/CD Systems" 
        GH["GitHub Actions"]:::ci
        Travis["Travis CI"]:::ci
    end

    %% Build Engine
    subgraph "Build Engine" 
        Make["Make Utility"]:::build
        LaTeX["pdfLaTeX/XeLaTeX Engines"]:::build
        Scripts["Python/Agda Scripts"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        TeXLive["TeXLive Packages"]:::ext
        PythonRT["Python Runtime"]:::ext
        AgdaRT["Agda Runtime"]:::ext
    end

    %% Output Artifacts
    subgraph "Output Artifacts"
        PDFs["hott-*.pdf\nerrata.pdf\nversion.tex"]:::output
    end

    %% Distribution Channels
    subgraph "Distribution Channels"
        Wiki["GitHub Wiki"]:::dist
        Website["homotopytypetheory.org"]:::dist
        Arxiv["arXiv"]:::dist
        Lulu["Lulu.com"]:::dist
    end

    %% Nightly Trigger
    Nightly["Nightly Build Trigger"]:::ci

    %% Connections
    Developer -->|pushes code to| SR
    Developer -->|runs make locally| Make
    SR -->|triggers| GH
    SR -->|triggers| Travis
    GH -->|invokes| Make
    Travis -->|invokes| Make
    Make -->|runs| LaTeX
    Make -->|runs| Scripts
    Make -->|uses| SR
    Make -->|uses| TeXLive
    Make -->|uses| PythonRT
    Make -->|uses| AgdaRT
    LaTeX -->|produces| PDFs
    Scripts -->|produces| PDFs
    PDFs -->|published to| Wiki
    PDFs -->|published to| Website
    PDFs -->|submitted to| Arxiv
    PDFs -->|sold via| Lulu
    Nightly -->|schedules| GH
    Nightly -->|schedules| Travis

    %% Styles
    classDef source fill:#DAE8FC,stroke:#6C8EBF,color:#1A3E68
    classDef build fill:#E1F5A9,stroke:#7CB342,color:#33691E
    classDef ci fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
    classDef ext fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef output fill:#F5F5F5,stroke:#9E9E9E,color:#424242
    classDef dist fill:#EEEEEE,stroke:#757575,color:#212121
    classDef dev fill:#FFF9C4,stroke:#FBC02D,color:#F57F17
```
