# windos/burnttoast architecture

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

- Interactive diagram: https://gitdiagram.com/windos/burnttoast
- Repository: https://github.com/windos/burnttoast

## Overview

##### Project type & purpose
- BurntToast is an open-source PowerShell **module/library** for constructing and displaying Windows 10/Server 2019 toast notifications from scripts.
- It exposes a set of public cmdlets (New-BurntToastNotification, New-BTAction, etc.) and uses private helper functions under the hood.
- It bundles .NET‐based UWP notification toolkits and provides installation via PowerShell Gallery or MSI.

##### File structure
- Core module in `BurntToast/`
- `Public/` → user-facing cmdlet functions
- `Private/` → internal helper scripts
- `lib/` → third-party dependencies (Microsoft.Toolkit.Uwp.Notifications, Microsoft.Windows.SDK.NET)
- `config.json` → module configuration
- `Examples/` → sample scripts exercising the module’s API
- `Tests/` → Pester tests validating each cmdlet
- `Installer/` → WiX project and MSI for manual installation
- CI/CD configs in `.github/workflows/` and `Azure-Pipelines/`
- `Tasks/` → build and packaging PowerShell scripts

##### Pull in README insights
- Module requires PowerShell v5+
- Uses Microsoft.Toolkit.Uwp.Notifications under the covers
- Publishes to PowerShell Gallery & GitHub Releases
- Provides examples and help text under `Help/`

##### Main components & their interactions
a. **User scripts** (Examples folder or any 3rd-party script)
↳ call →
b. **BurntToast Module** (loaded into PowerShell host)
– Public cmdlets (Public/*.ps1)
– Private helpers (Private/*.ps1)
– Config & assets (Images, en-US help, config.json)
↳ invoke →
c. **Notification Engine**
– Microsoft.Toolkit.Uwp.Notifications (NuGet under lib/)
– Microsoft.Windows.SDK.NET (for direct WinRT APIs)
↳ delegate to →
d. **Windows OS Notification Platform**
– Native COM/WinRT toast interfaces

e. **CI/CD & Packaging**
– GitHub Actions & Azure Pipelines
- Lint, Test (`Tests/` with Pester), Package Module
- Run `Tasks/build.ps1`, `Installer/src/BurntToast.wxs` → `.msi`
- Publish to PowerShell Gallery & GitHub Releases

##### Architectural patterns & principles
- **Modularity**: clear separation of Public vs. Private code
- **Dependency encapsulation**: bundles external UWP libraries in `lib/`
- **Test-driven**: 70+ Pester tests ensure cmdlet correctness
- **CI/CD**: automated build, test, packaging, publish pipelines

##### Detail
- That every Public cmdlet file maps to a Pester test script in `Tests/`
- `config.json` feeding default behaviors

- How end users or scripts call into BurntToast’s Public cmdlets
- How internal helpers and external UWP libraries collaborate to deliver a toast to Windows
- How examples and tests validate functionality
- How CI/CD builds, packages, and publishes the module and MSI installer

This level of granularity ensures you capture all essential architectural elements without over-simplifying.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Scripts
    UserScripts["User Scripts<br/>(Examples/)"]:::code
    click UserScripts "https://github.com/windos/burnttoast/tree/main/Examples/"

    %% Core Module
    subgraph "BurntToast Module"
        direction TB
        Manifest["Module Manifest & EntryPoint<br/>(BurntToast.psd1<br/>BurntToast.psm1)"]:::code
        click Manifest "https://github.com/windos/burnttoast/blob/main/BurntToast/BurntToast.psd1"
        click Manifest "https://github.com/windos/burnttoast/blob/main/BurntToast/BurntToast.psm1"

        subgraph "Public vs Private"
            direction TB
            PublicCmdlets["Public Cmdlets<br/>(Public/*.ps1)"]:::code
            click PublicCmdlets "https://github.com/windos/burnttoast/blob/main/BurntToast/Public/*.ps1"
            PrivateHelpers["Private Helpers<br/>(Private/*.ps1)"]:::code
            click PrivateHelpers "https://github.com/windos/burnttoast/blob/main/BurntToast/Private/*.ps1"
        end

        Config["Module Configuration<br/>(config.json)"]:::code
        click Config "https://github.com/windos/burnttoast/blob/main/BurntToast/config.json"
        Images["Image Assets<br/>(Images/)"]:::code
        click Images "https://github.com/windos/burnttoast/tree/main/BurntToast/Images/"
        HelpFile["Localized Help File<br/>(en-us/about_BurntToast.help.txt)"]:::code
        click HelpFile "https://github.com/windos/burnttoast/blob/main/BurntToast/en-us/about_BurntToast.help.txt"
    end

    %% External Libraries
    subgraph "External UWP Libraries"
        direction TB
        UWPToolkit["Microsoft.Toolkit.Uwp.Notifications"]:::external
        click UWPToolkit "https://github.com/windos/burnttoast/tree/main/BurntToast/lib/Microsoft.Toolkit.Uwp.Notifications/"
        WindowsSDK["Microsoft.Windows.SDK.NET"]:::external
        click WindowsSDK "https://github.com/windos/burnttoast/tree/main/BurntToast/lib/Microsoft.Windows.SDK.NET/"
    end

    %% Windows OS Platform
    WindowsOS["Windows OS Notification Platform"]:::runtime

    %% Tests
    Tests["Pester Test Suite<br/>(Tests/*.Tests.ps1,<br/>_envPrep.ps1)"]:::code
    click Tests "https://github.com/windos/burnttoast/blob/main/Tests/*.Tests.ps1"
    click Tests "https://github.com/windos/burnttoast/blob/main/Tests/_envPrep.ps1"

    %% Help Documentation
    HelpDoc["Help Documentation<br/>(Help/)"]:::code
    click HelpDoc "https://github.com/windos/burnttoast/tree/main/Help/"

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging" 
        direction TB
        GitHubActions["GitHub Actions CI<br/>(.github/workflows/)"]:::ci
        click GitHubActions "https://github.com/windos/burnttoast/blob/main/.github/workflows/ci.yaml"
        AzurePipelines["Azure Pipelines Release<br/>(Azure-Pipelines/release.ps1)"]:::ci
        click AzurePipelines "https://github.com/windos/burnttoast/blob/main/Azure-Pipelines/release.ps1"
        BuildScripts["Build & Packaging Scripts<br/>(Tasks/)"]:::ci
        click BuildScripts "https://github.com/windos/burnttoast/blob/main/Tasks/build.ps1"
        click BuildScripts "https://github.com/windos/burnttoast/blob/main/Tasks/BurntToast-Template.psm1"
    end

    %% Installer
    subgraph "Installer"
        direction TB
        WiX["WiX Definition<br/>(Installer/src/BurntToast.wxs)"]:::ci
        click WiX "https://github.com/windos/burnttoast/blob/main/Installer/src/BurntToast.wxs"
        MSI["MSI Installer Artifact<br/>(Installer/BurntToast.msi)"]:::ci
        click MSI "https://github.com/windos/burnttoast/blob/main/Installer/BurntToast.msi"
    end

    %% Publishing
    PSGallery["Publish to PS Gallery"]:::ci
    GitHubReleases["Publish to GitHub Releases"]:::ci

    %% Connections
    UserScripts -->|"Invoke-Cmdlet"| PublicCmdlets
    PublicCmdlets -->|calls| PrivateHelpers
    PrivateHelpers -->|"leverages"| UWPToolkit
    PrivateHelpers -->|"leverages"| WindowsSDK
    UWPToolkit -->|"delegates to"| WindowsOS
    WindowsSDK -->|"delegates to"| WindowsOS

    Manifest --> PublicCmdlets
    Manifest --> PrivateHelpers
    Manifest --> Config
    Manifest --> Images
    Manifest --> HelpFile

    PublicCmdlets --> Tests
    PrivateHelpers --> Tests

    Manifest --> HelpDoc

    Tests -->|"Build & Test"| GitHubActions
    Tests -->|"Build & Test"| AzurePipelines
    Manifest -->|"Package Module"| BuildScripts
    BuildScripts -->|"Generate MSI"| WiX
    WiX -->|"Produces"| MSI

    BuildScripts -->|"Publish Module"| PSGallery
    GitHubActions -->|"Deploy"| PSGallery
    AzurePipelines -->|"Release"| GitHubReleases

    %% Styles
    classDef code fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef runtime fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    classDef ci fill:#ffe0b2,stroke:#ef6c00,color:#e65100
    classDef external fill:#e1bee7,stroke:#6a1b9a,color:#4a148c
```
