# github/github-well-architected architecture

> Architecture diagram of the GitHub repository github/github-well-architected, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/github/github-well-architected
- Repository: https://github.com/github/github-well-architected

## Overview

This repository maintains the GitHub Well-Architected Framework static site and content library. Authors contribute guidance across framework pillars and scenarios; the site presents that material through Hugo layouts and shared page components. The documented content-preprocessing workflow merges Markdown includes and adjusts relative links before Hugo builds or serves the site. The graph captures major content domains from the tree and the sampled preprocessing code; README documents local Hugo serving, but no deployment/runtime wiring was sampled.

Main entry points: [`content/library`](https://github.com/github/github-well-architected/tree/main/content/library) (Framework library), [`content/library/scenarios`](https://github.com/github/github-well-architected/tree/main/content/library/scenarios) (Scenarios), [`src/markdown-includer/includeMarkdown.js`](https://github.com/github/github-well-architected/blob/main/src/markdown-includer/includeMarkdown.js) (Markdown inclusion), [`src/resolve-hugo-links/adjust-hugo-links.js`](https://github.com/github/github-well-architected/blob/main/src/resolve-hugo-links/adjust-hugo-links.js) (Link adjustment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Framework content"]
  node_library["Framework library"]
  node_pillars["Pillar guidance"]
  node_scenarios["Scenarios"]
  node_migrations["Migration guides"]
end

subgraph group_site["Static site"]
  node_siteconfig["Hugo configuration"]
  node_layouts["Page layouts"]
  node_assets["Browser assets"]
  node_hugo["Hugo site engine"]
end

subgraph group_preprocess["Content preprocessing"]
  node_include["Markdown inclusion<br/>[includeMarkdown.js]"]
  node_linkadjust["Link adjustment"]
  node_linkreduce["Link depth reduction"]
  node_processed["Processed content"]
end

node_authors(("Content authors"))
node_visitor(("Site visitor"))

node_authors -->|"contribute guidance"| node_library
node_library -->|"organizes pillars"| node_pillars
node_library -->|"includes scenarios"| node_scenarios
node_scenarios -->|"includes migration guides"| node_migrations
node_library -.->|"supplies Markdown"| node_include
node_include -->|"merges includes"| node_processed
node_processed -.->|"supplies files"| node_linkadjust
node_linkadjust -->|"adjusts links"| node_processed
node_linkreduce -->|"rewrites links"| node_library
node_siteconfig -.->|"configures site"| node_hugo
node_layouts -.->|"provides templates"| node_hugo
node_assets -.->|"provides assets"| node_hugo
node_hugo -.->|"serves pages"| node_visitor
node_visitor -.->|"requests pages"| node_hugo

click node_library "https://github.com/github/github-well-architected/tree/main/content/library"
click node_pillars "https://github.com/github/github-well-architected/tree/main/content/library"
click node_scenarios "https://github.com/github/github-well-architected/tree/main/content/library/scenarios"
click node_migrations "https://github.com/github/github-well-architected/tree/main/content/library/scenarios/migrations"
click node_siteconfig "https://github.com/github/github-well-architected/tree/main/config"
click node_layouts "https://github.com/github/github-well-architected/tree/main/layouts"
click node_assets "https://github.com/github/github-well-architected/tree/main/assets"
click node_include "https://github.com/github/github-well-architected/blob/main/src/markdown-includer/includeMarkdown.js"
click node_linkadjust "https://github.com/github/github-well-architected/blob/main/src/resolve-hugo-links/adjust-hugo-links.js"
click node_linkreduce "https://github.com/github/github-well-architected/blob/main/src/resolve-hugo-links/reduce-link-depth.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_library,node_pillars,node_scenarios,node_migrations toneBlue
class node_siteconfig,node_layouts,node_assets,node_hugo toneAmber
class node_include,node_linkadjust,node_linkreduce,node_processed toneMint
class node_authors,node_visitor toneIndigo
```

## Components

### Framework content

- [Framework library](https://github.com/github/github-well-architected/tree/main/content/library): `content/library`
- [Pillar guidance](https://github.com/github/github-well-architected/tree/main/content/library): `content/library`
- [Scenarios](https://github.com/github/github-well-architected/tree/main/content/library/scenarios): `content/library/scenarios`
- [Migration guides](https://github.com/github/github-well-architected/tree/main/content/library/scenarios/migrations): `content/library/scenarios/migrations`

### Static site

- [Hugo configuration](https://github.com/github/github-well-architected/tree/main/config): `config`
- [Page layouts](https://github.com/github/github-well-architected/tree/main/layouts): `layouts`
- [Browser assets](https://github.com/github/github-well-architected/tree/main/assets): `assets`
- **Hugo site engine**

### Content preprocessing

- [Markdown inclusion](https://github.com/github/github-well-architected/blob/main/src/markdown-includer/includeMarkdown.js): `src/markdown-includer/includeMarkdown.js`
- [Link adjustment](https://github.com/github/github-well-architected/blob/main/src/resolve-hugo-links/adjust-hugo-links.js): `src/resolve-hugo-links/adjust-hugo-links.js`
- [Link depth reduction](https://github.com/github/github-well-architected/blob/main/src/resolve-hugo-links/reduce-link-depth.js): `src/resolve-hugo-links/reduce-link-depth.js`
- **Processed content**

### Other components

- **Content authors**
- **Site visitor**

## Connections

- Content authors → Framework library: contribute guidance (evidence: `README.md`)
- Framework library → Pillar guidance: organizes pillars (evidence: `README.md`)
- Framework library → Scenarios: includes scenarios (evidence: `README.md`)
- Scenarios → Migration guides: includes migration guides
- Framework library → Markdown inclusion: supplies Markdown
- Markdown inclusion → Processed content: merges includes (evidence: `src/markdown-includer/includeMarkdown.js`)
- Processed content → Link adjustment: supplies files
- Link adjustment → Processed content: adjusts links (evidence: `src/resolve-hugo-links/adjust-hugo-links.js`)
- Link depth reduction → Framework library: rewrites links (evidence: `src/resolve-hugo-links/reduce-link-depth.js`)
- Hugo configuration → Hugo site engine: configures site
- Page layouts → Hugo site engine: provides templates
- Browser assets → Hugo site engine: provides assets
- Hugo site engine → Site visitor: serves pages (evidence: `README.md`)
- Site visitor → Hugo site engine: requests pages (evidence: `README.md`)
