- You are onboarding a new developer
- You have been deep into one aspect of the system and need a refresher on another area
- You have been off the project for a while
- Whenever you are discussing requirements that may require structural changes
The architecture diagram is a technical document that demonstrates the technology in use. The purpose of the architecture diagram is to show how a solution has been built and what the technical dependencies are. It is not used for user journeys or business logic.
- Figure: Bad Example - a screenshot of the resources used helps, but doesn't show data flows or dependencies
Depending on the complexity of your solution and your comfort/familiarity with the tools, an architecture diagram could take you anywhere from half an hour to a couple of days.
Usually, the longer an architecture diagram takes you to make, the more important it is for your project.
- Matt Goldman
An architecture diagram is part of the 7 crucial documents you need for your project, see our rule: Do you make awesome documentation?
Tip 1: Include your most important components
At a minimum, your architecture diagram should include:
Your diagram needs to include the relationships between these components, and how they share and process data.
- Your data repository
- Your business logic component
- Your UI
Tip 2: Don't use a .NET Dependency Graph as a System Architecture Diagram
The .NET dependency diagram is a useful tool, but it drills down into a specific component of the solution (the code) while ignoring the rest of it (the infrastructure). If it adds value to your documentation (i.e., there is a specific reason to include it) you can include the .NET dependency diagram, but don't use it here in place of the architecture diagram.
See SSW rule: Do you generate the VS Dependency Graph?
- Figure: Bad Example - the .NET dependency diagram shows code dependencies, but not the application's architecture
Tip 3: Show data dependencies and data flowsYour architecture diagram should show how the components of your solution fit together. It should also show how the components of the architecture depend on each other for functionality, as well as upstream and downstream data dependencies.
- Figure: OK Example - Shows the technologies and data flows. Gives an overview of the whole application in one diagram.
Tip 4: Put data at the top
It should be easy to tell at a glance which direction data flows in your diagram: left to right, right to left,
top to bottom (recommended). Pick a direction for your data flow, and keep it consistent across all your documentation. Where there are exceptions (for example data going to analytics or to/from partner sources) make these perpendiculars to the primary data flow direction.
- Figure: Good example - SugarLearning (an Angular + .NET project) - data flows from top to bottom, with exceptions (e.g. App Insights / Raygun, not part of the main data flow) perpendicular to the primary direction
Tip 5: Group relevant components
Group components logically by enclosing them in a box. Components that operate independently can stand alone, and those that work together to deliver a logical function can be grouped together. This is also a good way to show components that are out of scope, i.e. important for understanding the architecture but not necessarily part of it, e.g. legacy components, partner components, or components that have not been implemented yet.
- Figure: Good example - SSW Rewards - consistent styling is used, e.g. as well as all the icons and typography being consistent, you can see that data is a solid line and auth traffic is a dotted line
Tip 6: Start with paper...
Make sure you use the right tools when creating your architecture diagrams. There's nothing wrong with starting out with pen and paper, but your hand-drawn sketch should not be considered your 'done' final architecture diagram.
- Figure: OK Example - SSW Rewards - start out with a hand-drawn sketch if that's easier for you, but don't consider this your final architecture diagram
Tip: Microsoft Office Lens is a free mobile app that uses your smartphone camera to capture scan-like images of documents, photographs, business cards, and whiteboards (including searchable handwritten text).
- Figure: Better Example - SSW Rewards - the same sketch but captured with Office Lens
Tip 7: ...and Finish up with Diagrams.net
The best tool for creating these diagrams is
diagrams.net (previously draw.io). All the examples on this page were created with this tool.
- Figure: Better Example - TimePro (an Angular + .NET project) - you can create diagrams quickly and easily with diagrams.net that still look very professional. This one is in the style of a technical document.
Diagrams.net is free, can be used in the browser, or can be downloaded as a desktop app. But the best way to use diagrams.net is to integrate it directly into VS Code.
- Figure: Great Example - Auctions (a Blazor + .NET project) - diagrams.net integrated directly into VS Code
There are multiple extensions available that let you do this, the best one is
Draw.io Integration. This makes it easy to create and edit system architecture diagrams right alongside your code, and check them in with the relevant commits.
- Figure: Good Example - Auctions (a Blazor + .NET project) - system architecture diagram created within VS Code and checked into the repo in the same commit as the relevant code changes. Blazor UI layer encapsulated in thematic color
Tip 8: Polish up Diagrams.net
Maintain standards to keep your diagrams consistent:
- Diagram heading: Takes the format of Architecture Diagram - [product name], and is in font size 43pts
- Use a standard font (e.g., at SSW we use Helvetica bold)
- Arrowhead sizes: 14pts
- Bottom left - add location (e.g. DevOps | Wiki or GitHub | Repo | Docs) in font size 22pts
- Bottom right - add branding and URL in font size 22pts
- Add color and icons to make your diagrams engaging and easier to distinguish
- Figure: Good Example - SSW People (a Static Site - Gatsby and React) - you can just as easily create colorful, engaging diagrams suitable for all of your project stakeholders