microsoft/windowsdeveloperconfig

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.