# ethercod3/diploma_latex architecture

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

- Interactive diagram: https://gitdiagram.com/ethercod3/diploma_latex
- Repository: https://github.com/ethercod3/diploma_latex

## Overview

1. This repository is not an application runtime; it is a reproducible build system for a thesis package. The primary deliverable is a compiled LaTeX PDF, with supporting assets generated from Mermaid, Python-based diagram scripts, and DOCX title-page templates.

2. The central source-of-truth is the main LaTeX document `Куприянов_И221_диплом.tex`, backed by `preamble/`, `appendix/`, `tables/`, `bibliography.bib`, and `fonts/`. LaTeX is built with LuaLaTeX plus `biblatex/biber`, and the document can also pull in external code listings from a sibling code repository path.

3. Generated assets form a strict boundary around the LaTeX build: Mermaid diagrams are compiled from `mermaid/*.mmd` into PDFs under `figures/`, Python diagram scripts in `python_diagrams/` also emit figures, and `docx/*.docx` are converted into `титульник.pdf` and `задание.pdf` in the repository root. The final LaTeX build consumes those generated PDFs/images rather than raw source formats.

4. Build orchestration is unified through `Taskfile.yml` and the `tasks/` split. The high-level flow is sequential: generate DOCX PDFs, generate Mermaid diagrams, generate Python diagrams, then compile the thesis LaTeX. The same orchestration is exposed both locally and through Docker Compose profiles.

5. The Python `scripts/` directory contains the operational layer for builds and utilities. It includes LaTeX builders, Mermaid compilation, PDF cropping, DOCX-to-PDF conversion, PDF diffing between commits, checksum updates, and a backup workflow. These scripts are the glue between source assets, external CLI tools, and the final artifacts.

6. Docker is used as an isolation boundary for reproducible toolchains. Separate images/profiles exist for `latex`, `mermaid`, `python`, `docx`, and `crop`, so each artifact type can be built with its own dependencies. The compose setup is also used in CI to guarantee consistent outputs.

7. Documentation is a separate subsystem under `docs/`, built with Zensical in Russian and English. It produces a static site, with alternate-language navigation and separate configs for local serving versus GitHub Pages deployment. This docs pipeline is independent from the thesis PDF build, but shares repository-level automation and hosting.

8. GitHub Actions provide the release and publishing boundary. Workflows cover Pages deployment, PDF release generation, validation and release of a Windows check executable, and scheduled backups. The CI logic is partly delegated to Python in `scripts/ci/`, which prepares release context and environment details before invoking the main build tasks.

9. The repository has a private content dependency: CI pulls a separate `diploma_code` repository into `vault_diploma` for code listings or appendix material. That makes the thesis build dependent not only on local sources but also on an external code corpus that must be available during build.

10. Testing is focused on the build automation itself, not on the thesis content. `tests/` uses pytest to verify the pure-Python helper scripts such as build, cleanup, Mermaid compilation, DOCX conversion, cropping, PDF diffing, and checksum updates.

11. Backup is treated as an explicit subsystem rather than a filesystem snapshot. The project can package its Git history into a `git bundle` and upload it through `rclone` to cloud remotes, with scheduled automation both locally and in GitHub Actions. This preserves repository history, not uncommitted working state.

12. Overall architecture: source materials live in LaTeX, Mermaid, DOCX, and Python; build scripts and Task coordinates artifact generation; Docker provides reproducible environments; the final outputs are a thesis PDF, generated figures, and a static documentation site; CI/CD publishes PDFs, docs, checks tools, and backups to external services.

Main entry points: [`scripts/build_all.py`](https://github.com/ethercod3/diploma_latex/blob/main/scripts/build_all.py) (Build scripts), [`Куприянов_И221_диплом.tex`](https://github.com/ethercod3/diploma_latex/blob/main/Куприянов_И221_диплом.tex) (Main thesis), [`tasks/build.yml`](https://github.com/ethercod3/diploma_latex/blob/main/tasks/build.yml) (Build tasks), [`figures/.gitkeep`](https://github.com/ethercod3/diploma_latex/blob/main/figures/.gitkeep) (Figures)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_taskfile["Taskfile<br/>task runner<br/>[Taskfile.yml]"]
  node_tasks_build["Build tasks<br/>task split<br/>[build.yml]"]
  node_tasks_diagrams["Diagram tasks<br/>task split<br/>[diagrams.yml]"]
  node_tasks_docx["DOCX tasks<br/>task split<br/>[docx.yml]"]
end

subgraph group_thesis["Thesis build"]
  node_thesis_main["Main thesis<br/>LaTeX root"]
  node_thesis_preamble["Preamble<br/>LaTeX setup<br/>[packages.tex]"]
  node_thesis_appendix["Appendix<br/>LaTeX content<br/>[appendix_b.tex]"]
  node_thesis_tables["Tables<br/>LaTeX content<br/>[tech_table.tex]"]
  node_thesis_bib["Bibliography<br/>biblatex source<br/>[bibliography.bib]"]
  node_thesis_fonts["Fonts<br/>font assets"]
end

subgraph group_assets["Generated assets"]
  node_mermaid_src["Mermaid source<br/>diagram source<br/>[flow.mmd]"]
  node_python_diagrams["Python diagrams<br/>figure scripts<br/>[languages.py]"]
  node_generated_figures[("Figures<br/>generated assets<br/>[.gitkeep]")]
  node_docx_templates["Title pages<br/>DOCX sources<br/>[титульник.docx]"]
  node_root_pdfs["Root PDFs<br/>generated PDFs"]
end

subgraph group_docs["Documentation"]
  node_docs_site["Docs site<br/>Zensical docs<br/>[README.md]"]
end

subgraph group_tooling["Tooling"]
  node_scripts_core["Build scripts<br/>Python glue<br/>[build_all.py]"]
  node_scripts_ci["CI helpers<br/>release utils"]
  node_tests_suite["Tests<br/>pytest suite"]
end

subgraph group_infra["Isolation"]
  node_dockerfiles["Dockerfiles<br/>toolchain images<br/>[latex.dockerfile]"]
  node_compose_files["Compose<br/>profiles"]
end

node_taskfile -->|"delegates"| node_tasks_build
node_taskfile -->|"delegates"| node_tasks_diagrams
node_taskfile -->|"delegates"| node_tasks_docx
node_tasks_build -->|"builds"| node_thesis_main
node_tasks_build -->|"builds"| node_docs_site
node_thesis_main -->|"includes"| node_thesis_preamble
node_thesis_main -->|"includes"| node_thesis_appendix
node_thesis_main -->|"includes"| node_thesis_tables
node_thesis_main -->|"references"| node_thesis_bib
node_thesis_main -->|"uses"| node_thesis_fonts
node_tasks_diagrams -->|"compiles"| node_mermaid_src
node_tasks_diagrams -->|"runs"| node_python_diagrams
node_mermaid_src -->|"outputs"| node_generated_figures
node_python_diagrams -->|"outputs"| node_generated_figures
node_tasks_docx -->|"converts"| node_docx_templates
node_docx_templates -->|"outputs"| node_root_pdfs
node_thesis_main -->|"consumes"| node_generated_figures
node_scripts_core -->|"implements"| node_tasks_build
node_scripts_core -->|"compiles"| node_mermaid_src
node_scripts_core -->|"converts"| node_docx_templates
node_scripts_core -->|"processes"| node_generated_figures
node_scripts_ci -->|"orchestrates"| node_scripts_core
node_tests_suite -->|"verifies"| node_scripts_core
node_dockerfiles -->|"assembled by"| node_compose_files
node_compose_files -->|"runs"| node_tasks_build
node_compose_files -->|"isolates"| node_scripts_core
node_docs_site -->|"documents"| node_scripts_core

click node_taskfile "https://github.com/ethercod3/diploma_latex/blob/main/Taskfile.yml"
click node_tasks_build "https://github.com/ethercod3/diploma_latex/blob/main/tasks/build.yml"
click node_tasks_diagrams "https://github.com/ethercod3/diploma_latex/blob/main/tasks/diagrams.yml"
click node_tasks_docx "https://github.com/ethercod3/diploma_latex/blob/main/tasks/docx.yml"
click node_thesis_main "https://github.com/ethercod3/diploma_latex/blob/main/Куприянов_И221_диплом.tex"
click node_thesis_preamble "https://github.com/ethercod3/diploma_latex/blob/main/preamble/packages.tex"
click node_thesis_appendix "https://github.com/ethercod3/diploma_latex/blob/main/appendix/appendix_b.tex"
click node_thesis_tables "https://github.com/ethercod3/diploma_latex/blob/main/tables/tech_table.tex"
click node_thesis_bib "https://github.com/ethercod3/diploma_latex/blob/main/bibliography.bib"
click node_thesis_fonts "https://github.com/ethercod3/diploma_latex/blob/main/fonts/latin-modern-mono/lmmono10-regular.otf"
click node_mermaid_src "https://github.com/ethercod3/diploma_latex/blob/main/mermaid/flow.mmd"
click node_python_diagrams "https://github.com/ethercod3/diploma_latex/blob/main/python_diagrams/languages.py"
click node_generated_figures "https://github.com/ethercod3/diploma_latex/blob/main/figures/.gitkeep"
click node_docx_templates "https://github.com/ethercod3/diploma_latex/blob/main/docx/титульник.docx"
click node_docs_site "https://github.com/ethercod3/diploma_latex/blob/main/docs/ru/README.md"
click node_scripts_core "https://github.com/ethercod3/diploma_latex/blob/main/scripts/build_all.py"
click node_scripts_ci "https://github.com/ethercod3/diploma_latex/blob/main/scripts/ci/prepare_pdf_release_env.py"
click node_tests_suite "https://github.com/ethercod3/diploma_latex/blob/main/tests/test_build_latex_manual.py"
click node_dockerfiles "https://github.com/ethercod3/diploma_latex/blob/main/docker/latex.dockerfile"
click node_compose_files "https://github.com/ethercod3/diploma_latex/blob/main/docker-compose.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_taskfile,node_tasks_build,node_tasks_diagrams,node_tasks_docx toneBlue
class node_thesis_main,node_thesis_preamble,node_thesis_appendix,node_thesis_tables,node_thesis_bib,node_thesis_fonts toneAmber
class node_mermaid_src,node_python_diagrams,node_generated_figures,node_docx_templates,node_root_pdfs toneMint
class node_docs_site toneRose
class node_scripts_core,node_scripts_ci,node_tests_suite toneIndigo
class node_dockerfiles,node_compose_files toneTeal
```

## Components

### Orchestration

Task-based build entrypoints and shared execution flow.

- [Taskfile](https://github.com/ethercod3/diploma_latex/blob/main/Taskfile.yml): task runner · Top-level task entrypoint coordinating build stages. · `Taskfile.yml`
- [Build tasks](https://github.com/ethercod3/diploma_latex/blob/main/tasks/build.yml): task split · High-level build orchestration for thesis, diagrams, docs, and utilities. · `tasks/build.yml`
- [Diagram tasks](https://github.com/ethercod3/diploma_latex/blob/main/tasks/diagrams.yml): task split · Task definitions for Mermaid and Python-generated figures. · `tasks/diagrams.yml`
- [DOCX tasks](https://github.com/ethercod3/diploma_latex/blob/main/tasks/docx.yml): task split · Task definitions for title-page DOCX conversion. · `tasks/docx.yml`

### Thesis build

LaTeX source tree and supporting content for the PDF deliverable.

- [Main thesis](https://github.com/ethercod3/diploma_latex/blob/main/Куприянов_И221_диплом.tex): LaTeX root · Primary thesis source document and central build target. · `Куприянов_И221_диплом.tex`
- [Preamble](https://github.com/ethercod3/diploma_latex/blob/main/preamble/packages.tex): LaTeX setup · Package loading, bibliography setup, counters, lists, and formatting. · `preamble/packages.tex`
- [Appendix](https://github.com/ethercod3/diploma_latex/blob/main/appendix/appendix_b.tex): LaTeX content · Appendix material and injected listings. · `appendix/appendix_b.tex`
- [Tables](https://github.com/ethercod3/diploma_latex/blob/main/tables/tech_table.tex): LaTeX content · Reusable thesis tables and structured content blocks. · `tables/tech_table.tex`
- [Bibliography](https://github.com/ethercod3/diploma_latex/blob/main/bibliography.bib): biblatex source · Reference database consumed by the thesis build. · `bibliography.bib`
- [Fonts](https://github.com/ethercod3/diploma_latex/blob/main/fonts/latin-modern-mono/lmmono10-regular.otf): font assets · Bundled font files required by the thesis typesetting environment. · `fonts/latin-modern-mono/lmmono10-regular.otf`

### Generated assets

Intermediate and generated artifact pipelines consumed by LaTeX and docs.

- [Mermaid source](https://github.com/ethercod3/diploma_latex/blob/main/mermaid/flow.mmd): diagram source · Mermaid diagram definitions compiled into thesis figures. · `mermaid/flow.mmd`
- [Python diagrams](https://github.com/ethercod3/diploma_latex/blob/main/python_diagrams/languages.py): figure scripts · Python-based diagram generators that emit figure assets. · `python_diagrams/languages.py`
- [Figures](https://github.com/ethercod3/diploma_latex/blob/main/figures/.gitkeep): generated assets · Compiled PDFs/images consumed by the thesis build. · `figures/.gitkeep`
- [Title pages](https://github.com/ethercod3/diploma_latex/blob/main/docx/титульник.docx): DOCX sources · DOCX templates for title page and assignment sheet. · `docx/титульник.docx`
- **Root PDFs**: generated PDFs · Converted DOCX deliverables placed at the repository root.

### Documentation

Zensical documentation site in two languages.

- [Docs site](https://github.com/ethercod3/diploma_latex/blob/main/docs/ru/README.md): Zensical docs · Static documentation site in Russian and English. · `docs/ru/README.md`

### Tooling

Python utilities, CI helpers, tests, and release automation.

- [Build scripts](https://github.com/ethercod3/diploma_latex/blob/main/scripts/build_all.py): Python glue · Python operational layer for compilation, cleanup, conversion, hashing, and diffing. · `scripts/build_all.py`
- [CI helpers](https://github.com/ethercod3/diploma_latex/blob/main/scripts/ci/prepare_pdf_release_env.py): release utils · CI-specific helpers for release context, publishing, and check-tool automation. · `scripts/ci/prepare_pdf_release_env.py`
- [Tests](https://github.com/ethercod3/diploma_latex/blob/main/tests/test_build_latex_manual.py): pytest suite · Verification of build and helper scripts. · `tests/test_build_latex_manual.py`

### Isolation

Containerized toolchains and compose profiles for reproducible builds.

- [Dockerfiles](https://github.com/ethercod3/diploma_latex/blob/main/docker/latex.dockerfile): toolchain images · Isolated build images for latex, mermaid, python, docx, and crop workflows. · `docker/latex.dockerfile`
- [Compose](https://github.com/ethercod3/diploma_latex/blob/main/docker-compose.yaml): profiles · Compose definitions used locally and in CI for reproducible toolchains. · `docker-compose.yaml`

## Connections

- Taskfile → Build tasks: delegates · Top-level tasks dispatch into split task files.
- Taskfile → Diagram tasks: delegates · Diagram-related automation is defined separately.
- Taskfile → DOCX tasks: delegates · DOCX conversion tasks are split out.
- Build tasks → Main thesis: builds · Main task path compiles the thesis PDF.
- Build tasks → Docs site: builds · Repository automation also covers documentation site generation.
- Main thesis → Preamble: includes · Root document depends on shared LaTeX setup.
- Main thesis → Appendix: includes · Appendix material is part of the thesis source graph.
- Main thesis → Tables: includes · Tables are assembled into the thesis.
- Main thesis → Bibliography: references · Bibliography is resolved through biblatex/biber.
- Main thesis → Fonts: uses · LuaLaTeX build relies on bundled fonts.
- Diagram tasks → Mermaid source: compiles · Mermaid sources are turned into figures.
- Diagram tasks → Python diagrams: runs · Python diagram scripts generate additional figures.
- Mermaid source → Figures: outputs · Compiled Mermaid diagrams land in the figures directory.
- Python diagrams → Figures: outputs · Python diagram scripts emit thesis figures.
- DOCX tasks → Title pages: converts · DOCX sources are converted into PDF deliverables.
- Title pages → Root PDFs: outputs · Converted title-page PDFs are written at the repository root.
- Main thesis → Figures: consumes · Final LaTeX build consumes generated PDFs and images, not raw sources.
- Build scripts → Build tasks: implements · Python scripts provide the build and utility actions behind tasks.
- Build scripts → Mermaid source: compiles · Mermaid compilation logic lives in Python utilities.
- Build scripts → Title pages: converts · DOCX-to-PDF conversion is handled by scripts.
- Build scripts → Figures: processes · Crop, diff, and hash utilities operate on generated artifacts.
- CI helpers → Build scripts: orchestrates · CI helpers prepare context before invoking core scripts.
- Tests → Build scripts: verifies · Pytest coverage targets the pure-Python automation layer.
- Dockerfiles → Compose: assembled by · Compose profiles select the appropriate build images.
- Compose → Build tasks: runs · Local and CI builds are executed through containerized profiles.
- Compose → Build scripts: isolates · Python helpers run within reproducible toolchains.
- Docs site → Build scripts: documents · Documentation explains the same build and release machinery.
