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.
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.
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.
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.
```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):
# 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:
- Open GitHub Copilot Chat in your editor (typically with Ctrl+Shift+I or click the Copilot icon)
- Send a prompt like this, referencing your detailed prompt file:
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:
# 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:
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:
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:
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:
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:
%% 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:
Based on the codebase analysis, document the key architectural characteristics and decisions that
shaped this project.
Copilot will generate explanatory content about your architecture:
## 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:
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:
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:
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:
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:
# 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)
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.