# pluralitybook/plurality architecture

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

- Interactive diagram: https://gitdiagram.com/pluralitybook/plurality
- Repository: https://github.com/pluralitybook/plurality

## Overview

##### Project Type and Purpose
- This is an open-source, git-based **collaborative book and documentation project**, not a traditional web application or microservice ecosystem.
- It uses **MkDocs** to produce a static site (docs), maintains source content for English and Traditional Mandarin chapters under `contents`, generates figures via data notebooks in `figs`, and runs helper scripts (e.g. index generation, PDF cover builds) under `scripts`.
- CI/CD (GitHub Actions) builds, tests, and deploys the static site (GitHub Pages), and enforces quality (linting, style guide compliance) on pull requests.

##### File Structure Analysis
- Top-level directories:
- `.github/` — workflow definitions (`docs-ci.yml`, `main.yml`) and issue templates
- `contents/` — source markdown for the book (English, Chinese)
- `docs/` — site content (home, style guide, governance, contributing) used by MkDocs
- `figs/` — data and Jupyter notebooks to generate charts/figures
- `scripts/` — build utilities: indexing scripts, PDF generation (Perl, Python), Dockerfile
- `mkdocs.yml` — site configuration
- Key patterns:
- **Static-site generation** (MkDocs)
- **Data pipeline** for figures (notebooks → assets)
- **CI/CD pipelines** for docs build & deployment
- **Governance integration** via Gov4Git (referenced in README)

##### README Insights
- Emphasizes **collaborative editing**, community governance (Gov4Git), translations, and a **static website** interface.
- No dynamic backend or database; focus is on content workflow, contribution process, and site generation.

a. **Main Components**
1. GitHub Repository
– Source folders: `contents/`, `docs/`, `figs/`, `scripts/`, `design/`
– Configuration: `mkdocs.yml`, `.github/`, `Dockerfile`
2. Developer Workstation
– Git clone/fork → local edits in markdown, notebooks, scripts
– Run scripts (`make-book.pl`, Python indexers, notebook renders)
3. CI/CD (GitHub Actions)
– `docs-ci.yml`: lint, link-check, style-guide validation
– `main.yml`: build MkDocs site, run notebooks or figure scripts, package artifacts (PDFs), deploy to GitHub Pages
4. Static Site Generator
– MkDocs reads `docs/` + chapters from `contents/` → HTML, CSS, JS
5. Deployment Target
– GitHub Pages (via `gh-pages` branch or `docs/` folder)
– Published website and PDF assets
6. Governance Engine (Gov4Git)
– Git-native protocol for proposal tracking (not a running service, but managed through Git & CI)
b. **Relationships & Data Flow**
1. Contributors push changes → GitHub repo
2. CI pipeline triggers on PR or merge → runs style checks and builds site
3. Figure pipeline (`figs/`) executes notebooks → outputs images/assets in `docs/assets`
4. Site generator (MkDocs) compiles markdown + assets → static HTML
5. Deployment step pushes generated site to Pages
6. Governance decisions managed via Git workflows (issues, PRs, Gov4Git commits)
c. **Architectural Patterns & Principles**
- **Content-as-Code**: book chapters as markdown, figures as code-driven notebooks
- **Immutable artifacts**: every build produces versioned static outputs
- **GitOps/Governance**: project governance tracked in Git commits/PRs
- **Modular pipelines**: separate concerns (content editing, figure generation, site build, PDF render)
d. **Technologies & Frameworks**
- MkDocs / Python
- GitHub Actions (YAML workflows)
- Jupyter Notebooks / pandas / Matplotlib (figure generation)
- Perl/Python scripts for indexing and PDF cover generation
- Gov4Git protocol (Git-native governance)
- Docker (for consistent build environments)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Contributor Workstation
    Workstation[/"Contributor Workstation"/]:::external
    click Workstation "https://github.com/pluralitybook/plurality/tree/main//"
    
    %% GitHub Repository
    Repo[(GitHub Repository)]:::source
    click Repo "https://github.com/pluralitybook/plurality/tree/main//"
    
    Workstation -->|clones & pushes| Repo

    subgraph "Content Layer"
        English["English Markdown"]:::source
        Trad["Traditional Mandarin Markdown"]:::source
    end
    click English "https://github.com/pluralitybook/plurality/tree/main/contents/english/"
    click Trad "https://github.com/pluralitybook/plurality/tree/main/contents/traditional-mandarin/"
    Repo --> English
    Repo --> Trad

    subgraph "Documentation Layer"
        Docs["Site Source (docs/)"]:::source
        GovDocs["Governance Docs"]:::gov
        Contrib["Contributing Guides"]:::source
        Style["Style Guide"]:::source
        Home["Home & Index"]:::source
    end
    click Docs "https://github.com/pluralitybook/plurality/tree/main/docs/"
    click GovDocs "https://github.com/pluralitybook/plurality/tree/main/docs/governance/"
    click Contrib "https://github.com/pluralitybook/plurality/tree/main/docs/contributing/"
    click Style "https://github.com/pluralitybook/plurality/tree/main/docs/style guide/"
    click Home "https://github.com/pluralitybook/plurality/tree/main/docs/home/"
    click Home "https://github.com/pluralitybook/plurality/blob/main/docs/index.md"
    Repo --> Docs

    subgraph "Figure/Data Pipeline"
        FNb["Notebooks & Data"]:::source
        StyleUtil["Styling Utilities"]:::pipelines
        figsRead["Pipeline README"]:::source
        OutAssets["Figure Assets"]:::output
    end
    click FNb "https://github.com/pluralitybook/plurality/tree/main/figs/data/"
    click StyleUtil "https://github.com/pluralitybook/plurality/tree/main/figs/data/_styling/"
    click figsRead "https://github.com/pluralitybook/plurality/blob/main/figs/readme.md"
    FNb --> OutAssets
    StyleUtil --> OutAssets
    Repo --> FNb

    subgraph "Build & Utility Scripts"
        Index["Indexing Pipeline"]:::pipelines
        BookEn["PDF Assembly EN"]:::pipelines
        BookZh["PDF Assembly ZH"]:::pipelines
        CoverEn["Cover EN"]:::pipelines
        CoverZh["Cover ZH"]:::pipelines
        CoverF["Front Cover"]:::pipelines
        CoverB["Back Cover"]:::pipelines
        Emoji["Emoji Filter"]:::pipelines
        DockerEnv["Dockerfile"]:::pipelines
    end
    click Index "https://github.com/pluralitybook/plurality/tree/main/scripts/index/"
    click BookEn "https://github.com/pluralitybook/plurality/blob/main/scripts/make-book.pl"
    click BookZh "https://github.com/pluralitybook/plurality/blob/main/scripts/make-book-zh-tw.pl"
    click CoverEn "https://github.com/pluralitybook/plurality/blob/main/scripts/cover-image.pdf"
    click CoverZh "https://github.com/pluralitybook/plurality/blob/main/scripts/cover-image.zh-tw.pdf"
    click CoverF "https://github.com/pluralitybook/plurality/blob/main/scripts/FrontCoverFeb2024.pdf"
    click CoverB "https://github.com/pluralitybook/plurality/blob/main/scripts/BackcoverFeb2024.pdf"
    click Emoji "https://github.com/pluralitybook/plurality/blob/main/scripts/emoji_filter.js"
    click DockerEnv "https://github.com/pluralitybook/plurality/tree/main/scripts/Dockerfile"
    Repo --> Index
    Repo --> BookEn
    Repo --> BookZh
    Repo --> CoverEn
    Repo --> CoverZh
    Repo --> Emoji
    Repo --> DockerEnv
    Index --> BookEn
    Index --> BookZh

    subgraph "CI/CD Pipeline"
        Lint["Docs CI (Lint & Style)"]:::pipelines
        BuildMk["Main Build & Deploy"]:::pipelines
    end
    click Lint "https://github.com/pluralitybook/plurality/blob/main/.github/workflows/docs-ci.yml"
    click BuildMk "https://github.com/pluralitybook/plurality/blob/main/.github/workflows/main.yml"
    Repo --> Lint
    Repo --> BuildMk
    OutAssets --> BuildMk

    subgraph "Static Site Generator"
        MkDocs["MkDocs Generator"]:::pipelines
    end
    click MkDocs "https://github.com/pluralitybook/plurality/blob/main/mkdocs.yml"
    BuildMk --> MkDocs
    English --> MkDocs
    Trad --> MkDocs
    Docs --> MkDocs
    OutAssets --> MkDocs
    MkDocs --> Site["Static HTML/CSS/JS"]:::output

    subgraph "Deployment"
        Pages["GitHub Pages"]:::output
        CNAME["CNAME Config"]:::output
    end
    click CNAME "https://github.com/pluralitybook/plurality/tree/main/docs/CNAME"
    Site --> Pages
    BuildMk --> Pages
    CNAME --> Pages

    subgraph "Governance Layer"
        GovEngine["Gov4Git Protocol"]:::gov
        GovDoc1["Gov4Git Overview"]:::gov
        GovDoc2["Management Protocol"]:::gov
    end
    click GovDoc1 "https://github.com/pluralitybook/plurality/blob/main/docs/governance/Gov4Git.md"
    click GovDoc2 "https://github.com/pluralitybook/plurality/blob/main/docs/governance/Plural management protocol.md"
    Repo --> GovEngine
    GovDoc1 --> GovEngine
    GovDoc2 --> GovEngine
    GovEngine --> Lint

    classDef source fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef pipelines fill:#90EE90,stroke:#333,stroke-width:1px
    classDef output fill:#FFA500,stroke:#333,stroke-width:1px
    classDef gov fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
```
