Add ARCHITECTURE.md for the NuGet.Client repository by aortiz-msft · Pull Request #7228 · NuGet/NuGet.Client

aortiz-msft · 2026-03-23T22:53:20Z

Bug

Fixes: N/A

Description

Adds architecture.md file to help LLMs generate code for the repository.

Also:

Added skill to re-generate the architecture.md file when needed.
Removed project-overview.md file which was auto-generated and more limited in comparison.

PR Checklist

Meaningful title, helpful description and a linked NuGet/Home issue
Added tests
Link to an issue or pull request to update docs if this PR changes settings, environment variables, new feature, etc.

nkolev92

A left a bunch of comments that copilot should be able to fix.

I do think it's worth eliminating the duplication with project-overview since that is a smaller more compact version of this, but it doesn't really contain opinionated explanations like this one does.

ARCHITECTURE.md

nkolev92 · 2026-03-23T23:21:33Z

ARCHITECTURE.md

+
+A standalone console executable (`NuGet.Build.Tasks.Console.exe`) that runs restore using MSBuild's static graph functionality. This is the out-of-process restore host invoked by the `RestoreTaskEx` MSBuild task for improved performance and isolation.
+
+Depends on: `NuGet.Build.Tasks` and all transitive core libraries.


Interestingly depends on is different here :D

The "depends on" data was probably obtained from the DGML file which was generated deterministically by Visual Studio. Are you saying this is wrong?

It's not wrong.
Some places it lists the full closure, others just the top one. I don't see how/why.

I think a project level DGML, or ideally a mermaid for github is probably better than the text.

Since the DGML is auto-generated, and can be generated easily on-demand, I'm leaning towards not including these.

Removing them is fine I agree.
The diagram is much more useful and honestly makes the whole doc shorter leaves less room for something to become outdated.

ARCHITECTURE.md

nkolev92

Looking much better.

nkolev92 · 2026-03-26T17:36:43Z

ARCHITECTURE.md

+This document describes the high-level architecture of NuGet.Client.
+If you want to familiarize yourself with the codebase, you are in the right place!
+
+See also the auto-generated [project overview](docs/project-overview.md), the [feature guide](docs/feature-guide.md), and the [coding guidelines](docs/coding-guidelines.md).


Suggested change

See also the auto-generated [project overview](docs/project-overview.md), the [feature guide](docs/feature-guide.md), and the [coding guidelines](docs/coding-guidelines.md).

See also [feature guide](docs/feature-guide.md), and the [coding guidelines](docs/coding-guidelines.md).

project-overview is no more.

nkolev92 · 2026-03-26T17:40:16Z

ARCHITECTURE.md

+
+These are the foundational libraries shared by all NuGet products. They are multi-targeted (`net472` and `net8.0`) and have no dependency on Visual Studio or any specific host.
+
+#### [`NuGet.Versioning`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Versioning/NuGet.Versioning.csproj)


These links should be relative, otherwise they'll take out of the editor.
If you are looking at this in code clicking this will take you to a browser, but you actually want the local link.

nkolev92 · 2026-03-26T17:42:44Z

ARCHITECTURE.md

+
+A standalone console executable (`NuGet.Build.Tasks.Console.exe`) that runs restore using MSBuild's static graph functionality. This is the out-of-process restore host invoked by the `RestoreTaskEx` MSBuild task for improved performance and isolation.
+
+Depends on: `NuGet.Build.Tasks` and all transitive core libraries.


Removing them is fine I agree.
The diagram is much more useful and honestly makes the whole doc shorter leaves less room for something to become outdated.

nkolev92 · 2026-03-26T17:45:18Z

ARCHITECTURE.md

+
+#### [`NuGet.PackageManagement`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.PackageManagement/NuGet.PackageManagement.csproj)
+
+Package management orchestration for install/uninstall/update flows (primarily used by the Visual Studio client and NuGet.exe `install`/`update` commands). Defines `NuGetPackageManager`, the abstract `NuGetProject` base class, and concrete project types like `MSBuildNuGetProject`, `FolderNuGetProject`, and `BuildIntegratedNuGetProject`. The `Audit/` subdirectory handles package vulnerability auditing.


The concrete types are not the ones I'd choose as "most important".

We can tweak them, or remove them.
My vote is remove them.

nkolev92 · 2026-03-26T17:45:39Z

ARCHITECTURE.md

+
+#### [`NuGet.Localization`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Localization/NuGet.Localization.csproj)
+
+Localization satellite assemblies for the dotnet CLI. Leaf dependency.


This is just a payload package.

nkolev92 · 2026-03-26T17:50:07Z

ARCHITECTURE.md

+
+#### [`NuGet.SolutionRestoreManager`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Clients/NuGet.SolutionRestoreManager/NuGet.SolutionRestoreManager.csproj)
+
+The second VS package. `RestoreManagerPackage` auto-loads when a solution is open and hooks into VS build events. `SolutionRestoreBuildHandler` triggers restore before build. `SolutionRestoreWorker` executes restore jobs. `VsSolutionRestoreService` exposes restore as a brokered service.


RestoreManagerPackage by design contains a slimmed down version of the NuGet assemblies, allowing the functionality to be loaded early without paying a performance cost.

nkolev92 · 2026-03-26T17:50:49Z

ARCHITECTURE.md

+
+Depends on: `NuGet.Commands`, `NuGet.PackageManagement`, `NuGet.VisualStudio`, `NuGet.VisualStudio.Internal.Contracts`, and core libraries.
+
+#### [`NuGet.VisualStudio`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Clients/NuGet.VisualStudio/NuGet.VisualStudio.csproj)


Were we gonna group these 2?

nkolev92 · 2026-03-26T17:53:16Z

ARCHITECTURE.md

+
+### MEF Composition (VS)
+
+The VS extension uses MEF (Managed Extensibility Framework) extensively for service discovery and dependency injection. Key exports include `VSSolutionManager`, `ExtensibleSourceRepositoryProvider`, `NuGetUIFactory`, `VsPackageInstaller`, and the PowerShell console providers. Services are composed by VS's `SComponentModel`.


Suggested change

The VS extension uses MEF (Managed Extensibility Framework) extensively for service discovery and dependency injection. Key exports include `VSSolutionManager`, `ExtensibleSourceRepositoryProvider`, `NuGetUIFactory`, `VsPackageInstaller`, and the PowerShell console providers. Services are composed by VS's `SComponentModel`.

The VS extension uses MEF (Managed Extensibility Framework) extensively for service discovery and dependency injection. Key exports include `VSSolutionManager`, `ExtensibleSourceRepositoryProvider`, `NuGetUIFactory`, `VsPackageInstaller`, and the PowerShell console providers.

Create ARCHITECTURE.md

2a60d96

aortiz-msft requested a review from a team as a code owner March 23, 2026 22:53

aortiz-msft requested review from jebriede and nkolev92 March 23, 2026 22:53

nkolev92 reviewed Mar 23, 2026

View reviewed changes

aortiz-msft added 5 commits March 24, 2026 10:50

Firs round of updates from review

ffd1302

Second wave of review feedback

5bb90bb

Replaced ASCII diagram with Mermaid diagram

d3ca51d

Add skill for generating the architecture.md file

d6aea68

Delete project-overview.md file

a134331

aortiz-msft requested review from kartheekp-ms and nkolev92 March 25, 2026 21:54

nkolev92 reviewed Mar 26, 2026

View reviewed changes


		A standalone console executable (`NuGet.Build.Tasks.Console.exe`) that runs restore using MSBuild's static graph functionality. This is the out-of-process restore host invoked by the `RestoreTaskEx` MSBuild task for improved performance and isolation.

		Depends on: `NuGet.Build.Tasks` and all transitive core libraries.

	See also the auto-generated [project overview](docs/project-overview.md), the [feature guide](docs/feature-guide.md), and the [coding guidelines](docs/coding-guidelines.md).
	See also [feature guide](docs/feature-guide.md), and the [coding guidelines](docs/coding-guidelines.md).


		These are the foundational libraries shared by all NuGet products. They are multi-targeted (`net472` and `net8.0`) and have no dependency on Visual Studio or any specific host.

		#### [`NuGet.Versioning`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Versioning/NuGet.Versioning.csproj)


		#### [`NuGet.PackageManagement`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.PackageManagement/NuGet.PackageManagement.csproj)

		Package management orchestration for install/uninstall/update flows (primarily used by the Visual Studio client and NuGet.exe `install`/`update` commands). Defines `NuGetPackageManager`, the abstract `NuGetProject` base class, and concrete project types like `MSBuildNuGetProject`, `FolderNuGetProject`, and `BuildIntegratedNuGetProject`. The `Audit/` subdirectory handles package vulnerability auditing.


		#### [`NuGet.Localization`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Core/NuGet.Localization/NuGet.Localization.csproj)

		Localization satellite assemblies for the dotnet CLI. Leaf dependency.


		#### [`NuGet.SolutionRestoreManager`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Clients/NuGet.SolutionRestoreManager/NuGet.SolutionRestoreManager.csproj)

		The second VS package. `RestoreManagerPackage` auto-loads when a solution is open and hooks into VS build events. `SolutionRestoreBuildHandler` triggers restore before build. `SolutionRestoreWorker` executes restore jobs. `VsSolutionRestoreService` exposes restore as a brokered service.


		Depends on: `NuGet.Commands`, `NuGet.PackageManagement`, `NuGet.VisualStudio`, `NuGet.VisualStudio.Internal.Contracts`, and core libraries.

		#### [`NuGet.VisualStudio`](https://github.com/NuGet/NuGet.Client/blob/dev/src/NuGet.Clients/NuGet.VisualStudio/NuGet.VisualStudio.csproj)


		### MEF Composition (VS)

		The VS extension uses MEF (Managed Extensibility Framework) extensively for service discovery and dependency injection. Key exports include `VSSolutionManager`, `ExtensibleSourceRepositoryProvider`, `NuGetUIFactory`, `VsPackageInstaller`, and the PowerShell console providers. Services are composed by VS's `SComponentModel`.

Conversation

aortiz-msft commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bug

Description

PR Checklist

Uh oh!

nkolev92 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nkolev92 Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nkolev92 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aortiz-msft commented Mar 23, 2026 •

edited

Loading

nkolev92 Mar 24, 2026 •

edited

Loading