Would contributor-facing architecture docs (doc/architecture/) be welcome?

[dimension-zero]

Hi maintainers — wanted to check with the team before opening a PR.

While orienting myself to the codebase, I drafted three contributor-facing architecture documents describing the design at a higher level than the existing doc/ content. The goal was to make it easier for new contributors to form an accurate picture without reading the full source.

Proposed location: doc/architecture/

• Architecture.md — project layering, source/package/version abstractions, the operator<< workflow composition pattern, ExecutionContext, COM surface, threading via ContextOrchestrator, REST protocol shape, and the installer security model.

• Configuration.md — the four-layer configuration precedence (Group Policy → admin settings → user settings → defaults), the admin_settings file format, and the DSC subsystem (ConfigurationSet / Unit / Processor, schema evolution).

• Data.md — storage layout under %LOCALAPPDATA% / %PROGRAMDATA% / %TEMP%, the role of each SQLite database (installed.db, pinning.db, config.db, index.db, checkpoints), the manifest cache, the ARP registry sources used to populate the installed catalog, and the install / source-update data flows.

The documents deliberately avoid line numbers, exact field counts, and version-pinned details that would rot. They cross-reference the existing docs — Settings.md, manifest.md, returnCodes.md, the policy reference, and the COM API spec — rather than duplicating content. The source of truth for specifics remains the code.

Draft branch (read-only browse):
https://github.com/dimension-zero/winget-cli/tree/performance-improvements/doc/architecture

A few questions before I invest more time:

1. Would architecture docs of this kind be welcome upstream?
2. Is doc/architecture/ the right location, or do you prefer somewhere else (or no subdirectory)?
3. Is there a maintainer willing to take ownership of keeping them current, or should they live somewhere clearly marked "contributor notes, not maintained"?
4. Any style or scope guidance beyond what's in CONTRIBUTING.md?

Thanks for taking a look.

[florelis]

I would love to have something like this. I skimmed through what you have in your branch and it looks super helpful. If we got this we would probably want to link to it from CONTRIBUTING.md. Maybe also include a mention in the PR template checklist to help remind us to keep it current.

I would change the name of Configuration.md to something closer to "settings" so that it would not be confused with the "configuration" feature (DSC). Maybe also change the name of the folder to make it clearer that those are dev docs, like doc/dev/