# microsoft/mu architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/mu
- Repository: https://github.com/microsoft/mu

## Overview

##### Project type and purpose
- This repo is not an application or service, but a **documentation site project** for “Project Mu.”
- It uses MkDocs (a static site generator) plus custom Python scripts to build, test, and deploy documentation.
- Continuous-integration (CI) workflows automate linting, testing, building, and publishing of the generated site.

##### File structure
a. **Top‐level files & scripts**
- `README.md`, `CONTRIBUTING.md`, `LICENSE.txt`, `SECURITY.md`, `.gitignore`, MkDocs config (`mkdocs_base.yml`), Python build tools (`DocBuild.py`, `Test_DocBuild.py`, `Utf8Test.py`), `requirements.txt`.
b. **`docs/` directory**
- Markdown source for all documentation (“WhatAndWhy”, “How”, “DeveloperDocs”, etc.), plus `docs/img` for images.
c. **`theme/` directory**
- Custom MkDocs theme assets (CSS, JS, images) under `theme/assets`.
d. **CI/CD configurations**
- Azure Pipelines YAML (`azure-pipelines-pr-gate.yml`)
- GitHub Actions workflows under `.github/workflows` (auto-approve, label-issues, stale, triage, etc.)
e. **Testing & linting**
- Python tests (`Test_DocBuild.py`), UTF-8 validation (`Utf8Test.py`), `.flake8`, `cspell.json` spelling config, `.markdownlint.yaml`.

##### README for additional insights
- Primary build commands:
1. `pip install --upgrade -r requirements.txt`
2. `DocBuild.py --Build --Clean --yml mkdocs_base.yml`
3. `mkdocs serve` (or `mkdocs build` in CI).
- Publishes to https://microsoft.github.io/mu/ via GitHub Pages / Azure static-site hosting.

##### Elements
- **Labels**: “Docs Source”, “Theme Assets”, “DocBuild.py”, “MkDocs Engine”, “CI/CD”, “Quality Gate”, “Hosting”.
- From Docs Source & Theme → DocBuild.py
- DocBuild.py → MkDocs Engine
- MkDocs Engine → Generated Site
- CI/CD → triggers lint/tests & build → deployment
- Output → Hosting
- **Blue rectangles** for code artifacts (scripts, source).
- **Orange clouds** for external services (GitHub, Azure).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    Dev["Developers"]:::external

    %% Content and Assets
    Docs["Docs Source"]:::code
    Theme["Theme Assets"]:::code

    %% Build Layer
    Build["DocBuild.py"]:::code
    Config["mkdocs_base.yml"]:::code
    MkDocs["MkDocs Engine"]:::code

    %% Site Output
    Site["Generated Site (/site)"]:::site

    %% Quality & Validation
    subgraph "Quality & Validation" 
        class Q1,Q2,Q3,Q4,Q5 code
        Q1[".flake8"]:::code
        Q2[".markdownlint.yaml"]:::code
        Q3["cspell.json"]:::code
        Q4["Test_DocBuild.py"]:::code
        Q5["Utf8Test.py"]:::code
    end
    class Q1,Q2,Q3,Q4,Q5 qgate

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        class CI1,CI2 ci
        CI1[".github/workflows/"]:::code
        CI2["azure-pipelines-pr-gate.yml"]:::code
    end
    class CI1,CI2 ciDashed

    %% Metadata & Guides
    subgraph "Project Metadata & Guides"
        class M1,M2,M3,M4 code
        M1["README.md"]:::code
        M2["CONTRIBUTING.md"]:::code
        M3["LICENSE.txt"]:::code
        M4["SECURITY.md"]:::code
    end

    %% Dependencies
    Req["requirements.txt"]:::code

    %% Hosting
    subgraph "Hosting"
        GH["GitHub Pages"]:::cloud
        AZ["Azure Static Website"]:::cloud
    end

    %% Flows
    Dev -->|"edits"| Docs
    Dev -->|"edits"| Theme
    Dev -->|"updates"| M1
    Dev --> M2
    Dev --> M3
    Dev --> M4
    Dev --> Req

    Dev -->|"push triggers"| CI1
    Dev --> CI2

    CI1 -->|"runs quality gates"| Q1
    CI1 --> Q2
    CI1 --> Q3
    CI1 --> Q4
    CI1 --> Q5

    Q1 & Q2 & Q3 & Q4 & Q5 -->|"all checks pass"| Build

    Build -->|"uses config"| Config
    Build -->|"invokes"| MkDocs

    MkDocs -->|"generates"| Site

    Site -->|"deploy"| GH
    Site -->|"deploy"| AZ

    CI2 -->|"deploy pipeline"| Site

    %% Click Events
    click Docs "https://github.com/microsoft/mu/tree/master/docs/"
    click Theme "https://github.com/microsoft/mu/tree/master/theme/assets/"
    click Build "https://github.com/microsoft/mu/blob/master/DocBuild.py"
    click Config "https://github.com/microsoft/mu/blob/master/mkdocs_base.yml"
    click Q4 "https://github.com/microsoft/mu/blob/master/Test_DocBuild.py"
    click Q5 "https://github.com/microsoft/mu/blob/master/Utf8Test.py"
    click Q1 "https://github.com/microsoft/mu/blob/master/.flake8"
    click Q2 "https://github.com/microsoft/mu/blob/master/.markdownlint.yaml"
    click Q3 "https://github.com/microsoft/mu/blob/master/cspell.json"
    click CI1 "https://github.com/microsoft/mu/tree/master/.github/workflows/"
    click CI2 "https://github.com/microsoft/mu/blob/master/azure-pipelines-pr-gate.yml"
    click M1 "https://github.com/microsoft/mu/blob/master/README.md"
    click M2 "https://github.com/microsoft/mu/blob/master/CONTRIBUTING.md"
    click M3 "https://github.com/microsoft/mu/blob/master/LICENSE.txt"
    click M4 "https://github.com/microsoft/mu/blob/master/SECURITY.md"
    click Req "https://github.com/microsoft/mu/blob/master/requirements.txt"

    %% Styles
    classDef code fill:#cce5ff,stroke:#004085
    classDef external fill:#fff3cd,stroke:#856404
    classDef site fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef cloud fill:#ffeeba,stroke:#856404
    classDef ci fill:#d1ecf1,stroke:#0c5460
    classDef qgate stroke-dasharray: 5 5
    classDef ciDashed stroke-dasharray: 5 5
```
