# jupyter/governance architecture

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

- Interactive diagram: https://gitdiagram.com/jupyter/governance
- Repository: https://github.com/jupyter/governance

## Overview

##### Project type and purpose
- Type: Static documentation website (governance docs for Project Jupyter)
- Purpose: Maintain Markdown governance documents, build them into a browsable website with Jupyter Book, and publish via GitHub Pages.

##### File structure
- Top‐level content folders (e.g. charters/, conduct/, elections/, etc.) each containing Markdown source.
- Configuration files: _config.yml (Jupyter Book site config), _toc.yml (table of contents).
- Build scripts/workflows under .github/workflows (build.yml, deploy.yml).
- requirements.txt defines Python dependencies (jupyter-book, etc.).
- README.md explains build instructions; LICENSE.md and governance PDFs/Md files provide content.

##### README for additional insights
- The site is built locally via `jupyter-book build .`
- Hosted using GitHub Pages (via a gh-pages branch).
- CI workflows automate build & deploy.

##### Main components & their interactions
a. Source Repository
- Markdown content + config + CI workflows live in GitHub repo.
b. Continuous Integration (CI)
- GitHub Actions Build workflow: on push to main branch, sets up Python environment, installs Jupyter Book, builds static HTML in `_build/html`.
c. Continuous Deployment (CD)
- GitHub Actions Deploy workflow: on successful build, pushes static output to `gh-pages` branch.
d. Static Site Generator
- Jupyter Book CLI transforms `.md` + config into HTML.
e. Hosting
- GitHub Pages serves content from `gh-pages`.
f. End Users
- Browsers requesting governance pages at https://jupyter.org/governance.

##### Architectural patterns / design principles
- Clear separation of concerns:
- Content (Markdown) vs. Presentation (Jupyter Book templates)
- Build logic (CI workflows) vs. hosting (Pages)
- Declarative configuration: _config.yml, _toc.yml, workflows as code
- Static site generation (SSG) pattern

##### Technologies / frameworks in play
- Jupyter Book (static site generator)
- Python + pip for dependencies
- GitHub Actions for CI/CD
- GitHub Pages for hosting
- Markdown as source content

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Local Build
    Dev["Developer"]:::user
    LocalBuild["Local Build & Preview"]:::build
    Dev -->|"jupyter-book build ."| LocalBuild
    LocalBuild --> JBCLI

    %% Source Repository
    subgraph "GitHub Repository" 
        direction TB
        RepoContent["Markdown Content"]:::content
        RepoConfig["_config.yml & _toc.yml"]:::config
        RepoReq["requirements.txt"]:::config
        subgraph "CI/CD Workflows"
            direction TB
            BuildWF[".github/workflows/build.yml"]:::build
            DeployWF[".github/workflows/deploy.yml"]:::deploy
        end
        RepoMeta["README.md & LICENSE.md"]:::config
        RepoScripts["elections/process-votes.py"]:::config
        RepoPR[".github/PULL_REQUEST_TEMPLATE"]:::config
    end

    %% Expand Markdown Content
    subgraph "Markdown Content" 
        direction TB
        CHAR["charters/"]:::content
        COND["conduct/"]:::content
        ELEC["elections/"]:::content
        ARCH["archive/"]:::content
        BMEC["bootstrapping_executive_council.md"]:::content
        BMSSC["bootstrapping_subproject_councils.md"]:::content
        CBWG["communitybuildingworkinggroup.md"]:::content
        DM["decision_making.md"]:::content
        DC["distinguished_contributors.md"]:::content
        EC["executive_council.md"]:::content
        INTRO["intro.md"]:::content
        JF["jupyter_foundation.md"]:::content
        LP["linux-proposal.md"]:::content
        LSCAWG["list_of_standing_committees_and_working_groups.md"]:::content
        LOSP["list_of_subprojects.md"]:::content
        NEWSP["newsubprojects.md"]:::content
        OVW["overview.md"]:::content
        PAPERS["papers.md"]:::content
        PEOPLE["people.md"]:::content
        LICENSEMD["projectlicense.md"]:::content
        SSC["software_steering_council.md"]:::content
        SSWP["software_subprojects.md"]:::content
        SCWG["standing_committees_and_working_groups.md"]:::content
        TM["trademarks.md"]:::content
    end

    %% CI/CD and Build
    BuildWF -->|"on: push to main"| CI["CI Build Action"]:::build
    CI -->|"pip install & jupyter-book build"| JBCLI["Jupyter Book CLI"]:::build
    JBCLI -->|"generates HTML in _build/html"| HTML["Static HTML"]:::build
    HTML --> DeployWF
    DeployWF -->|"push to gh-pages"| Pages["GitHub Pages Hosting"]:::hosting
    Pages -->|"serves site"| User["End User Browser"]:::user

    %% Developer push to repo
    Dev -->|"push to main"| RepoContent
    Dev --> RepoConfig
    Dev --> RepoReq
    Dev --> RepoMeta
    Dev --> RepoScripts
    Dev --> RepoPR

    %% Local build flows into Jupyter Book CLI
    LocalBuild --> JBCLI

    %% Styles
    classDef content fill:#FFEFD5,stroke:#333,stroke-width:1px
    classDef config fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef build fill:#D3E4CD,stroke:#333,stroke-width:1px
    classDef deploy fill:#FADADD,stroke:#333,stroke-width:1px
    classDef hosting fill:#CFE0E8,stroke:#333,stroke-width:1px
    classDef user fill:#FFFACD,stroke:#333,stroke-width:1px

    %% Click Events for component mappings
    click CHAR "https://github.com/jupyter/governance/tree/main/charters/"
    click COND "https://github.com/jupyter/governance/tree/main/conduct/"
    click ELEC "https://github.com/jupyter/governance/tree/main/elections/"
    click ARCH "https://github.com/jupyter/governance/tree/main/archive/"
    click BMEC "https://github.com/jupyter/governance/blob/main/bootstrapping_executive_council.md"
    click BMSSC "https://github.com/jupyter/governance/blob/main/bootstrapping_subproject_councils.md"
    click CBWG "https://github.com/jupyter/governance/blob/main/communitybuildingworkinggroup.md"
    click DM "https://github.com/jupyter/governance/blob/main/decision_making.md"
    click DC "https://github.com/jupyter/governance/blob/main/distinguished_contributors.md"
    click EC "https://github.com/jupyter/governance/blob/main/executive_council.md"
    click INTRO "https://github.com/jupyter/governance/blob/main/intro.md"
    click JF "https://github.com/jupyter/governance/blob/main/jupyter_foundation.md"
    click LP "https://github.com/jupyter/governance/blob/main/linux-proposal.md"
    click LSCAWG "https://github.com/jupyter/governance/blob/main/list_of_standing_committees_and_working_groups.md"
    click LOSP "https://github.com/jupyter/governance/blob/main/list_of_subprojects.md"
    click NEWSP "https://github.com/jupyter/governance/blob/main/newsubprojects.md"
    click OVW "https://github.com/jupyter/governance/blob/main/overview.md"
    click PAPERS "https://github.com/jupyter/governance/blob/main/papers.md"
    click PEOPLE "https://github.com/jupyter/governance/blob/main/people.md"
    click LICENSEMD "https://github.com/jupyter/governance/blob/main/projectlicense.md"
    click SSC "https://github.com/jupyter/governance/blob/main/software_steering_council.md"
    click SSWP "https://github.com/jupyter/governance/blob/main/software_subprojects.md"
    click SCWG "https://github.com/jupyter/governance/blob/main/standing_committees_and_working_groups.md"
    click TM "https://github.com/jupyter/governance/blob/main/trademarks.md"
    click RepoConfig "https://github.com/jupyter/governance/blob/main/_config.yml"
    click RepoConfig "https://github.com/jupyter/governance/blob/main/_toc.yml"
    click RepoReq "https://github.com/jupyter/governance/blob/main/requirements.txt"
    click BuildWF "https://github.com/jupyter/governance/blob/main/.github/workflows/build.yml"
    click DeployWF "https://github.com/jupyter/governance/blob/main/.github/workflows/deploy.yml"
    click RepoMeta "https://github.com/jupyter/governance/blob/main/README.md"
    click RepoMeta "https://github.com/jupyter/governance/blob/main/LICENSE.md"
    click RepoScripts "https://github.com/jupyter/governance/blob/main/elections/process-votes.py"
    click RepoPR "https://github.com/jupyter/governance/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md"
    click RepoPR "https://github.com/jupyter/governance/blob/main/.github/PULL_REQUEST_TEMPLATE/standingcommittee.md"
    click RepoPR "https://github.com/jupyter/governance/blob/main/.github/PULL_REQUEST_TEMPLATE/workinggroup.md"
```
