# scrumatscale/official-guide architecture

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

- Interactive diagram: https://gitdiagram.com/scrumatscale/official-guide
- Repository: https://github.com/scrumatscale/official-guide

## Overview

##### Project type and purpose
- Type: An open-source documentation project (the official Scrum@Scale Guide).
- Purpose: Store, manage, translate, build, and publish a LaTeX-based guide (PDF/Word) and related assets for a global audience.

##### File structure
- Top-level files:
– README.md, guide-us-english.tex/pdf – the primary English LaTeX source and output.
– _config.yml – configuration (likely for Jekyll/GitHub Pages).
– .gitattributes, .gitignore – VCS settings.
- Directories:
– images/ – shared media assets used by the English guide.
– translations/ – subfolders for each locale; each contains .tex/.pdf/.docx and occasionally its own images folder.
- No explicit build scripts in repo, but conventions imply use of:
– LaTeX toolchain (pdflatex/xelatex)
– Optional CI (GitHub Actions) for automated builds
– Jekyll or static-site generator using _config.yml for publishing HTML site.

##### README for additional insights
- Format: LaTeX.
- Contribution process: GitHub Issues & Pull Requests.
- Biannual release cadence.
- Translations: community-driven, must conform to structure (guide-language.tex etc.).

##### Main components & interactions
a. Components:
1. Version Control System (GitHub Repo)
2. Source Content:
– Master LaTeX (guide-us-english.tex) + images
– Translations (per-locale .tex/.docx + localized assets)
3. Continuous Integration / Build Environment:
– LaTeX compiler
– Conversion tools (.docx transformers, if any)
4. Static-Site Generator (Jekyll via _config.yml)
5. Outputs:
– PDF & DOCX guide files
– Published HTML site (via GitHub Pages)
6. Consumers:
– End users (download PDFs, view translations, read online)
– Contributors (open Issues/PRs)

b. Relationships & Data Flow:
– Contributors push commits/PRs → GitHub Repo
– CI detects changes → triggers build pipeline
– Build pipeline invokes LaTeX compiler on guide-us-english.tex and per-locale .tex files
– Generated PDFs (and DOCX covers) are stored in output directories or artifacts
– Jekyll processes Markdown/HTML templates (README, translation landing pages)
– Final site is deployed to GitHub Pages
– End users access site or download assets
– Feedback via Issues/PRs loops back to Contributors

c. Architectural patterns / principles
– Content-oriented, folder-per-locale modularity
– CI/CD: automated build & deploy
– Separation of concerns: source vs. build vs. deployment vs. consumption
– Community-driven extensibility (easy addition of new language folders)

d. Key technologies & frameworks
– Git/GitHub (repo, Issues, PRs, Pages)
– LaTeX toolchain (pdflatex/xelatex)
– Static-site generator (Jekyll, configured by _config.yml)
– PDF and DOCX document formats
– Creative Commons license

- Clear labels for each component (e.g., “GitHub Repo,” “LaTeX Compiler,” “GitHub Pages”)
– Push → Build → Deploy → Access
– Feedback loop from Users → Issues → PRs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Zone
    subgraph "Source" 
        direction TB
        Contributors["Contributors"]:::actor
        GitHubRepo["GitHub Repo"]:::external
        MasterLaTeX["Master LaTeX Source\n(guide-us-english.tex)"]:::source
        TranslationsDir["Translations Directory\n(translations/)"]:::source
        SharedAssets["Shared Media Assets\n(images/)"]:::source
        LegacyAssets["Legacy Translation Assets\n(zh-CN/old/)"]:::source
        TranslationSrc["Translation .tex Files"]:::source
    end

    %% Build Zone
    subgraph "Build & CI/CD"
        direction TB
        CI["CI/CD Pipeline"]:::ci
        LaTeX["LaTeX Compiler"]:::ci
        Jekyll["Jekyll Build\n(_config.yml)"]:::ci
    end

    %% Output Zone
    subgraph "Outputs"
        direction TB
        GuidePDF["Master PDF Output\n(guide-us-english.pdf)"]:::output
        CoverDocs["Cover Documents\n(.docx/.pdf)"]:::output
        TransPDF["Translation PDFs"]:::output
        TransDOCX["Translation DOCX"]:::output
        HTMLSite["HTML Site"]:::output
    end

    %% Deployment Zone
    subgraph "Deployment & Consumption"
        direction TB
        GitHubPages["GitHub Pages"]:::external
        EndUsers["End Users"]:::actor
    end

    %% Relationships
    Contributors -->|"push PRs/Commits"| GitHubRepo
    EndUsers -->|"open Issues"| GitHubRepo
    GitHubRepo -->|triggers| CI
    CI -->|runs| LaTeX
    LaTeX -->|generates| GuidePDF
    LaTeX -->|generates| TransPDF
    CI -->|runs| Jekyll
    Jekyll -->|produces| HTMLSite
    CI -->|collects| CoverDocs
    GuidePDF -->|publishes| GitHubPages
    HTMLSite -->|deploys| GitHubPages
    TransPDF -->|publishes| GitHubPages
    TransDOCX -->|publishes| GitHubPages
    GitHubPages -->|serves| EndUsers

    TranslationsDir --> TranslationSrc
    TranslationsDir --> TransPDF
    TranslationsDir --> TransDOCX
    SharedAssets --> MasterLaTeX
    SharedAssets --> TranslationSrc
    MasterLaTeX --> LaTeX

    %% Click Events
    click GitHubRepo "https://github.com/scrumatscale/official-guide/blob/master//.gitignore"
    click MasterLaTeX "https://github.com/scrumatscale/official-guide/blob/master//guide-us-english.tex"
    click GuidePDF "https://github.com/scrumatscale/official-guide/blob/master//guide-us-english.pdf"
    click CoverDocs "https://github.com/scrumatscale/official-guide/blob/master//ScrumAtScaleGuide-Cover.docx"
    click Jekyll "https://github.com/scrumatscale/official-guide/blob/master//_config.yml"
    click SharedAssets "https://github.com/scrumatscale/official-guide/tree/master//images/"
    click TranslationsDir "https://github.com/scrumatscale/official-guide/tree/master//translations/"
    click TranslationSrc "https://github.com/scrumatscale/official-guide/blob/master//translations/*/*.tex"
    click TransPDF "https://github.com/scrumatscale/official-guide/blob/master//translations/*/*.pdf"
    click TransDOCX "https://github.com/scrumatscale/official-guide/blob/master//translations/*/*.docx"
    click LegacyAssets "https://github.com/scrumatscale/official-guide/tree/master//translations/zh-CN/old/"

    %% Styles
    classDef actor fill:#e5f5e0,stroke:#33a02c,color:#000
    classDef external fill:#f0f0f0,stroke:#999,color:#000
    classDef source fill:#e0f3f8,stroke:#036, color:#000
    classDef ci fill:#c6dbef,stroke:#2171b5,color:#000
    classDef output fill:#fee8c8,stroke:#e6550d,color:#000
```
