# microsoft/windows-appsample-customers-orders-database architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/windows-appsample-customers-orders-database
- Repository: https://github.com/microsoft/windows-appsample-customers-orders-database

## Overview

##### Project type and purpose
- Project type: Full-stack desktop + cloud sample
- Purpose: A WinUI 3 (.NET 6) desktop client showcasing MVVM, Azure AD authentication, data access via repository pattern (SQLite or REST), backed by an ASP .NET Core 6 Web API and SQL database (LocalDB or Azure SQL).

##### File structure
- ContosoApp: WinUI 3 front-end using MVVM
- ContosoModels: Shared data models (Customer, Order, Product, etc.)
- ContosoRepository: Repository interfaces + two implementations—Sql (EF Core over SQLite/SQL Azure) and Rest (HTTP client to Web API)
- ContosoService: ASP .NET Core Web API (Controllers → EF Core DbContext → SQL database)
- Assets: Sample SQLite DB, SQL schema script
- Config files: appsettings.json (Service), Constants.cs (Repo endpoints & AAD client IDs)

##### README for additional insights
- Authentication: Azure AD via MSAL
- Patterns: MVVM in UI; Repository pattern abstracts data source; List/details and form layouts
- Technologies: WinUI 3, .NET 6, Entity Framework Core, ASP NET Core Web API, MSAL, SQLite, SQL Azure

##### Main components & relationships
a. Frontend (ContosoApp)
– MVVM layers: Views (XAML), ViewModels, UserControls
– MsalHelper → Azure AD for token acquisition
– RepositoryFactory chooses either SqlRepo or RestRepo based on user setting
b. Repository layer (ContosoRepository)
– IContosoRepository + specific interfaces (ICustomerRepository, etc.)
– Sql implementation (EF Core ⇒ ContosoContext ⇒ SQLite/SQL Azure)
– Rest implementation (HttpHelper ⇒ ASP NET Core Web API)
c. Backend Web API (ContosoService)
– Controllers (CustomerController, OrderController, ProductController)
– EF Core DbContext (SqlContosoRepository)
– Data store: SQL Azure or LocalDB
d. External services
– Azure Active Directory (authentication/authorization)
– Azure SQL (optional production DB)

##### Architectural patterns & design principles
- MVVM separates UI/ViewModels
- Repository pattern hides data-access details
- Dependency injection in Service and in ContosoApp (via factory or DI container)
- Token caching for MSAL desktop flows
- /details and responsive UI for Windows 11

##### Minimum elements
- Clear labels: Component names + technology

[User]
↓
[ContosoApp UI (WinUI 3)]───→[Authentication (MsalHelper)]───→[Azure AD]
│
└─→[ViewModels & UserControls]
│
↓
[RepositoryFactory]
├─→[SqlContosoRepository (EF Core)]───→[SQLite file or SQL Azure DB]
└─→[RestContosoRepository (HTTP/JSON)]───→[ContosoService Web API]───→[EF Core DbContext]───→[SQL Azure or LocalDB]

- UI layer (blue)
- Auth (green)
- Data layer (orange)
- External/Cloud (gray)

## Diagram (Mermaid)

```mermaid
graph TB
  %% User Layer
  User["User"]:::external
  User --> ContosoAppUI

  %% Frontend Layer
  subgraph "ContosoApp (WinUI 3 MVVM Client)" 
    direction TB
    ContosoAppUI["ContosoApp UI\n(App.xaml, MainWindow.xaml)"]:::ui
    Views["Views\n(CustomerListPage.xaml, OrderListPage.xaml, …)"]:::ui
    ViewModels["ViewModels\n(AuthenticationViewModel.cs, MainViewModel.cs, …)"]:::ui
    UserControls["UserControls\n(AuthenticationControl, CollapsibleSearchBox)"]:::ui
    MsalHelper["MsalHelper\n(Azure AD token)"]:::auth
    RepositoryFactory["RepositoryFactory"]:::logic
    AssetsDB["SQLite DB\nContoso.db"]:::data
    AssetsSchema["DB Schema\nContosoDb.sql"]:::data
  end

  ContosoAppUI -->|uses| Views
  ContosoAppUI -->|binds to| ViewModels
  ContosoAppUI -->|contains| UserControls
  ContosoAppUI -->|acquires token via| MsalHelper
  ContosoAppUI -->|chooses repo via| RepositoryFactory

  %% Repository Layer
  subgraph "ContosoRepository (Repository Layer)"
    direction TB
    RepoInterfaces["IContosoRepository & Entity Interfaces"]:::logic
    SqlRepo["SqlContosoRepository\n(EF Core)"]:::data
    RestRepo["RestContosoRepository\n(HTTP/JSON)"]:::data
  end

  RepositoryFactory -->|implements| RepoInterfaces
  RepositoryFactory -->|creates| SqlRepo
  RepositoryFactory -->|creates| RestRepo

  SqlRepo -->|reads/writes| AssetsDB
  SqlRepo -->|reads/writes| AzureSQLRemote
  RestRepo -->|HTTP/JSON| WebAPI

  %% Backend API Layer
  subgraph "ContosoService (ASP.NET Core Web API)"
    direction TB
    WebAPI["Web API\n(Controllers)"]:::service
    DbContext["SqlContosoRepository DbContext"]:::data
    Configuration["appsettings.json"]:::service
  end

  WebAPI -->|uses EF Core| DbContext
  DbContext -->|connects to| AzureSQLRemote
  DbContext -->|connects to| LocalDB["LocalDB"]:::data

  %% External Services
  MsalHelper -->|MSAL/HTTPS| AzureAD["Azure Active Directory"]:::external
  DbContext -->|SQL| AzureSQLRemote["Azure SQL"]:::external

  %% Click Events
  click ContosoAppUI "https://github.com/microsoft/windows-appsample-customers-orders-database/blob/master/ContosoApp/App.xaml"
  click Views "https://github.com/microsoft/windows-appsample-customers-orders-database/tree/master/ContosoApp/Views"
  click ViewModels "https://github.com/microsoft/windows-appsample-customers-orders-database/tree/master/ContosoApp/ViewModels"
  click UserControls "https://github.com/microsoft/windows-appsample-customers-orders-database/tree/master/ContosoApp/UserControls"
  click MsalHelper "https://github.com/microsoft/windows-appsample-customers-orders-database/blob/master/ContosoApp/MsalHelper.cs"
  click AssetsDB "https://github.com/microsoft/windows-appsample-customers-orders-database/blob/master/ContosoApp/Assets/Contoso.db"
  click AssetsSchema "https://github.com/microsoft/windows-appsample-customers-orders-database/blob/master/ContosoApp/Assets/ContosoDb.sql"
  click SqlRepo "https://github.com/microsoft/windows-appsample-customers-orders-database/blob/master/ContosoRepository/Sql/SqlContosoRepository.cs"
  click RestRepo "https://github.com/microsoft/windows-appsample-customers-orders-database/blob/master/ContosoRepository/Rest/RestContosoRepository.cs"
  click WebAPI "https://github.com/microsoft/windows-appsample-customers-orders-database/blob/master/ContosoService/Program.cs"

  %% Styles
  classDef ui fill:#bbe1fa,stroke:#1b262c,color:#0f4c75;
  classDef logic fill:#ffd32a,stroke:#f9ed69,color:#30323d;
  classDef data fill:#ffba08,stroke:#faa307,color:#272343;
  classDef service fill:#9bf6ff,stroke:#48cae4,color:#03045e;
  classDef auth fill:#caffbf,stroke:#52b788,color:#1b4332;
  classDef external fill:#cccccc,stroke:#888888,color:#000000;
```
