What you'll learn

Maintaining up-to-date architecture documentation is a challenge that plagues many development teams. In this guide, I'll show you how to leverage GitHub Copilot to automatically generate and maintain beautiful architecture diagrams using Mermaid syntax. This approach eliminates manual diagramming work while ensuring your architecture documentation stays accurate as your codebase evolves.

I'll also share how I used this approach when joining a project: combining Copilot's local code analysis with GitHub MCP to trace events across repositories and turn those connections into a Mermaid diagram.

Why it matters

Architecture diagrams are essential for understanding complex systems, onboarding new team members, and making informed design decisions. Yet they often become outdated almost as soon as they're created, as code changes but diagrams don't. This disconnect leads to confusion, misaligned development efforts, and wasted time.

By using GitHub Copilot to analyze your codebase and generate Mermaid diagrams, you can:

  • Ensure documentation accurately reflects your current architecture
  • Automatically update diagrams when the codebase structure changes
  • Save hours of manual diagramming work
  • Standardize architectural representation across your organization
  • Facilitate better communication between development teams and stakeholders

This approach transforms architecture documentation from a tedious maintenance burden into a dynamic, up-to-date resource that genuinely adds value to your development process.

Implementation

Real-World Case Study: Understanding a New Project Through Its Events

When I joined a project, I needed to understand how our service fitted into the wider system. Reading our repository was only part of the picture. Where did the events we published go? And which services published the events we consumed?

I asked GitHub Copilot to find the outgoing events in our repository. Then, using the GitHub MCP server, I asked it to search other repositories for their consumers. We also worked in reverse: starting with the events our service consumed and finding their publishers.

Those connections helped us quickly understand the flows. We then used the findings to generate an architecture diagram with Mermaid. Instead of looking at one repository in isolation, we could see how it connected to the rest of the system.

Here is a reusable version of that workflow. The prompts and service names below are illustrative, not details from that project.

1. Inventory Events in the Current Repository

Start with the code you have open. Ask for publishing and handling code, not just event class names: a shared contract or a test fixture alone does not prove that a service publishes or consumes an event.

markdown


Analyze this repository to inventory its outgoing and incoming integration events.
Do not modify code.

1. Find outgoing events and the code paths that publish them.
2. Find incoming events, their handlers, and consumer registrations.
3. Inspect messaging configuration for topics, queues, subscriptions, routing keys,
   and serialized event names or versions where available.
4. Distinguish cross-service integration events from in-process notifications,
   contract-only references, and tests.

Return a table with:
Direction | Event contract and version | Publisher or handler | Messaging destination |
Repository-relative file path and line numbers | Uncertainties

Do not assume that an event type declaration means the event is actually used.
      
2. Use GitHub MCP to Trace Both Sides of Each Event

Connect Copilot to the GitHub MCP server and enable its repository search and file-reading tools. Use your organization's approved Copilot and MCP setup, with access only to repositories you are authorized to inspect; prefer read-only tools for this investigation. MCP does not bypass GitHub permissions.

Replace the organization and repository placeholders below with your approved search scope. Copilot can use GitHub MCP to search beyond the local workspace and inspect the matching files.

markdown


Using the event inventory above and GitHub MCP, trace integration events across
the authorized repositories in YOUR_ORG. Limit searches to this repository list:
YOUR_ORG/service-a, YOUR_ORG/service-b, YOUR_ORG/service-c.
Use read-only tools; do not modify repositories.

For every outgoing event from our service:
- Find consumers in the allowed repositories.
- Inspect handler implementations, registrations, and messaging configuration.

For every incoming event handled by our service:
- Find its publishers in the allowed repositories.
- Inspect the publish call sites and messaging configuration.

Search using the exact event name, namespace, serialized name, version, and
destination where known. Do not equate matching class names with a confirmed flow.
Check contract compatibility and routing configuration on both sides.

Return an evidence table:
Publisher repository | Event | Topic or queue | Consumer repository |
Publish-site link | Handler and registration links | Configuration links |
Status (confirmed in code / candidate / unresolved)

Include the inspected branch or commit for each repository.
Report inaccessible repositories and search limitations explicitly.
No search results means "not found within this search scope," not "no consumers."
      
3. Turn the Evidence into a Mermaid Diagram

Once you have the evidence table, ask Copilot to draw the relationships. Keep uncertain connections separate so that a plausible guess does not become an architectural fact.

markdown


Generate a Mermaid flowchart from the evidence table.
Show the current service, upstream publishers, downstream consumers, and the
verified messaging destinations between them. Label connections with event names.
Include only relationships confirmed in code in the main diagram.
List candidates and unresolved events separately with the evidence still needed.

Add a short explanation of each flow and its source links.
Do not infer that handling one event causes another event to be published unless
the implementation establishes that relationship.
State that this is a code-derived view, not proof of production message delivery.
      

For example, an illustrative map centred on an Order Service might look like this. Topic names are placeholders; use the destinations verified in your own configuration. Copy the Mermaid block into a Markdown viewer that supports Mermaid to render it.

markdown


```mermaid
flowchart LR
    Payment["Payment Service"]
    PaymentEvents["Payment events topic"]
    Orders["Order Service - current repository"]
    OrderEvents["Order events topic"]
    Inventory["Inventory Service"]
    Notifications["Notification Service"]

    Payment -->|"PaymentCompleted"| PaymentEvents
    PaymentEvents -->|"PaymentCompleted"| Orders
    Orders -->|"OrderPlaced"| OrderEvents
    OrderEvents -->|"OrderPlaced"| Inventory
    OrderEvents -->|"OrderPlaced"| Notifications
```
      

Read this as two relationships: Order Service consumes PaymentCompleted from Payment Service, and publishes OrderPlaced for Inventory and Notification services. It does not claim that receiving PaymentCompleted triggers OrderPlaced, or imply any ordering between them.

Before treating the map as a reference, review the publish sites, handler registrations, and routing configuration with the team. Source code shows intended connections; environment-specific configuration and runtime telemetry are needed to verify what is deployed and actually delivering messages.

The value for us was not just a diagram. It was a quicker way to build a shared understanding of an unfamiliar system: start with events, follow them across repository boundaries, then visualize the evidence.

Setting Up Your Architecture Documentation Process

Let's set up a system for maintaining architecture documentation using GitHub Copilot. The key to success is creating a well-structured prompt that guides Copilot to analyze your codebase and generate accurate diagrams.

Step 1: Create an Architecture Documentation Prompt

First, create a specialized prompt file to guide GitHub Copilot. Save this as a markdown file in your project (e.g., architecture-documentation-prompt.md):

markdown


# Architecture Documentation & Maintenance Prompt for ILoveDotNet

As an expert software architect and documentation specialist familiar with .NET applications, assist me with 
analyzing and documenting my ILoveDotNet codebase architecture using the following approaches:

## PERSONA
You are a skilled software architect with deep knowledge of .NET ecosystems who can visualize complex systems 
and maintain technical documentation. You understand Blazor WASM, MAUI, and component-based architectures.

## INSTRUCTIONS
Analyze my ILoveDotNet codebase to create visual representations of the architecture and help maintain 
documentation that reflects the current state of the project.

## Task 1: Building Architecture Diagrams from Code

Please perform the following tasks in sequence:

1. **Analyze Application Structure**
   - Examine the entire ILoveDotNet.slnx structure including all projects
   - Focus on both Web (Blazor WASM) and MAUI projects as the main entry points
   - Analyze how component libraries are organized and referenced
   - Identify key services and their dependencies
   - Understand the lazy loading mechanism for Blazor components
   - Document how the application handles cross-platform deployment

2. **Create Visual Representation**
   - Show the structure visually using Mermaid syntax
   - Create these three specific diagrams:
     1. Project structure diagram - showing how projects relate to each other
     2. Component interaction diagram - showing the runtime flow including lazy loading
     3. Deployment architecture diagram - showing how the app is built and deployed
   - Ensure all diagrams use valid Mermaid syntax with appropriate styling
   - Show clear relationships between components with proper node labels

3. **Document Architecture Visually**
   - Create a new file or update existing file at `docs/Architecture.md`
   - Include all Mermaid diagrams from step 2
   - Add explanatory text between diagrams
   - Include sections for Key Architectural Characteristics, Component Types, and Technical Implementation

4. **Track Architectural Changes**
   - Use git commands to identify recent structural changes in the codebase
   - Check for new projects, removed projects, or changes to project relationships
   - Update all affected diagrams to accurately reflect the current state
   - Preserve diagram styling and formatting
   - Note any significant architectural shifts or patterns introduced

## Task 2: Maintaining Documentation

Please help maintain project documentation with these specific tasks:

1. **Analyze Recent Commits**
   - Find all Git commits since tag vX.X.X for the current repo
   - Provide a categorized summary of changes (features, fixes, refactoring, etc.)

2. **Deep Code Change Analysis**
   - Discover all code changes for all commits since vX.X.X
   - Provide a categorized summary based on actual code changes, not just commit messages
   - Highlight architectural changes, new patterns introduced, and significant refactorings

3. **Generate Release Notes**
   - Use all commits since vX.X.X
   - Follow the release note template in RELEASE_TEMPLATE.md
   - Generate a draft release_notes.md file

4. **Version Management**
   - Commit the release notes with an appropriate tag of vX.X.X
   - Ensure the version is correctly incremented according to semantic versioning

## FORMAT
Provide results in markdown format with appropriate sections, code blocks, and Mermaid diagrams where applicable.
      

This prompt creates a persona for GitHub Copilot to follow, with specific instructions for analyzing your codebase and generating architecture diagrams. It focuses on three key diagram types: project structure, component interaction, and deployment architecture.

Step 2: Initial Architecture Documentation Generation

With your prompt file ready, you can now use GitHub Copilot Chat to generate your initial architecture documentation:

  1. Open GitHub Copilot Chat in your editor (typically with Ctrl+Shift+I or click the Copilot icon)
  2. Send a prompt like this, referencing your detailed prompt file:
markdown


Please analyze my codebase following the instructions in architecture-documentation-prompt.md and create an 
architecture documentation file with Mermaid diagrams showing the project structure, component interactions, and deployment process.
      

GitHub Copilot will examine your code structure, analyze dependencies, and generate the architecture documentation with appropriate Mermaid diagrams. The output might look something like this:

markdown


# ILoveDotNet Application Architecture

This document provides a visual representation of the ILoveDotNet 
application architecture using Mermaid diagrams.

## Project Structure

The following diagram illustrates the high-level project structure and 
relationships between the main components:

```mermaid
graph TB
    subgraph "Entry Points"
        Web["Web Project
(Blazor WASM)"] MAUI["MAUI Project
(Cross-platform native app)"] end subgraph "Core Components" BaseComponents["BaseComponents
(Core UI elements)"] CommonComponents["CommonComponents
(Shared UI elements)"] SharedComponents["SharedComponents
(Utility components)"] SharedModels["SharedModels
(Data models)"] end subgraph "Demo Components" AIDemoComponents["AIDemoComponents"] BlazorDemo["BlazorDemoComponents"] LINQDemo["LINQDemoComponents"] DIDemoComponents["DependencyInjectionDemoComponents"] DesignPatternDemo["DesignPatternDemoComponents"] OOPSDemo["OOPSDemoComponents"] RegexDemo["RegexDemoComponents"] ReportDemo["ReportDemoComponents"] HTTPDemo["HTTPClientDemoComponents"] MiddlewareDemo["MiddlewareDemoComponents"] MLNETDemo["MLNETDemoComponents"] WebAPIDemo["WebAPIDemoComponents"] MAUIDemo["MAUIDemoComponents"] MSBuildDemo["MSBuildDemoComponents"] OWASPDemo["OWASPDemoComponents"] SignalRDemo["SignalRDemoComponents"] SOLIDDemo["SOLIDDemoComponents"] TDDDemo["TDDDemoComponents"] TestingDemo["TestingDemoComponents"] PythonDemo["PythonDemoComponents"] TalkDemo["TalkDemoComponents"] end %% Component dependencies and relationships... ```

Step 3: Maintaining and Updating Architecture Documentation

As your project evolves, you'll need to keep your architecture documentation up-to-date. GitHub Copilot makes this easy:

markdown


Look at the last Git commit I did to see what changed structurally in the codebase. Update my Mermaid 
architecture diagram accordingly.
      

Copilot will analyze recent changes and update the diagrams to reflect the current state of your codebase. For example, when I asked Copilot to update our architecture diagram after recent changes, it identified a new AI component and updated the diagram:

diff


graph TB
    subgraph "Entry Points"
        Web["Web Project
(Blazor WASM)"] MAUI["MAUI Project
(Cross-platform native app)"] end subgraph "Core Components" BaseComponents["BaseComponents
(Core UI elements)"] CommonComponents["CommonComponents
(Shared UI elements)"] SharedComponents["SharedComponents
(Utility components)"] SharedModels["SharedModels
(Data models)"] + AIServices["AIServices
(AI Integration)"] end subgraph "Demo Components" AIDemoComponents["AIDemoComponents"] + CopilotDemos["CopilotDemoComponents"] BlazorDemo["BlazorDemoComponents"] // ...other demo components... end

Step 4: Setting Up Automated Documentation Updates

For an even more streamlined approach, you can automate architecture documentation updates using GitHub Actions:

yaml


name: Update Architecture Documentation

on:
  push:
    branches: [ main ]
    paths:
      - '**/*.csproj'
      - '**/*.sln'
      - 'docs/Architecture.md'

jobs:
  update-architecture:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      
      # Conceptual step: run your custom architecture-update script here.
      # For example, a Python/Node script that calls an AI API to regenerate
      # docs/Architecture.md based on the current codebase structure.
      - name: Update architecture documentation
        run: |
          echo "Running custom architecture documentation update script..."
          # node scripts/update-architecture.js
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Commit changes if needed
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add docs/Architecture.md
          if git diff --staged --quiet; then
            echo "No changes to commit"
          else
            git commit -m "📝 Update architecture documentation"
            git push
          fi
      

This workflow automatically triggers when project files change. The "Update architecture documentation" step is a placeholder for your own custom script—for example a Node.js or Python script that calls an AI API to regenerate docs/Architecture.md based on the current codebase.

Customizing Diagram Styles

You can enhance your Mermaid diagrams with customized styling for better readability:

markdown


Please update my architecture diagram with the following style enhancements:
1. Use color coding for different component types (core, demo, utilities)
2. Add clearer relationship labels
3. Improve the layout for better readability
      

Copilot will then apply professional styling to your diagrams:

markdown


%% Layout control
classDef entryPoint fill:#f96,stroke:#333,stroke-width:2px
classDef coreComponent fill:#bbf,stroke:#333,stroke-width:1px
classDef demoComponent fill:#bfb,stroke:#333,stroke-width:1px
classDef utility fill:#fbb,stroke:#333,stroke-width:1px
classDef testing fill:#fcf,stroke:#333,stroke-width:1px
classDef buildUtil fill:#cff,stroke:#333,stroke-width:1px

class Web,MAUI entryPoint
class BaseComponents,CommonComponents,SharedComponents,SharedModels coreComponent
class AIDemoComponents,BlazorDemo,LINQDemo,DIDemoComponents,
      DesignPatternDemo,OOPSDemo,RegexDemo,ReportDemo,HTTPDemo,
      MiddlewareDemo,MLNETDemo,WebAPIDemo,MAUIDemo,MSBuildDemo,
      OWASPDemo,SignalRDemo,SOLIDDemo,TDDDemo,TestingDemo,
      PythonDemo,TalkDemo demoComponent
      

Documenting Architectural Decisions

In addition to diagrams, you can ask Copilot to document key architectural decisions:

markdown


Based on the codebase analysis, document the key architectural characteristics and decisions that 
shaped this project.
      

Copilot will generate explanatory content about your architecture:

markdown


## Key Architectural Characteristics

1. **Modular Design**: The application is structured into multiple component
   libraries, each focusing on a specific aspect of .NET technology.

2. **Dual Entry Points**: 
   - **Web Project (Blazor WASM)**: For browser-based access
   - **MAUI Project**: For native application access across multiple platforms 
     (iOS, Android, macOS, Windows)
   - **MAUI as a Shell**: The MAUI project uses BlazorWebView to render the 
     same Blazor WASM components as the Web project but inside a native 
     application shell, providing access to native platform features while 
     maintaining a unified codebase

3. **Lazy Loading**: Components are loaded on-demand to optimize initial load 
   time and performance.

4. **Shared Component Model**: Both entry points share the same component 
   libraries, maximizing code reuse.
      

Analyzing Changes Between Versions

For projects with version tags, you can analyze architectural changes between releases:

markdown


Find all architectural changes between v1.0.0 and v2.0.0 and generate a summary of how the system 
structure evolved.
      

This helps maintain a record of how your architecture evolves over time.

Real-World Example: Updating ILoveDotNet Architecture

Let's look at a real example of how I used GitHub Copilot to update the ILoveDotNet architecture documentation. I recently added a new AI learning path to the project, which included new components for GitHub Copilot integration.

I asked Copilot to update our architecture diagram:

markdown


Analyze the recent addition of the AI learning path and Copilot components to the ILoveDotNet codebase. 
Update the architecture diagrams in docs/Architecture.md to reflect these changes while maintaining the existing formatting and style.
      

Copilot analyzed the changes and updated the diagrams, adding new nodes for the AI components and updating the relationships. Here's an excerpt of what changed:

diff


subgraph "Demo Components" 
+       AIDemoComponents["AIDemoComponents"]
        BlazorDemo["BlazorDemoComponents"]
        LINQDemo["LINQDemoComponents"]
        // ...other components...
    end

    %% Component dependencies
    BaseComponents --> SharedModels
    SharedComponents --> SharedModels
    CommonComponents --> BaseComponents
    CommonComponents --> SharedComponents
    
    %% Entry point dependencies
    Web --> CommonComponents
    Web --> SharedComponents
    Web --> SharedModels
      

Copilot also updated the deployment diagram to reflect how the new AI components are integrated:

diff


flowchart TD
    subgraph "Development"
        Dev["Developer Workstation"]
        GitHub["GitHub Repository"]
+       CopilotExtension["GitHub Copilot Extension"]
    end
    
    subgraph "CI/CD"
        Actions["GitHub Actions"]
        BuildWeb["Build Web App"]
        BuildMAUI["Build MAUI Apps"]
        Tests["Run Tests"]
        // ...other elements...
    end
      

The result is always a professionally updated architecture document that accurately reflects the current state of the codebase, with minimal manual effort.

The final architecture documentation will look like this:

markdown


# ILoveDotNet Application Architecture

This document provides a visual representation of the ILoveDotNet application architecture using Mermaid diagrams.

## Project Structure

The following diagram illustrates the high-level project structure and relationships between the main components:

```mermaid
graph TB
    subgraph "Entry Points"
        Web["Web Project
(Blazor WASM)"] MAUI["MAUI Project
(Cross-platform native app)"] end subgraph "Core Components" BaseComponents["BaseComponents
(Core UI elements)"] CommonComponents["CommonComponents
(Shared UI elements)"] SharedComponents["SharedComponents
(Utility components)"] SharedModels["SharedModels
(Data models)"] end subgraph "Demo Components" AIDemoComponents["AIDemoComponents"] BlazorDemo["BlazorDemoComponents"] LINQDemo["LINQDemoComponents"] DIDemoComponents["DependencyInjectionDemoComponents"] DesignPatternDemo["DesignPatternDemoComponents"] OOPSDemo["OOPSDemoComponents"] RegexDemo["RegexDemoComponents"] ReportDemo["ReportDemoComponents"] HTTPDemo["HTTPClientDemoComponents"] MiddlewareDemo["MiddlewareDemoComponents"] MLNETDemo["MLNETDemoComponents"] WebAPIDemo["WebAPIDemoComponents"] MAUIDemo["MAUIDemoComponents"] MSBuildDemo["MSBuildDemoComponents"] OWASPDemo["OWASPDemoComponents"] SignalRDemo["SignalRDemoComponents"] SOLIDDemo["SOLIDDemoComponents"] TDDDemo["TDDDemoComponents"] TestingDemo["TestingDemoComponents"] PythonDemo["PythonDemoComponents"] TalkDemo["TalkDemoComponents"] end subgraph "Testing & Utilities" subgraph "Testing" UITests["UI Tests
(bUnit/XUnit)"] EndToEndTests["E2E Tests
(Playwright/NUnit)"] end subgraph "Build & Documentation" RSSFeedGenerator["RSS Feed Generator"] SitemapGenerator["Sitemap Generator"] ArchitectureDocs["Architecture Documentation
(AI-assisted)"] end end %% Component dependencies BaseComponents --> SharedModels SharedComponents --> SharedModels CommonComponents --> BaseComponents CommonComponents --> SharedComponents %% Demo component dependencies AIDemoComponents --> BaseComponents AIDemoComponents --> SharedComponents BlazorDemo --> BaseComponents BlazorDemo --> SharedComponents LINQDemo --> BaseComponents LINQDemo --> SharedComponents DIDemoComponents --> BaseComponents DIDemoComponents --> SharedComponents DesignPatternDemo --> BaseComponents DesignPatternDemo --> SharedComponents OOPSDemo --> BaseComponents OOPSDemo --> SharedComponents RegexDemo --> BaseComponents RegexDemo --> SharedComponents ReportDemo --> BaseComponents ReportDemo --> SharedComponents HTTPDemo --> BaseComponents HTTPDemo --> SharedComponents MiddlewareDemo --> BaseComponents MiddlewareDemo --> SharedComponents MLNETDemo --> BaseComponents MLNETDemo --> SharedComponents WebAPIDemo --> BaseComponents WebAPIDemo --> SharedComponents MAUIDemo --> BaseComponents MAUIDemo --> SharedComponents MSBuildDemo --> BaseComponents MSBuildDemo --> SharedComponents OWASPDemo --> BaseComponents OWASPDemo --> SharedComponents SignalRDemo --> BaseComponents SignalRDemo --> SharedComponents SOLIDDemo --> BaseComponents SOLIDDemo --> SharedComponents TDDDemo --> BaseComponents TDDDemo --> SharedComponents TestingDemo --> BaseComponents TestingDemo --> SharedComponents PythonDemo --> BaseComponents PythonDemo --> SharedComponents TalkDemo --> BaseComponents TalkDemo --> SharedComponents %% Entry point dependencies Web --> CommonComponents Web --> SharedComponents Web --> SharedModels Web --> AIDemoComponents Web --> BlazorDemo Web --> LINQDemo Web --> DIDemoComponents Web --> DesignPatternDemo Web --> OOPSDemo Web --> RegexDemo Web --> ReportDemo Web --> HTTPDemo Web --> MiddlewareDemo Web --> MLNETDemo Web --> WebAPIDemo Web --> MAUIDemo Web --> MSBuildDemo Web --> OWASPDemo Web --> SignalRDemo Web --> SOLIDDemo Web --> TDDDemo Web --> TestingDemo Web --> PythonDemo Web --> TalkDemo MAUI --> CommonComponents MAUI --> SharedComponents MAUI --> SharedModels MAUI --> AIDemoComponents MAUI --> BlazorDemo MAUI --> LINQDemo MAUI --> DIDemoComponents MAUI --> DesignPatternDemo MAUI --> OOPSDemo MAUI --> RegexDemo MAUI --> ReportDemo MAUI --> HTTPDemo MAUI --> MiddlewareDemo MAUI --> MLNETDemo MAUI --> WebAPIDemo MAUI --> MAUIDemo MAUI --> MSBuildDemo MAUI --> OWASPDemo MAUI --> SignalRDemo MAUI --> SOLIDDemo MAUI --> TDDDemo MAUI --> TestingDemo MAUI --> PythonDemo MAUI --> TalkDemo %% Testing dependencies UITests --> CommonComponents RSSFeedGenerator --> SharedModels SitemapGenerator --> SharedModels %% Layout control classDef entryPoint fill:#f96,stroke:#333,stroke-width:2px classDef coreComponent fill:#bbf,stroke:#333,stroke-width:1px classDef demoComponent fill:#bfb,stroke:#333,stroke-width:1px classDef utility fill:#fbb,stroke:#333,stroke-width:1px classDef testing fill:#fcf,stroke:#333,stroke-width:1px classDef buildUtil fill:#cff,stroke:#333,stroke-width:1px class Web,MAUI entryPoint class BaseComponents,CommonComponents,SharedComponents,SharedModels coreComponent class AIDemoComponents,BlazorDemo,LINQDemo,DIDemoComponents,DesignPatternDemo,OOPSDemo,RegexDemo,ReportDemo,HTTPDemo,MiddlewareDemo,MLNETDemo,WebAPIDemo,MAUIDemo,MSBuildDemo,OWASPDemo,SignalRDemo,SOLIDDemo,TDDDemo,TestingDemo,PythonDemo,TalkDemo demoComponent class UITests,EndToEndTests testing class RSSFeedGenerator,SitemapGenerator,ArchitectureDocs buildUtil ``` ## MAUI WebView Architecture The following diagram illustrates how MAUI.csproj uses BlazorWebView to render the same web content as the Web.csproj project but inside a native shell: ```mermaid flowchart TB subgraph "MAUI Native Application" MauiShell["MAUI Shell
(Native Container)"] BlazorWebView["BlazorWebView
(WebView Control)"] subgraph "Web Content (Same as Web.csproj)" Router["Router
(Routes.razor)"] MainLayout["MainLayout"] LazyLoading["Lazy Loading"] DemoComponents["Demo Components"] end MauiShell -->|"Hosts"| BlazorWebView BlazorWebView -->|"Renders"| Router Router --> MainLayout MainLayout --> LazyLoading LazyLoading --> DemoComponents end subgraph "Platform Native Features" Notifications["Native Notifications"] FileSystem["File System Access"] DeviceFeatures["Device Features"] end MauiShell -.->|"Provides access to"| Notifications MauiShell -.->|"Provides access to"| FileSystem MauiShell -.->|"Provides access to"| DeviceFeatures classDef native fill:#f96,stroke:#333,stroke-width:2px classDef webview fill:#bbf,stroke:#333,stroke-width:2px classDef webcontent fill:#bfb,stroke:#333,stroke-width:1px classDef platformfeatures fill:#fbb,stroke:#333,stroke-width:1px class MauiShell native class BlazorWebView webview class Router,MainLayout,LazyLoading,DemoComponents webcontent class Notifications,FileSystem,DeviceFeatures platformfeatures ``` ## Component Interaction and Lazy Loading The following sequence diagram illustrates how components interact and the lazy loading mechanism: ```mermaid sequenceDiagram participant User participant Browser participant Web as Web/MAUI Entry Point participant LazyLoader as Lazy Loader Service participant Components as Component Libraries participant JSInterop as JavaScript Interop User->>Browser: Open application Browser->>Web: Load initial resources Web->>LazyLoader: Initialize LazyLoader->>Web: Pre-load critical assemblies Web->>Browser: Render initial UI Note over User,Browser: User navigates to a topic User->>Browser: Click navigation link Browser->>Web: Navigate to route Web->>LazyLoader: OnNavigateAsync() LazyLoader->>Components: Load required assembly Components->>Web: Assembly loaded Web->>Browser: Render component Note over User,Browser: User interacts with demo User->>Browser: Interact with demo Browser->>Web: Component event Web->>JSInterop: Call JavaScript when needed JSInterop->>Browser: Execute client-side code Browser->>User: Display result ``` ## Deployment Architecture The following diagram shows the deployment process and targets: ```mermaid flowchart TD subgraph "Development" Dev["Developer Workstation"] GitHub["GitHub Repository"] CopilotExtension["GitHub Copilot
(AI Assistance)"] end subgraph "CI/CD" Actions["GitHub Actions"] BuildWeb["Build Web App"] BuildMAUI["Build MAUI Apps"] Tests["Run Tests"] subgraph "Testing" UITests["UI Tests
(bUnit/XUnit)"] E2ETests["E2E Tests
(Playwright/NUnit)"] end end subgraph "Deployment Targets" GHPages["GitHub Pages
(Web)"] AppStores["App Stores
(iOS/Android/Windows/macOS)"] Docker["Docker Container"] end Dev -->|Push Changes| GitHub Dev <-->|AI Code Assistance| CopilotExtension CopilotExtension -.->|Architecture Analysis| GitHub GitHub -->|Trigger Workflow| Actions Actions --> BuildWeb Actions --> BuildMAUI Actions --> Tests Tests --> UITests Tests --> E2ETests BuildWeb -->|Deploy| GHPages BuildMAUI -->|Publish| AppStores BuildWeb -->|Package| Docker classDef dev fill:#f9f,stroke:#333,stroke-width:1px classDef cicd fill:#ff9,stroke:#333,stroke-width:1px classDef deploy fill:#9ff,stroke:#333,stroke-width:1px classDef testing fill:#fcf,stroke:#333,stroke-width:1px class Dev,GitHub,CopilotExtension dev class Actions,BuildWeb,BuildMAUI,Tests cicd class GHPages,AppStores,Docker deploy class UITests,E2ETests testing ``` ## Key Architectural Characteristics 1. **Modular Design**: The application is structured into multiple component libraries, each focusing on a specific aspect of .NET technology. 2. **Dual Entry Points**: - **Web Project (Blazor WASM)**: For browser-based access - **MAUI Project**: For native application access across multiple platforms (iOS, Android, macOS, Windows) - **MAUI as a Shell**: The MAUI project uses BlazorWebView to render the same Blazor WASM components as the Web project but inside a native application shell, providing access to native platform features while maintaining a unified codebase 3. **Lazy Loading**: Components are loaded on-demand to optimize initial load time and performance. 4. **Shared Component Model**: Both entry points share the same component libraries, maximizing code reuse. 5. **JavaScript Interoperability**: Uses JSInterop for browser-native functionality when needed. 6. **Responsive Design**: Adapts to different screen sizes and platforms. 7. **CI/CD Integration**: Automated build and deployment through GitHub Actions. 8. **Testing**: Includes UI testing capabilities for ensuring quality. ## Component Types 1. **Core Components**: Basic building blocks used across the application - BaseComponents - CommonComponents - SharedComponents - SharedModels 2. **Demo Components**: Topic-specific components that demonstrate various .NET technologies - BlazorDemoComponents - LINQDemoComponents - DependencyInjectionDemoComponents - Many others (20+ topic areas) 3. **Utilities**: Supporting tools and services - RSSFeedGenerator - SitemapGenerator - UITests - EndToEndTests (Playwright) ## Technical Implementation - **Language**: C# with Razor components - **Framework**: .NET 10.0 with Blazor WebAssembly and .NET MAUI - **Styling**: CSS with custom classes - **JavaScript Integration**: Module-based JS isolation - **Testing**: XUnit with coverage reporting - **MAUI Implementation**: Uses BlazorWebView to host the same web components as the Web project inside a native shell, providing a unified experience with native platform capabilities ## Maintenance and Evolution This architecture documentation is maintained with the help of GitHub Copilot. As the codebase evolves, the diagrams and explanations are updated using AI-assisted analysis of code changes. This approach ensures that the documentation remains accurate and up-to-date with minimal manual effort. Key benefits of this approach include: - Automatic detection of structural changes in the codebase - Consistent diagram styling and formatting - Accurate representation of project relationships - Documentation that evolves alongside the code For more details on this process, see the blog post: [Using GitHub Copilot AI for Architecture Diagram Generation](https://ilovedotnet.org/blogs/using-github-copilot-ai-for-architecture-diagram-generation)
Architecture Visualisation with Copilot
Architecture Visualisation with Copilot

Summary

When joining an event-driven project, start by mapping the events your service publishes and consumes. Use GitHub MCP to find the other side of those relationships in authorized repositories, validate the code and configuration evidence, and ask Copilot to turn the confirmed connections into Mermaid. Keep unresolved connections visible rather than filling the gaps with guesses.

Using GitHub Copilot for architecture diagram generation transforms documentation from a tedious chore into an automated, accurate, and valuable part of your development process. By creating a well-structured prompt and incorporating it into your workflow, you can ensure your architecture diagrams always reflect the current state of your codebase.

This approach offers significant benefits: consistently up-to-date documentation, standardized visual representation, time savings, and improved communication across your team. As your project evolves, your architecture diagrams evolve with it, maintaining their value as a reference point for both new and existing team members.

For large, complex projects like ILoveDotNet with multiple interrelated components, maintaining accurate documentation manually would be nearly impossible. With GitHub Copilot, it becomes not just possible, but straightforward. Start implementing this approach in your projects today, and watch as your architecture documentation transforms from a burden into an asset.