# arith-geom/ag-comp-arith-geom architecture

> Architecture diagram of the GitHub repository arith-geom/ag-comp-arith-geom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arith-geom/ag-comp-arith-geom
- Repository: https://github.com/arith-geom/ag-comp-arith-geom

## Overview

#### Purpose and runtime
This repository builds the official static website for Heidelberg University’s Computational Arithmetic Geometry group. It is a Ruby/Jekyll site: source content is rendered at build time into static HTML/CSS/JS, then published through GitHub Pages. Local entry point: `bundle exec jekyll serve`; dependencies are defined in `Gemfile` and `Gemfile.lock`.

#### Site entry points and routing
Top-level landing and primary sections are Markdown pages, with navigation/content driven by front matter and data:
- `index.md`
- `_pages/home.md`
- `_pages/members.md`
- `_pages/publications.md`
- `_pages/research.md`
- `_pages/contact.md`

Jekyll layout selection is the main routing/rendering boundary. Shared page shell and specialized content layouts live in `_layouts/default.liquid`, `_layouts/page.liquid`, `_layouts/publication.liquid`, and `_layouts/profiles/member.liquid`.

#### Structured content model
Editorial data is primarily YAML under `_data`, separating content from templates. Important domain datasets include:
- `_data/members.yml`
- `_data/publications.yml`
- `_data/teaching.yml`
- `_data/research.yml`
- `_data/navigation.yml`

Research and teaching also use Jekyll collections/content files under `_research/` and `_teaching/`, e.g. `_research/galois-representations.md` and `_teaching/index.md`. This boundary allows editors or a Pages CMS workflow to change structured records without altering rendering code.

#### Build-time content generation
Custom Ruby plugins convert structured records into generated pages, enforce naming rules, and provide presentation filters:
- `_plugins/member_generator.rb`
- `_plugins/publication_generator.rb`
- `_plugins/teaching_generator.rb`
- `_plugins/shortlink_generator.rb`
- `_plugins/filename_checker.rb`

These plugins are architecturally significant because generated member, publication, teaching, and redirect/shortlink routes depend on build-time transformations rather than only handwritten pages. `_plugins/cache_bust_filters.rb` supports asset versioning; `_plugins/linkify_authors.rb` enriches publication author output.

#### Rendering composition
Layouts compose reusable Liquid includes into site pages. The global shell is split into head, header, footer, and scripts:
- `_includes/layout/head.liquid`
- `_includes/layout/header.liquid`
- `_includes/layout/footer.liquid`
- `_includes/scripts/scripts.liquid`

Domain rendering is componentized for publications, projects, CVs, and repository information, notably `_includes/components/citation.liquid`, `_includes/components/selected-papers.liquid`, and `_includes/cv/time_table.liquid`. Page data flows from front matter/YAML collections through layouts and includes to static output.

#### Assets and browser behavior
Sass is compiled from the main stylesheet entry point and partials:
- `assets/css/main.scss`
- `_sass/_variables.scss`
- `_sass/_themes.scss`

Client-side JavaScript adds interactive presentation behavior, including search and MathJax configuration:
- `assets/js/search/search.js`
- `assets/js/components/mathjax-setup.js`
- `assets/search-data.json`

Large static PDFs and migrated archival materials are served directly from `assets/uploads/`, `assets/migrated/`, and `assets/img/fileadmin/`; they are content assets, not application-managed storage.

#### Delivery and quality boundaries
GitHub Actions provides the deployment pipeline in `.github/workflows/pages.yml`, targeting GitHub Pages. Repository configuration is centered in `_config.yml` and `.pages.yml`. A Python validation utility at `.github/scripts/validate.py` is available for content/data quality checks; it is separate from the Jekyll runtime. No server-side application, database, or API integration is indicated; external comment/embed providers are represented by optional Liquid includes such as `_includes/content/disqus.liquid` and `_includes/content/giscus.liquid`.

Main entry points: [`Gemfile`](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/Gemfile) (Jekyll site build), [`_layouts/default.liquid`](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_layouts/default.liquid) (Liquid layouts), [`_data/members.yml`](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_data/members.yml) (YAML domain data), [`_plugins/member_generator.rb`](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_plugins/member_generator.rb) (Custom generators)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Editorial Content"]
  node_pages["Primary Markdown pages<br/>Jekyll pages<br/>[index.md]"]
  node_data["YAML domain data<br/>Jekyll data<br/>[members.yml]"]
  node_research["Research collection<br/>Jekyll collection"]
  node_teaching["Teaching collection<br/>Jekyll collection"]
end

subgraph group_build["Jekyll Build"]
  node_config["Site configuration<br/>Jekyll config<br/>[_config.yml]"]
  node_jekyll{{"Jekyll site build<br/>Ruby static-site runtime"}}
  node_generators["Custom generators<br/>Ruby plugins"]
  node_filters["Presentation filters<br/>Ruby plugins"]
  node_output["Static site output<br/>HTML/CSS/JS"]
end

subgraph group_presentation["Presentation"]
  node_layouts["Liquid layouts<br/>Jekyll layouts<br/>[default.liquid]"]
  node_shell["Global shell includes<br/>Liquid includes<br/>[head.liquid]"]
  node_components["Domain components<br/>Liquid includes<br/>[citation.liquid]"]
  node_styles["Sass stylesheets<br/>[main.scss]"]
  node_browser["Browser enhancements<br/>JavaScript<br/>[search.js]"]
  node_assets["Static content assets<br/>served files"]
end

subgraph group_delivery["Delivery"]
  node_validation["Content validation<br/>Python utility<br/>[validate.py]"]
  node_deploy{{"Pages deployment<br/>GitHub Actions<br/>[pages.yml]"}}
  node_github_pages(("GitHub Pages<br/>static hosting"))
end

node_pages -->|"renders"| node_jekyll
node_data -->|"supplies records"| node_jekyll
node_research -->|"supplies collection"| node_jekyll
node_teaching -->|"supplies collection"| node_jekyll
node_config -->|"configures"| node_jekyll
node_data -->|"drives generated routes"| node_generators
node_teaching -->|"drives generated routes"| node_generators
node_generators -->|"extends build"| node_jekyll
node_filters -->|"extends rendering"| node_jekyll
node_jekyll -->|"selects layouts"| node_layouts
node_layouts -->|"composes"| node_shell
node_layouts -->|"renders"| node_components
node_styles -->|"compiles"| node_jekyll
node_browser -->|"published with"| node_output
node_assets -->|"copied to"| node_output
node_jekyll -->|"generates"| node_output
node_validation -.->|"checks"| node_data
node_deploy -->|"publishes"| node_output
node_output -->|"hosted on"| node_github_pages

click node_pages "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/index.md"
click node_data "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_data/members.yml"
click node_config "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_config.yml"
click node_jekyll "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/Gemfile"
click node_generators "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_plugins/member_generator.rb"
click node_filters "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_plugins/cache_bust_filters.rb"
click node_layouts "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_layouts/default.liquid"
click node_shell "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_includes/layout/head.liquid"
click node_components "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_includes/components/citation.liquid"
click node_styles "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/assets/css/main.scss"
click node_browser "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/assets/js/search/search.js"
click node_validation "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/.github/scripts/validate.py"
click node_deploy "https://github.com/arith-geom/ag-comp-arith-geom/blob/main/.github/workflows/pages.yml"

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_pages,node_data,node_research,node_teaching toneBlue
class node_config,node_jekyll,node_generators,node_filters,node_output toneAmber
class node_layouts,node_shell,node_components,node_styles,node_browser,node_assets toneMint
class node_validation,node_deploy,node_github_pages toneRose
```

## Components

### Editorial Content

Pages, data, and collections edited for the site.

- [Primary Markdown pages](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/index.md): Jekyll pages · `index.md`
- [YAML domain data](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_data/members.yml): Jekyll data · Members, publications, teaching, research, and navigation records. · `_data/members.yml`
- **Research collection**: Jekyll collection
- **Teaching collection**: Jekyll collection

### Jekyll Build

Ruby rendering and generation pipeline.

- [Site configuration](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_config.yml): Jekyll config · `_config.yml`
- [Jekyll site build](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/Gemfile): Ruby static-site runtime · Renders content into static HTML, CSS, and JavaScript. · `Gemfile`
- [Custom generators](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_plugins/member_generator.rb): Ruby plugins · Generate member, publication, teaching, and shortlink routes. · `_plugins/member_generator.rb`
- [Presentation filters](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_plugins/cache_bust_filters.rb): Ruby plugins · Adds asset cache busting and linked publication authors. · `_plugins/cache_bust_filters.rb`
- **Static site output**: HTML/CSS/JS

### Presentation

Reusable templates and browser assets.

- [Liquid layouts](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_layouts/default.liquid): Jekyll layouts · Select page structure and specialized publication or profile views. · `_layouts/default.liquid`
- [Global shell includes](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_includes/layout/head.liquid): Liquid includes · Head, header, footer, and scripts compose the shared page shell. · `_includes/layout/head.liquid`
- [Domain components](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/_includes/components/citation.liquid): Liquid includes · Citation, selected-paper, and CV presentation components. · `_includes/components/citation.liquid`
- [Sass stylesheets](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/assets/css/main.scss): Sass · `assets/css/main.scss`
- [Browser enhancements](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/assets/js/search/search.js): JavaScript · Search and MathJax presentation behavior. · `assets/js/search/search.js`
- **Static content assets**: served files · PDFs, migrated materials, and images are published directly.

### Delivery

Validation and GitHub Pages publishing.

- [Content validation](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/.github/scripts/validate.py): Python utility · Separate quality checks for site content and data. · `.github/scripts/validate.py`
- [Pages deployment](https://github.com/arith-geom/ag-comp-arith-geom/blob/main/.github/workflows/pages.yml): GitHub Actions · `.github/workflows/pages.yml`
- **GitHub Pages**: static hosting

## Connections

- Primary Markdown pages → Jekyll site build: renders
- YAML domain data → Jekyll site build: supplies records
- Research collection → Jekyll site build: supplies collection
- Teaching collection → Jekyll site build: supplies collection
- Site configuration → Jekyll site build: configures
- YAML domain data → Custom generators: drives generated routes
- Teaching collection → Custom generators: drives generated routes
- Custom generators → Jekyll site build: extends build
- Presentation filters → Jekyll site build: extends rendering
- Jekyll site build → Liquid layouts: selects layouts
- Liquid layouts → Global shell includes: composes
- Liquid layouts → Domain components: renders
- Sass stylesheets → Jekyll site build: compiles
- Browser enhancements → Static site output: published with
- Static content assets → Static site output: copied to
- Jekyll site build → Static site output: generates
- Content validation → YAML domain data: checks
- Pages deployment → Static site output: publishes
- Static site output → GitHub Pages: hosted on