# microsoftdocs/cloud-adoption-framework architecture

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

- Interactive diagram: https://gitdiagram.com/microsoftdocs/cloud-adoption-framework
- Repository: https://github.com/microsoftdocs/cloud-adoption-framework

## Overview

##### Project type and purpose
- This is a static documentation site (Microsoft Cloud Adoption Framework) built with markdown sources, templates, and configuration, then processed through a build pipeline to produce a published website.

##### File structure
- Top‐level directories:
- docs/                ← All markdown content, organized by topic/scenario
- includes/            ← Reusable content fragments
- templates/           ← Scenario‐ and page‐level markdown templates
- .docutune/           ← Configuration and data for DocuTune (content linting/score tool)
- Configuration files:
- docfx.json           ← DocFX static‐site generator config (under docs/)
- .openpublishing.*.json ← Publishing pipeline settings
- cspell*.json         ← Spell‐checker settings
- azure-pipelines.yml  ← Azure DevOps build & publish pipeline
- .github/workflows/*.yml ← GitHub Actions workflows (e.g., stale issue cleanup)
- Templates & data:
- .docutune/config, /data, /dictionaries ← DocuTune content quality engine
- templates/               ← Base markdown templates for new scenarios

##### README for additional insights
- The README only specifies the Code of Conduct; no architectural doc is present, so we infer architecture from folder names and config files.

##### Detail
- Break each major piece into subcomponents (e.g., under Build: DocuTune config/data/dictionaries; under Hosting: static files + redirection JSON).
- Tool interactions (spell check before build, content score gating, template rendering).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Authoring Layer
    subgraph "Authoring Layer"
        direction TB
        Docs["docs/"]:::repo
        Includes["includes/"]:::repo
        Templates["templates/"]:::repo
        DocfxConfig["docs/docfx.json"]:::repo
        DocuTuneConfig[".docutune/config/"]:::repo
        DocuTuneData[".docutune/data/"]:::repo
        DocuTuneDict[".docutune/dictionaries/Dictionary-Global.json"]:::repo
        Cspell["Spell Checker Settings"]:::repo
        OpenPub[".openpublishing configs"]:::repo
        PRTemplate["Pull Request Template"]:::repo
        QCInstructions["Quality Instructions"]:::repo
    end

    %% Build & QA Layer
    subgraph "Build & QA Layer"
        direction TB
        DocuTuneEngine["DocuTune Engine"]:::tool
        SpellCheck["cspell Spell Checker"]:::tool
        DocFX["DocFX Generator"]:::tool
    end

    %% CI/CD Layer
    subgraph "CI/CD Layer"
        direction TB
        AzurePipelines["Azure Pipelines"]:::pipeline
        GitHubActions["GitHub Actions"]:::pipeline
    end

    %% Deployment Layer
    subgraph "Deployment Layer"
        direction TB
        AzureHosting["Azure Static Web App / Storage+CDN"]:::hosting
        Redirection["Redirection Service"]:::hosting
    end

    EndUser["End User"]:::user

    %% Flows
    Docs -->|push| AzurePipelines
    Includes -->|push| AzurePipelines
    Templates -->|push| AzurePipelines
    DocfxConfig -->|config| AzurePipelines
    DocuTuneConfig -->|config| AzurePipelines
    DocuTuneData -->|data| AzurePipelines
    DocuTuneDict -->|dictionary| AzurePipelines
    Cspell -->|config| AzurePipelines
    OpenPub -->|config| AzurePipelines
    PRTemplate -->|repo metadata| AzurePipelines
    QCInstructions -->|instructions| AzurePipelines

    AzurePipelines -->|run| DocuTuneEngine
    DocuTuneEngine -->|report| AzurePipelines
    AzurePipelines -->|run| SpellCheck
    SpellCheck -->|report| AzurePipelines
    AzurePipelines -->|run| DocFX
    DocFX -->|generate site| AzurePipelines
    AzurePipelines -->|publish| AzureHosting

    GitHubActions -->|maintenance| Docs
    GitHubActions -->|maintenance| Includes
    GitHubActions -->|maintenance| Templates

    AzureHosting -->|serves| EndUser
    Redirection -->|redirects| EndUser
    AzureHosting -->|uses| Redirection

    %% Click Events
    click Docs "https://github.com/microsoftdocs/cloud-adoption-framework/tree/main/docs/"
    click Includes "https://github.com/microsoftdocs/cloud-adoption-framework/tree/main/includes/"
    click Templates "https://github.com/microsoftdocs/cloud-adoption-framework/tree/main/templates/"
    click DocfxConfig "https://github.com/microsoftdocs/cloud-adoption-framework/blob/main/docs/docfx.json"
    click DocuTuneConfig "https://github.com/microsoftdocs/cloud-adoption-framework/tree/main/.docutune/config/"
    click DocuTuneData "https://github.com/microsoftdocs/cloud-adoption-framework/tree/main/.docutune/data/"
    click DocuTuneDict "https://github.com/microsoftdocs/cloud-adoption-framework/blob/main/.docutune/dictionaries/Dictionary-Global.json"
    click AzurePipelines "https://github.com/microsoftdocs/cloud-adoption-framework/blob/main/azure-pipelines.yml"
    click GitHubActions "https://github.com/microsoftdocs/cloud-adoption-framework/blob/main/.github/workflows/stale.yml"
    click PRTemplate "https://github.com/microsoftdocs/cloud-adoption-framework/blob/main/.github/pull_request_template.md"
    click QCInstructions "https://github.com/microsoftdocs/cloud-adoption-framework/blob/main/AGENTS.md"

    %% Styles
    classDef repo fill:#bbdefb,stroke:#1e88e5,color:#000;
    classDef tool fill:#c8e6c9,stroke:#388e3c,color:#000;
    classDef pipeline fill:#ffe0b2,stroke:#fb8c00,color:#000;
    classDef hosting fill:#e1bee7,stroke:#8e24aa,color:#000;
    classDef user fill:#f5f5f5,stroke:#9e9e9e,color:#000;
```
