# microsoft/winget-command-not-found architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/winget-command-not-found
- Repository: https://github.com/microsoft/winget-command-not-found

## Overview

1. **What this repository is**
   - This repo builds a **PowerShell 7.4+ module** named `Microsoft.WinGet.CommandNotFound`.
   - Its job is to act as a **feedback provider / command-line predictor plugin**: when PowerShell cannot find a native command, it suggests matching **WinGet packages** that could satisfy that command.

2. **Primary architectural boundary**
   - The core boundary is between **PowerShell’s feedback/prediction subsystem** and the **Windows Package Manager (WinGet)**.
   - The module does not implement a shell itself; it plugs into PowerShell’s **Subsystem Plugin Model** and returns suggestions back to the shell UI/PSReadLine.

3. **Module packaging and runtime surface**
   - `src/Microsoft.WinGet.CommandNotFound.csproj` builds the managed implementation targeting **.NET 8 / net8.0**.
   - `src/Microsoft.WinGet.CommandNotFound.psd1` is the PowerShell module manifest used for loading/importing the built artifact.
   - The README’s import path (`src/bin/<Configuration>/net8.0`) indicates the build produces a loadable PowerShell module assembly plus manifest.

4. **Core feedback/prediction component**
   - `src/WinGetCommandNotFoundFeedbackPredictor.cs` is the main managed entry point implied by the repo.
   - This class is the bridge that PowerShell calls when a command-not-found event occurs, and it is where package suggestions are likely assembled and returned to the shell.

5. **Suggestion flow**
   - The runtime flow is: **PowerShell detects a missing native command** → **feedback provider/predictor is invoked** → **module queries WinGet/package metadata** → **suggestions are returned to PowerShell/PSReadLine**.
   - The output is advisory only: it helps the user discover installable packages, but it does not install anything automatically.

6. **Environment and compatibility gating**
   - `src/ValidateOS.psm1` indicates a PowerShell-side validation layer, likely used to ensure the host OS/environment is supported before the predictor is activated.
   - This is an important boundary because the feature depends on specific PowerShell versions and experimental features (`PSFeedbackProvider`, `PSCommandNotFoundSuggestion`).

7. **Resource handling / allocation control**
   - `src/PooledPowerShellObjectPolicy.cs` suggests the module uses an object-pooling strategy for PowerShell-related objects.
   - That points to a performance-oriented internal layer to reduce repeated allocations while generating suggestions.

8. **Build and packaging pipeline**
   - `build.ps1` and `Microsoft.WinGet.CommandNotFound.build.ps1` are the build orchestration scripts.
   - The README shows the build is scripted rather than purely MSBuild-driven, and supports bootstrapping plus Debug/Release outputs.
   - `NuGet.config` indicates dependency restore is part of the build pipeline.

9. **Supporting tooling**
   - `tools/helper.psm1` is shared PowerShell tooling for build/release or repository automation.
   - The `.config/tsaoptions.json` and `.github` policy files are repo governance and automation, not runtime architecture, but they shape CI, issue handling, and release hygiene.

10. **External dependencies that matter architecturally**
   - **PowerShell 7.4+** is the host runtime because the module depends on `IFeedbackProvider`.
   - **PSReadLine 2.2.6+** is required for the command-line prediction UI to display the suggestions.
   - **WinGet** is the external package intelligence source the module consults to map a missing command to installable packages.

11. **Diagramming guidance**
   - A good architecture diagram should show:
     - PowerShell host / PSReadLine on one side
     - This module as the plugin layer in the middle
     - WinGet as the external package data source on the other side
     - A separate support path for OS validation and build/packaging artifacts
   - The repo is therefore best represented as a **PowerShell plugin module with a small managed core and a thin PowerShell support layer**, not as a standalone application.

Main entry points: [`src/WinGetCommandNotFoundFeedbackPredictor.cs`](https://github.com/microsoft/winget-command-not-found/blob/main/src/WinGetCommandNotFoundFeedbackPredictor.cs) (Feedback predictor), [`Microsoft.WinGet.CommandNotFound.build.ps1`](https://github.com/microsoft/winget-command-not-found/blob/main/Microsoft.WinGet.CommandNotFound.build.ps1) (Module build), [`build.ps1`](https://github.com/microsoft/winget-command-not-found/blob/main/build.ps1) (Build script), [`src/Microsoft.WinGet.CommandNotFound.psd1`](https://github.com/microsoft/winget-command-not-found/blob/main/src/Microsoft.WinGet.CommandNotFound.psd1) (Module manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime path"]
  node_powershell_host(("PowerShell 7.4+<br/>host runtime"))
  node_psreadline["PSReadLine<br/>prediction UI"]
  node_module_manifest["Module manifest<br/>psd1 package"]
  node_predictor["Feedback predictor<br/>managed plugin"]
  node_os_validation["OS check<br/>psm1 gate<br/>[ValidateOS.psm1]"]
  node_object_pool["Object pool<br/>allocation helper"]
  node_winget[("WinGet<br/>package source")]
end

subgraph group_build["Build path"]
  node_csproj["Module project<br/>net8.0 build"]
  node_build_ps1["Build script<br/>orchestration<br/>[build.ps1]"]
  node_module_build_ps1["Module build<br/>packaging script"]
  node_helper_psm1["Helper tools<br/>shared psm1<br/>[helper.psm1]"]
  node_nuget_config["NuGet config<br/>restore config<br/>[NuGet.config]"]
end

subgraph group_governance["Repo governance"]
  node_release_pipeline["Release CI<br/>pipeline<br/>[releaseBuild.yml]"]
  node_github_policies["GitHub policy<br/>automation<br/>[.github]"]
end

node_powershell_host -->|"imports"| node_module_manifest
node_module_manifest -->|"wires"| node_predictor
node_powershell_host -->|"renders"| node_psreadline
node_predictor -->|"checks"| node_os_validation
node_predictor -->|"uses"| node_object_pool
node_predictor -->|"queries"| node_winget
node_predictor -->|"returns"| node_psreadline
node_build_ps1 -->|"builds"| node_csproj
node_build_ps1 -->|"orchestrates"| node_module_build_ps1
node_module_build_ps1 -->|"reuses"| node_helper_psm1
node_module_build_ps1 -->|"restores"| node_nuget_config
node_release_pipeline -->|"runs"| node_build_ps1
node_github_policies -.->|"governs"| node_release_pipeline

click node_module_manifest "https://github.com/microsoft/winget-command-not-found/blob/main/src/Microsoft.WinGet.CommandNotFound.psd1"
click node_predictor "https://github.com/microsoft/winget-command-not-found/blob/main/src/WinGetCommandNotFoundFeedbackPredictor.cs"
click node_os_validation "https://github.com/microsoft/winget-command-not-found/blob/main/src/ValidateOS.psm1"
click node_object_pool "https://github.com/microsoft/winget-command-not-found/blob/main/src/PooledPowerShellObjectPolicy.cs"
click node_csproj "https://github.com/microsoft/winget-command-not-found/blob/main/src/Microsoft.WinGet.CommandNotFound.csproj"
click node_build_ps1 "https://github.com/microsoft/winget-command-not-found/blob/main/build.ps1"
click node_module_build_ps1 "https://github.com/microsoft/winget-command-not-found/blob/main/Microsoft.WinGet.CommandNotFound.build.ps1"
click node_helper_psm1 "https://github.com/microsoft/winget-command-not-found/blob/main/tools/helper.psm1"
click node_nuget_config "https://github.com/microsoft/winget-command-not-found/blob/main/NuGet.config"
click node_release_pipeline "https://github.com/microsoft/winget-command-not-found/blob/main/.pipelines/releaseBuild.yml"
click node_github_policies "https://github.com/microsoft/winget-command-not-found/blob/main/.github"

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_powershell_host,node_psreadline,node_module_manifest,node_predictor,node_os_validation,node_object_pool,node_winget toneBlue
class node_csproj,node_build_ps1,node_module_build_ps1,node_helper_psm1,node_nuget_config toneAmber
class node_release_pipeline,node_github_policies toneMint
```

## Components

### Runtime path

PowerShell command-not-found feedback flow and suggestion generation

- **PowerShell 7.4+**: host runtime · Shell host that invokes feedback providers when commands are missing
- **PSReadLine**: prediction UI · Displays command-line suggestions to the user
- [Module manifest](https://github.com/microsoft/winget-command-not-found/blob/main/src/Microsoft.WinGet.CommandNotFound.psd1): psd1 package · PowerShell module entrypoint and import metadata · `src/Microsoft.WinGet.CommandNotFound.psd1`
- [Feedback predictor](https://github.com/microsoft/winget-command-not-found/blob/main/src/WinGetCommandNotFoundFeedbackPredictor.cs): managed plugin · Main managed entrypoint that returns WinGet-based suggestions · `src/WinGetCommandNotFoundFeedbackPredictor.cs`
- [OS check](https://github.com/microsoft/winget-command-not-found/blob/main/src/ValidateOS.psm1): psm1 gate · Validates host/environment compatibility before activation · `src/ValidateOS.psm1`
- [Object pool](https://github.com/microsoft/winget-command-not-found/blob/main/src/PooledPowerShellObjectPolicy.cs): allocation helper · Pools PowerShell-related objects to reduce repeated allocations · `src/PooledPowerShellObjectPolicy.cs`
- **WinGet**: package source · External package intelligence used to match commands to installable packages

### Build path

Scripts and project files that produce the loadable module

- [Module project](https://github.com/microsoft/winget-command-not-found/blob/main/src/Microsoft.WinGet.CommandNotFound.csproj): net8.0 build · Targets .NET 8 and builds the managed module implementation · `src/Microsoft.WinGet.CommandNotFound.csproj`
- [Build script](https://github.com/microsoft/winget-command-not-found/blob/main/build.ps1): orchestration · Top-level build and bootstrapping entrypoint · `build.ps1`
- [Module build](https://github.com/microsoft/winget-command-not-found/blob/main/Microsoft.WinGet.CommandNotFound.build.ps1): packaging script · Repo-specific build and packaging logic for the module · `Microsoft.WinGet.CommandNotFound.build.ps1`
- [Helper tools](https://github.com/microsoft/winget-command-not-found/blob/main/tools/helper.psm1): shared psm1 · Reusable PowerShell functions for build and release automation · `tools/helper.psm1`
- [NuGet config](https://github.com/microsoft/winget-command-not-found/blob/main/NuGet.config): restore config · Dependency restore configuration used by the build · `NuGet.config`

### Repo governance

CI, issue handling, and policy automation

- [Release CI](https://github.com/microsoft/winget-command-not-found/blob/main/.pipelines/releaseBuild.yml): pipeline · Automated build and release pipeline definition · `.pipelines/releaseBuild.yml`
- [GitHub policy](https://github.com/microsoft/winget-command-not-found/blob/main/.github): automation · Issue and triage automation plus repository templates · `.github`

## Connections

- PowerShell 7.4+ → Module manifest: imports · PowerShell loads the module through its manifest
- Module manifest → Feedback predictor: wires · Manifest exposes the managed predictor implementation
- PowerShell 7.4+ → PSReadLine: renders · Suggestions are surfaced in the command-line UI
- Feedback predictor → OS check: checks · Activation is gated by OS and feature compatibility
- Feedback predictor → Object pool: uses · Prediction flow reuses pooled PowerShell objects
- Feedback predictor → WinGet: queries · Looks up packages that could satisfy the missing command
- Feedback predictor → PSReadLine: returns · Hands suggested commands back to the shell prediction path
- Build script → Module project: builds · Main build entrypoint compiles the managed project
- Build script → Module build: orchestrates · Build script delegates repo-specific packaging steps
- Module build → Helper tools: reuses · Packaging script shares helper functions
- Module build → NuGet config: restores · Build uses NuGet restore configuration
- Release CI → Build script: runs · CI invokes the scripted build path
- GitHub policy → Release CI: governs · Repo policy and templates support automation and release hygiene
