Using GitHub Copilot AI for Architecture Diagram Generation
Author - Abdul Rahman (Content Writer)
AI
3 Articles
Table of Contents
What we gonna do?
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.
Why we gonna do?
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.
How we gonna do?
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.sln 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@v3
with:
fetch-depth: 0
- name: Set up Node.js
uses: actions/setup-node@v3
with:
node-version: 16
- name: Install GitHub Copilot CLI
run: npm install -g @github/copilot-cli
- name: Update architecture documentation
run: |
echo "Analyzing code architecture changes..."
github-copilot-cli architecture-update
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, using GitHub Copilot CLI to update the architecture documentation.
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.
Summary
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.