# microsoft/winui-gallery architecture

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

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

## Overview

##### Project type and purpose
- This is a single‐solution, desktop “sample gallery” application for WinUI 3 and the Windows App SDK.
- Its goal is to demonstrate every WinUI control, style, adaptive layout, design guideline, accessibility feature, and sample code snippet in a navigable UI shell.

##### File structure
- Top‐level solution (WinUIGallery.sln) contains:
- ▶ WinUIGallery – the main app project (XAML pages, controls, assets, helpers, models, layouts, converters, styles, sample data/code)
- ▶ WinUIGallery.DesktopWap.Package – packaging project (appx manifests)
- ▶ tests/WinUIGallery.UnitTests – unit tests targeting core logic
- ▶ tests/WinUIGallery.UITests – UI automation tests
- There’s also a Tools folder (PowerShell scripts to sync samples), CI pipeline definitions (.pipelines/azure-pipelines.yml), and docs.

##### README insights
- Confirms it’s purely a client‐side WinUI 3 app.
- Emphasizes use of the Microsoft.UI.Xaml NuGet package, adaptive UI, design & accessibility guidance, and sample‐code loading.

##### Main components & their relationships
a. Presentation Layer (blue):
- App.xaml + App.xaml.cs (entry point)
- NavigationRootPage → NavigationView shell
- Pages/ (HomePage, AllControlsPage, SectionPage, ItemPage, SettingsPage, plus many sample pages)
- Controls/ (custom user controls and control examples)
b. View/Logic Layer (green):
- Helpers/ (navigation, suspension, theme, file loading, native interop)
- Converters/ (value converters for binding)
- Layouts/ (custom panel & layout logic)
- Models/ (Category, ControlInfoData, IconData)
c. Data Layer (orange):
- FileLoader (loads JSON into model objects)
- Samples/SampleCode (text snippets loaded on demand)
- Samples/SampleHelpers (code support for 3D scenes)
d. Packaging & Infrastructure (gray):
- WinUIGallery.DesktopWap.Package (appx manifests & packaging targets)
- Directory.Build.props/targets, common.props, net7.override.targets
- NuGet.config (WinUI and WindowsAppSDK feed)
- Azure Pipelines definitions (.pipelines/)
e. Test Harnesses (purple):
- UnitTests project (exercises Models, Helpers, Converters)
- UITests project (launches the packaged app via WinAppDriver or Appium, drives UI controls, verifies accessibility via AxeHelper)

##### Architectural patterns & design principles
- Layered architecture within a single process.
- XAML + code‐behind as “MVVM‐lite” (Views in XAML, logic in code‐behind or Helpers).
- Data‐driven pages: meta JSON → Model objects → bound to UI via Helpers/Converters.
- Modular organization: Controls, Helpers, Converters, Layouts, Models each live in their own folder.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        AppEntry["App.xaml + App.xaml.cs"]:::frontend
        NavShell["NavigationRootPage"]:::frontend
        PagesDir["Pages/"]:::frontend
        ControlsDir["Controls/"]:::frontend
        StylesDir["Styles/"]:::frontend
    end

    %% View/Logic Layer
    subgraph "View/Logic Layer"
        direction TB
        HelpersDir["Helpers/"]:::logic
        ConvertersDir["Converters/"]:::logic
        LayoutsDir["Layouts/"]:::logic
        ModelsDir["Models/"]:::logic
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataJsonDir["Samples/Data/"]:::data
        FileLoader["FileLoader"]:::data
        SampleCodeDir["Samples/SampleCode/"]:::data
        SampleHelpersDir["Samples/SampleHelpers/"]:::data
    end

    %% Packaging & Infrastructure
    subgraph "Packaging & Infrastructure"
        direction TB
        PackageProject["WinUIGallery.DesktopWap.Package"]:::infra
        AppxManifests["Package.appxmanifest + Package.Dev.appxmanifest"]:::infra
        BuildProps["Build Props & Targets"]:::infra
        CIPipelines["CI Pipeline Definitions"]:::infra
        NuGetConfig["nuget.config"]:::infra
        ToolsScripts["Tools/ PS Scripts"]:::infra
    end

    %% Test Harnesses
    subgraph "Test Harnesses"
        direction TB
        UnitTests["WinUIGallery.UnitTests"]:::test
        UITests["WinUIGallery.UITests"]:::test
    end

    %% External Dependencies
    ExternalSDK["WindowsAppSDK NuGet"]:::external
    VSBuild["Visual Studio Build Env"]:::external

    %% Connections
    AppEntry -->|"starts"| NavShell
    NavShell -->|"navigates to"| PagesDir
    PagesDir -->|"uses"| ControlsDir
    PagesDir -->|"applies"| StylesDir
    PagesDir -->|"binds via converter"| ConvertersDir
    ControlsDir -->|"uses"| ConvertersDir
    ConvertersDir -->|"maps to"| ModelsDir
    DataJsonDir -->|"loaded by"| FileLoader
    FileLoader -->|"populates"| ModelsDir
    SampleCodeDir -->|"loaded on demand"| PagesDir
    SampleHelpersDir -->|"supports samples"| PagesDir
    PackageProject -->|"includes manifests"| AppxManifests
    CIPipelines -->|"triggers build"| PackageProject
    BuildProps -->|"defines settings"| PackageProject
    NuGetConfig -->|"feeds packages"| PackageProject
    ToolsScripts -->|"sync samples for"| DataJsonDir
    UnitTests -->|"tests"| HelpersDir
    UnitTests -->|"tests"| ConvertersDir
    UnitTests -->|"tests"| ModelsDir
    UITests -->|"drives UI of"| PackageProject
    PackageProject -->|"deploys to"| VSBuild
    PackageProject -->|"uses SDK"| ExternalSDK

    %% Click Events
    click AppEntry "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/App.xaml"
    click AppEntry "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/App.xaml.cs"
    click NavShell "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/Pages/NavigationRootPage.xaml"
    click NavShell "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/Pages/NavigationRootPage.xaml.cs"
    click PagesDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Pages"
    click ControlsDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Controls"
    click StylesDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Styles"
    click HelpersDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Helpers"
    click ConvertersDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Converters"
    click LayoutsDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Layouts"
    click ModelsDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Models"
    click DataJsonDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Samples/Data"
    click SampleCodeDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Samples/SampleCode"
    click SampleHelpersDir "https://github.com/microsoft/winui-gallery/tree/main/WinUIGallery/Samples/SampleHelpers"
    click PackageProject "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/WinUIGallery.DesktopWap.Package.wapproj"
    click AppxManifests "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/Package.appxmanifest"
    click AppxManifests "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/Package.Dev.appxmanifest"
    click BuildProps "https://github.com/microsoft/winui-gallery/blob/main/Directory.Build.props"
    click BuildProps "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/Directory.Build.props"
    click BuildProps "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/Directory.Build.targets"
    click BuildProps "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/common.props"
    click BuildProps "https://github.com/microsoft/winui-gallery/blob/main/WinUIGallery/net7.override.targets"
    click CIPipelines "https://github.com/microsoft/winui-gallery/blob/main/.pipelines/azure-pipelines.yml"
    click CIPipelines "https://github.com/microsoft/winui-gallery/blob/main/.pipelines/WinUI-Gallery-OneBranch-Official.yml"
    click CIPipelines "https://github.com/microsoft/winui-gallery/blob/main/.pipelines/WinUI-Gallery-SyncMirror.yml"
    click NuGetConfig "https://github.com/microsoft/winui-gallery/blob/main/nuget.config"
    click ToolsScripts "https://github.com/microsoft/winui-gallery/blob/main/Tools/Get-LatestAddedSamples.ps1"
    click ToolsScripts "https://github.com/microsoft/winui-gallery/blob/main/Tools/Get-LatestUpdatedSamples.ps1"
    click UnitTests "https://github.com/microsoft/winui-gallery/blob/main/tests/WinUIGallery.UnitTests"
    click UITests "https://github.com/microsoft/winui-gallery/blob/main/tests/WinUIGallery.UITests"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef test fill:#9370DB,stroke:#333,stroke-width:1px
    classDef external fill:#F0E68C,stroke:#333,stroke-width:1px
```
