# mpi-astronomy/faq architecture

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

- Interactive diagram: https://gitdiagram.com/mpi-astronomy/faq
- Repository: https://github.com/mpi-astronomy/faq

## Overview

##### Project type and purpose
- This is a **static documentation website** (“MPI-astronomy FAQ”) built with the **Jupyter Book** (MyST) ecosystem. Its sole purpose is to collect and publish short FAQ-style documents (Markdown + Jupyter notebooks) on astronomy-related computing topics.

##### File structure
- Top-level files:
- `.github/workflows/deploy-myst.yml` → CI/CD pipeline for building & deploying the site
- `myst.yml`, `pyproject.toml`, `requirements.txt` → project configuration & dependencies for Jupyter Book
- `README.md`, `LICENSE`, `CONTRIBUTING.md`, etc. → repository metadata
- Content directory:
- `faq/` → Jupyter Book source tree containing `_config.yml`, chapter TOC (`_toc.yml`), Markdown chapters and `.ipynb` notebooks
- No traditional “backend” or “database”—the site is generated purely from file-based source.

##### README for additional insights
- Confirms use of **Jupyter Book** (MyST Markdown + notebooks) and the **executablebooks/cookiecutter-jupyter-book template**
- Deploys via a GitHub Actions workflow to GitHub Pages at `https://mpi-astronomy.github.io/FAQ/`

##### Main components & relationships
a. **Source Repository (GitHub)**
- Stores all content (`faq/`), configuration (`myst.yml`, `_config.yml`), build scripts, and CI definitions.
b. **Static Site Generator (Jupyter Book)**
- Reads the MyST Markdown and notebooks, applies templates, and produces a static HTML/CSS/JS site.
c. **CI/CD Pipeline (GitHub Actions)**
- On push/merge, runs `deploy-myst.yml`, installs dependencies, invokes `jupyter-book build`, and publishes output to the `gh-pages` branch.
d. **Hosting (GitHub Pages)**
- Serves the generated static site to end users at the public URL.
e. **End Users**
- Browse the FAQ in a web browser; no dynamic server or database involved.

Data Flow:
Developer → Git commit → GitHub Actions → Jupyter Book build → gh-pages branch → GitHub Pages → Browser

##### Architectural patterns & design principles
- **Infrastructure as code**: CI/CD pipeline fully defined in YAML
- **Configuration-driven**: All site behavior controlled via `myst.yml` & `_config.yml`
- **Content-source separation**: Raw documents in `faq/` are separate from build logic
- **Immutable hosting**: Once built, site is static—no runtime code execution on the server

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Repository
    subgraph "Source Repository (GitHub)"
        Repo["/ (root)"]:::repo
        README["README.md"]:::file
        LICENSE["LICENSE"]:::file
        CONTRIB["CONTRIBUTING.md"]:::file
        MYSTCFG["myst.yml"]:::config
        PYPROJ["pyproject.toml"]:::config
        REQ["requirements.txt"]:::config
        subgraph "Content Directory"
            FAQ["/faq/"]:::content
            FAQCFG["_config.yml"]:::config
            FAQTOC["_toc.yml"]:::config
        end
    end

    %% CI/CD Pipeline
    CI["GitHub Actions CI/CD"]:::ci
    WORKFLOW[".github/workflows/deploy-myst.yml"]:::file

    %% Static Site Generator
    Generator["Jupyter Book Build"]:::generator
    CLICK_MYST["myst.yml"]:::config

    %% Hosting
    Pages["GitHub Pages Hosting"]:::hosting

    %% End User
    User["End User Browser"]:::user

    %% Connections
    Repo -->|push/merge| CI
    CI -->|"runs deploy-myst.yml"| Generator
    Generator -->|"build HTML/CSS/JS"| Pages
    Pages -->|"serve site"| User

    %% Internal links
    Repo --> README
    Repo --> LICENSE
    Repo --> CONTRIB
    Repo --> MYSTCFG
    Repo --> PYPROJ
    Repo --> REQ
    Repo --> FAQ
    FAQ --> FAQCFG
    FAQ --> FAQTOC
    CI --> WORKFLOW
    Generator --> CLICK_MYST

    %% Click Events
    click Repo "https://github.com/mpi-astronomy/faq/tree/main//"
    click README "https://github.com/mpi-astronomy/faq/blob/main/README.md"
    click LICENSE "https://github.com/mpi-astronomy/faq/tree/main/LICENSE"
    click CONTRIB "https://github.com/mpi-astronomy/faq/blob/main/CONTRIBUTING.md"
    click MYSTCFG "https://github.com/mpi-astronomy/faq/blob/main/myst.yml"
    click PYPROJ "https://github.com/mpi-astronomy/faq/blob/main/pyproject.toml"
    click REQ "https://github.com/mpi-astronomy/faq/blob/main/requirements.txt"
    click FAQ "https://github.com/mpi-astronomy/faq/tree/main//faq/"
    click FAQCFG "https://github.com/mpi-astronomy/faq/blob/main//faq/_config.yml"
    click FAQTOC "https://github.com/mpi-astronomy/faq/blob/main//faq/_toc.yml"
    click WORKFLOW "https://github.com/mpi-astronomy/faq/blob/main/.github/workflows/deploy-myst.yml"

    %% Styles
    classDef repo fill:#E3F2FD,stroke:#1E88E5,stroke-width:2px
    classDef file fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
    classDef config fill:#E8F5E9,stroke:#43A047,stroke-width:1px
    classDef content fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px
    classDef ci fill:#FFEBEE,stroke:#E53935,stroke-width:2px
    classDef generator fill:#E1F5FE,stroke:#039BE5,stroke-width:2px
    classDef hosting fill:#FBE9E7,stroke:#D84315,stroke-width:2px
    classDef user fill:#FFFDE7,stroke:#FDD835,stroke-width:2px
```
