# microsoft/windowsdeveloperconfig architecture

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

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

## Overview

1. **What this repo is**
   - This is a configuration-as-code repository for Windows developer setups.
   - The core architectural model is “declarative config + PowerShell bootstrap + `winget configure` orchestration,” with most flows designed to be idempotent and re-runnable.

2. **Source of truth vs signed release copies**
   - `src/` is the authoritative source tree.
   - Top-level `windows-dev-config/`, `Workloads/`, and `wsl-comfort/` are signed release copies regenerated by the signing pipeline, not the primary edit surface.
   - That split is important for the architecture diagram: authoring happens in `src/`, distribution happens from the signed mirrors.

3. **Single manifest drives the system**
   - `src/manifest.yml` is the central catalog of flows.
   - It ties together paths, identities, build/run metadata, and the entries consumed by CI, the command-palette extension, and the per-flow bootstrap scripts.
   - Treat it as the registry that connects all subsystems.

4. **Common execution layer**
   - The shared PowerShell helpers in `Workloads/_common` and `src/Workloads/_common` provide the reusable execution primitives: preflight checks, retry logic, applying `winget` configuration, enabling/config-validating `winget configure`, and refreshing PATH.
   - These helpers form the boundary between declarative config files and actual machine mutation.

5. **Windows Dev Config flow**
   - `windows-dev-config` is the “full workstation” path.
   - It uses a single `dev-config.winget` file to install tools, apply Windows settings, and bootstrap WSL/Ubuntu.
   - There is a reboot boundary in this flow: `RunOnce` resumes the configuration after sign-in, so the architecture has an explicit “pre-reboot / post-reboot” split.

6. **WSL Comfort flow**
   - `wsl-comfort` is a two-part system: a Windows-side installer and a Linux-side bootstrap script.
   - The Windows side sets up WSL, the distro, fonts, and a Windows Terminal profile; the Linux side configures shell experience inside Ubuntu.
   - It supports both interactive and unattended modes, which is a key runtime boundary for the diagram.

7. **Single-language workloads**
   - `Workloads/` contains isolated dev-stack setups: .NET, Go, Java, PHP, Python, Rust, TypeScript, PowerShell, SQL, WinForms, and WinUI.
   - Each workload is a small unit with a `configuration.winget` manifest plus an `install.ps1` shim.
   - The shim’s main architectural purpose is to run the config and then refresh the current shell so newly installed tools are immediately on PATH.

8. **Technology and platform boundaries**
   - The main external engine is Windows Package Manager (`winget configure`), which is the installer/orchestrator for most setups.
   - Some flows also depend on Windows features and ecosystem tools such as WSL, Ubuntu, Visual Studio components, PowerShell 7, VS Code, and PowerToys.
   - Those dependencies define the real system boundaries: Windows OS configuration, package installation, and Linux-in-WSL shell configuration.

9. **Validation and test harness**
   - `src/tests` contains per-flow smoke tests with sample programs, probe scripts, and expected outputs.
   - The `_harness` scripts suggest the tests are run as flow-based integration checks rather than unit tests.
   - The diagram should show CI validating complete setups, not just script syntax.

10. **CI and release automation**
   - `.github/workflows/ci.yml` and `.pipelines/OneBranch.SignAndPackage.yml` indicate two important automation lanes: continuous validation and signed packaging.
   - `src/tools/check-signed-drift.ps1` and the `signed-copy-guard` workflow reinforce that signed mirrors must stay in sync with source.
   - This makes the repo’s delivery pipeline part of the architecture, not just build plumbing.

11. **Future extension surface**
   - `src/future/cmdpal/QuickWingetSetup` is a separate C#/.NET app intended to surface the same flows in a PowerToys Command Palette extension.
   - It has its own UI pages, models, and services for fetching, summarizing, and running scripts, plus WSL detection and `winget configure` health checks.
   - Architecturally, it is a consumer of the shared flow catalog rather than a new configuration source.

12. **How data moves through the repo**
   - At authoring time: `manifest.yml` and the per-flow `configuration.winget` files define what gets installed or configured.
   - At runtime: a shim or installer script invokes `winget configure`, then helper scripts handle validation, retries, and PATH refresh.
   - At distribution time: the signing pipeline publishes sanitized/signed copies into the top-level release folders.

13. **How to draw the diagram**
   - Put `src/manifest.yml` and the `src/` flow definitions at the center.
   - Branch out to three major consumers: Windows Dev Config, WSL Comfort, and single-language Workloads.
   - Add a cross-cutting helper layer for common PowerShell scripts, a validation lane for tests/CI, and a packaging lane that produces the signed top-level mirrors.

Main entry points: [`src/wsl-comfort`](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/wsl-comfort) (WSL Comfort), [`src/Workloads/_common`](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/Workloads/_common) (Shared PS), [`src/windows-dev-config`](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/windows-dev-config) (Dev Config), [`src/manifest.yml`](https://github.com/microsoft/windowsdeveloperconfig/blob/main/src/manifest.yml) (manifest.yml)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Source tree"]
  node_manifest["manifest.yml<br/>flow catalog<br/>[manifest.yml]"]
  node_src_common["Shared PS<br/>execution helpers"]
  node_src_windows_dev["Dev Config<br/>full workstation flow"]
  node_src_wsl_comfort["WSL Comfort<br/>dual-runtime flow"]
  node_src_workloads["Workloads<br/>language stacks"]
end

subgraph group_release["Signed mirrors"]
  node_release_windows_dev["Dev Config<br/>signed release"]
  node_release_workloads["Workloads<br/>signed release"]
  node_release_wsl_comfort["WSL Comfort<br/>signed release"]
end

subgraph group_automation["Automation"]
  node_ci["CI<br/>validation lane<br/>[ci.yml]"]
  node_signed_guard["Drift guard<br/>sync check"]
  node_sign_package["Sign & package<br/>release lane"]
end

subgraph group_validation["Validation"]
  node_tests_harness["Harness<br/>flow test runner"]
  node_tests_flows["Smoke tests<br/>integration checks"]
end

subgraph group_future["Future UI"]
  node_src_future_cmdpal["QuickWingetSetup<br/>cmdpal app"]
end

node_winget(("winget configure<br/>external engine"))
node_windows_os(("Windows OS<br/>platform boundary"))
node_wsl_ubuntu(("Ubuntu in WSL<br/>linux boundary"))

node_manifest -->|"describes"| node_src_windows_dev
node_manifest -->|"describes"| node_src_wsl_comfort
node_manifest -->|"describes"| node_src_workloads
node_src_windows_dev -->|"invokes"| node_winget
node_src_wsl_comfort -->|"invokes"| node_winget
node_src_workloads -->|"invokes"| node_winget
node_src_common -->|"wraps"| node_winget
node_src_common -->|"mutates"| node_windows_os
node_src_windows_dev -->|"configures"| node_windows_os
node_src_windows_dev -->|"reuses"| node_src_common
node_src_wsl_comfort -->|"configures"| node_windows_os
node_src_wsl_comfort -->|"boots"| node_wsl_ubuntu
node_src_wsl_comfort -->|"reuses"| node_src_common
node_src_workloads -->|"reuses"| node_src_common
node_tests_harness -->|"runs"| node_tests_flows
node_ci -->|"executes"| node_tests_harness
node_ci -->|"validates"| node_tests_flows
node_sign_package -->|"publishes"| node_release_windows_dev
node_sign_package -->|"publishes"| node_release_workloads
node_sign_package -->|"publishes"| node_release_wsl_comfort
node_signed_guard -->|"checks"| node_release_windows_dev
node_signed_guard -->|"checks"| node_release_workloads
node_signed_guard -->|"checks"| node_release_wsl_comfort
node_src_future_cmdpal -->|"consumes"| node_manifest
node_src_future_cmdpal -->|"health-checks"| node_winget
node_src_future_cmdpal -->|"detects"| node_wsl_ubuntu

click node_manifest "https://github.com/microsoft/windowsdeveloperconfig/blob/main/src/manifest.yml"
click node_src_common "https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/Workloads/_common"
click node_src_windows_dev "https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/windows-dev-config"
click node_src_wsl_comfort "https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/wsl-comfort"
click node_src_workloads "https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/Workloads"
click node_src_future_cmdpal "https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/future/cmdpal/QuickWingetSetup"
click node_tests_harness "https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/tests/_harness"
click node_tests_flows "https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/tests"
click node_ci "https://github.com/microsoft/windowsdeveloperconfig/blob/main/.github/workflows/ci.yml"
click node_signed_guard "https://github.com/microsoft/windowsdeveloperconfig/blob/main/.github/workflows/signed-copy-guard.yml"
click node_sign_package "https://github.com/microsoft/windowsdeveloperconfig/blob/main/.pipelines/OneBranch.SignAndPackage.yml"
click node_release_windows_dev "https://github.com/microsoft/windowsdeveloperconfig/tree/main/windows-dev-config"
click node_release_workloads "https://github.com/microsoft/windowsdeveloperconfig/tree/main/Workloads"
click node_release_wsl_comfort "https://github.com/microsoft/windowsdeveloperconfig/tree/main/wsl-comfort"

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_manifest,node_src_common,node_src_windows_dev,node_src_wsl_comfort,node_src_workloads toneBlue
class node_release_windows_dev,node_release_workloads,node_release_wsl_comfort toneAmber
class node_ci,node_signed_guard,node_sign_package toneMint
class node_tests_harness,node_tests_flows toneRose
class node_src_future_cmdpal toneIndigo
class node_winget,node_windows_os,node_wsl_ubuntu toneNeutral
```

## Components

### Source tree

Primary edit surface under src/

- [manifest.yml](https://github.com/microsoft/windowsdeveloperconfig/blob/main/src/manifest.yml): flow catalog · Central registry for flows, paths, identities, and run metadata · `src/manifest.yml`
- [Shared PS](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/Workloads/_common): execution helpers · Reusable preflight, retry, winget, and PATH-refresh primitives · `src/Workloads/_common`
- [Dev Config](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/windows-dev-config): full workstation flow · Authoritative Windows setup with reboot-resume orchestration · `src/windows-dev-config`
- [WSL Comfort](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/wsl-comfort): dual-runtime flow · Windows installer plus Linux bootstrap for Ubuntu shell comfort · `src/wsl-comfort`
- [Workloads](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/Workloads): language stacks · Isolated dev-stack installers built from winget manifests and shims · `src/Workloads`

### Signed mirrors

Top-level release copies regenerated by the signing pipeline

- [Dev Config](https://github.com/microsoft/windowsdeveloperconfig/tree/main/windows-dev-config): signed release · Signed mirror of the workstation setup · `windows-dev-config`
- [Workloads](https://github.com/microsoft/windowsdeveloperconfig/tree/main/Workloads): signed release · Signed mirror of the workload installers · `Workloads`
- [WSL Comfort](https://github.com/microsoft/windowsdeveloperconfig/tree/main/wsl-comfort): signed release · Signed mirror of the WSL comfort flow · `wsl-comfort`

### Automation

CI, signing, and drift checks

- [CI](https://github.com/microsoft/windowsdeveloperconfig/blob/main/.github/workflows/ci.yml): validation lane · Continuous validation workflow · `.github/workflows/ci.yml`
- [Drift guard](https://github.com/microsoft/windowsdeveloperconfig/blob/main/.github/workflows/signed-copy-guard.yml): sync check · Checks that signed mirrors stay aligned with source · `.github/workflows/signed-copy-guard.yml`
- [Sign & package](https://github.com/microsoft/windowsdeveloperconfig/blob/main/.pipelines/OneBranch.SignAndPackage.yml): release lane · Pipeline that publishes signed copies of release artifacts · `.pipelines/OneBranch.SignAndPackage.yml`

### Validation

Flow-level smoke tests and harness

- [Harness](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/tests/_harness): flow test runner · Shared scripts for running end-to-end smoke checks · `src/tests/_harness`
- [Smoke tests](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/tests): integration checks · Per-flow sample programs, probes, and expected outputs · `src/tests`

### Future UI

Command-palette extension surface

- [QuickWingetSetup](https://github.com/microsoft/windowsdeveloperconfig/tree/main/src/future/cmdpal/QuickWingetSetup): cmdpal app · PowerToys Command Palette consumer for browsing and running flows · `src/future/cmdpal/QuickWingetSetup`

### Other components

- **winget configure**: external engine · Main package/configuration orchestrator used by the flows
- **Windows OS**: platform boundary · Windows features, settings, and machine state
- **Ubuntu in WSL**: linux boundary · Linux shell environment configured from the WSL flow

## Connections

- manifest.yml → Dev Config: describes · Central catalog points to the workstation flow
- manifest.yml → WSL Comfort: describes · Central catalog points to the WSL comfort flow
- manifest.yml → Workloads: describes · Central catalog points to the language workload set
- Dev Config → winget configure: invokes · Install and configure operations are executed through winget configure
- WSL Comfort → winget configure: invokes · Windows-side setup uses winget configure for orchestration
- Workloads → winget configure: invokes · Each workload shim applies its winget configuration
- Shared PS → winget configure: wraps · Shared helpers validate and apply winget configuration
- Shared PS → Windows OS: mutates · Helpers manage machine state and shell environment
- Dev Config → Windows OS: configures · Applies Windows settings and bootstraps the workstation
- Dev Config → Shared PS: reuses · Uses shared preflight, retry, and PATH-refresh logic
- WSL Comfort → Windows OS: configures · Windows installer sets up WSL, distro, fonts, and terminal profile
- WSL Comfort → Ubuntu in WSL: boots · Linux bootstrap configures the Ubuntu shell experience
- WSL Comfort → Shared PS: reuses · Windows-side installer shares the common execution layer where applicable
- Workloads → Shared PS: reuses · Workload install shims rely on shared execution primitives
- Harness → Smoke tests: runs · Harness drives flow-based smoke checks
- CI → Harness: executes · CI runs the integration harness
- CI → Smoke tests: validates · CI validates representative setups end to end
- Sign & package → Dev Config: publishes · Packaging pipeline generates signed workstation mirror
- Sign & package → Workloads: publishes · Packaging pipeline generates signed workload mirror
- Sign & package → WSL Comfort: publishes · Packaging pipeline generates signed WSL comfort mirror
- Drift guard → Dev Config: checks · Ensures signed mirror matches source
- Drift guard → Workloads: checks · Ensures signed mirror matches source
- Drift guard → WSL Comfort: checks · Ensures signed mirror matches source
- QuickWingetSetup → manifest.yml: consumes · Extension reads the shared flow catalog and metadata
- QuickWingetSetup → winget configure: health-checks · Checks winget configure readiness before running scripts
- QuickWingetSetup → Ubuntu in WSL: detects · Service layer detects whether WSL is available