Do you have an Architecture Diagram?

A good architecture diagram (aka a cloud architecture diagram or system architecture diagram) gives a great overview of your project. An architecture diagram lets you see at a glance what the overall structure of the solution is. This is useful for gaining an understanding of how the system fits together, how it flows, and what it does. It also helps to easily show which components can be improved due to updated or better components (or improved architectural guidelines).

<youtubeEmbed url="https://www.youtube.com/embed/ek8ArrOfJxA" description="" />

An architecture diagram is useful when:
* In the initial discussion with a client (see Brendan Richards' quote below)
* 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 diagram 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.

<asideEmbed
  variant="info"
  body={<>
    Check out the [8 Tips to Better Architecture Diagrams](https://adamcogan.com/2020/10/07/8-tips-to-better-architecture-diagrams/).
  </>}
  figureEmbed={{
    preset: "default",
    figure: 'XXX',
    shouldDisplay: false
  }}
/>

::: bad img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Bad example - A screenshot of the Azure resources used helps, but doesn\'t show data flows or dependencies',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/bad-azure-resource-screenshot.jpg"
/>
:::

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, Software Architect

An architecture diagram is part of the 7 crucial documents you need for your project, see our rule: [Do you make awesome documentation?](/do-you-review-the-documentation)

### Tip #1: Include your most important components

At a minimum, your architecture diagram should include:

* Your data repository
* Your business logic component
* Your UI

Your diagram needs to include the relationships between these components, and how they share and process data.

### Tip #2: Don't use a .NET Dependency Graph as a 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 dependency graphs?](/generate-dependency-graphs)

::: bad img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Bad example - The .NET dependency diagram shows code dependencies, but not the application\'s architecture',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/dependency-validation-01.png"
/>
:::

### Tip #3: Show data dependencies and data flows

Your 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.

::: ok img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'OK example - Shows the technologies and data flows (from the data --&gt; Azure Data Factory --&gt; Azure Databricks --&gt; Power BI). This gives an overview of the whole application in one diagram.',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/architecture-diagram-good1.png"
/>
:::

### Tip #4: Put data at the top

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 perpendicular to the primary data flow direction.

It should be easy to tell at a glance which direction data flows in your diagram - **top to bottom is recommended**.

::: good img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Good example - SugarLearning (an Angular + .NET project) - data flows from top to bottom, with exceptions (e.g. Application Insights / Raygun, not part of the main data flow) perpendicular to the primary direction',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/sugarlearning-architecture-diagram.png"
/>
:::

### 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. Also 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.

**Note:** For clarity, out of scope items whether one or many, should be in a box.

::: good img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Good example - SSW Rewards (Xamarin with Entra ID B2C) - 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',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/rewards-architecture-diagram.png"
/>
:::

### 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. If you want to save paper, and increase collaboration, a great alternative is the trusty old whiteboard.

For me its all about building a shared understanding between the client and the developers. Most pieces of software architecture I do, work starts by building a rough solution architecture diagram on a whiteboard.

Putting something on a whiteboard is "low risk" for the participants as its really easy to wipe and redraw. It allows us to start working together straight away, building a shared understanding of what we're trying to achieve. There is no software or skills required to participate in whiteboard collaboration.

> A key milestone in the early engagement is the first time a client takes the pen and starts using the whiteboard to explain something to me. Early use of the whiteboard is all about immediate communication. Later, the solution design starts to solidify and we can then use the last state of the whiteboard to make out first architecture diagram.
>
> * Brendan Richards, SSW Solution Architect

::: ok img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'SSW Rewards - start out with a hand-drawn sketch if that\'s easier for you, but don\'t consider this your final architecture diagram',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/rewards-hand-drawn-sketch.jpg"
/>
:::

**Tip:** [Microsoft Office Lens](https://www.google.com.au/url?sa=t&rct=j&q=&esrc=s&source=video&cd=&cad=rja&uact=8&ved=2ahUKEwi6-NTb1MvrAhWXA3IKHevqC-MQtwIwAHoECAEQAQ&url=https://www.youtube.com/watch?v%3DjzZ3WVhgi5w&usg=AOvVaw25XKH6ZRcPfM5jaVajFOlH) 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).

::: good img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Better example - SSW Rewards - the same sketch but captured with Office Lens. How much clearer and more vibrant is this!',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/reward-hand-drawn-sketch-office-lens.jpg"
/>
:::

### Tip #7: ...and finish up with draw.io

The best tool for creating these diagrams is [draw.io](https://draw.io/). All the examples on this page were created with this tool.

It is definitely the most popular diagram tool at SSW:


<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'When SSW developers were surveyed, draw.io was the clear winner (see green) for building architecture diagrams',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/FaveTool.png"
/>

::: good img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Better example - TimePro (an Angular &plus; .NET project with Hangfire) - you can create diagrams quickly and easily with draw.io that still look very professional. This one is in the style of a technical document',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/TimePRO-Architecture-Diagram-v2.png"
/>
:::

Draw.io is free, can be used in the browser, or can be downloaded as a desktop app. But the best way to use draw.io is to integrate it directly into VS Code.

::: good img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Great example - Auctions (a Blazor + .NET + Cosmos DB project) - draw.io integrated directly into VS Code',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/thumbnail_image003.jpg"
/>
:::

There are multiple extensions available that let you do this, the best one is [VS Code | Extensions | Draw.io Integration](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio). This makes it easy to create and edit the architecture diagram right alongside the code, and check-in with the relevant commits.

::: good img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Good example - Auctions (a Blazor + .NET + Cosmos DB project) - 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',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/architecture-2.png"
/>
:::

### Tip #8: Polish up draw.io

Maintain standards to keep your diagrams consistent:

* Title - Naming Convention. E.g. Architecture Diagram - &#123;&#123;product name&#125;&#125;
* Title - Standard font size. E.g. 43pts
* Standard font. E.g. Helvetica bold
* Standard arrowhead sizes. E.g. 14pts
* Doc details - at the bottom left, add file location. E.g. DevOps | Wiki or GitHub | Repo | Docs, in font size 22pts
* Doc details - at the bottom right, add branding and URL E.g. &#123;&#123;logo image&#125;&#125; - url.com, in font size 22pts
* Add color and icons to make your diagrams engaging and easier to distinguish

::: good img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Good example - SSW People (a Static Site - Gatsby and React with Dynamics 365 and SharePoint Online) - you can just as easily create colorful, engaging diagrams suitable for all of your project stakeholders',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/SSW.People-Architecture-Diagram.png"
/>
:::

### Tip #10: Exporting diagrams

To export your diagram, go to *File* | *Export as* | *PNG*

Make sure to tick *Include a copy of my diagram* is selected. This will let you open your diagram and edit it again when you import the PNG file into draw.io.

To make it easy to tell that you can open the file in draw.io, ensure that the file extension is `.drawio.png`.

Read more in the docs - https://www.drawio.com/doc/faq/export-to-png

### Tip #11: Where to store diagrams?

Standardizing where your organisation stores architecture diagrams ensures a consistent experience among developers. Therefore store your architecture diagrams in the repo **docs**\ folder. Additionally, the \README.md (in the root) should have a link and an embedded image of the high-level architecture diagram (from the **docs**\\* folder).

**Note:** If you have a Wiki, for visibility add an architecture diagram page and embed the images from the **docs**\\* folder.

### Tip #12: Use Azure Architecture Center

[Azure Architecture Center](https://docs.microsoft.com/en-us/azure/architecture/) is the best tool to help you figure out the pieces you need for an architecure diagram - see [SSW.Rules | Do you use Azure Architecture Center](/azure-architecture-center)

### Alternatives to draw.io


**Eraser**

Another popular tool is [Eraser](app.eraser.io) which provide many industry standard icons, features, and tools that are used for architecture diagrams and software design blueprints.

**Miro (by Adobe)**

[Miro](https://miro.com/) is an online tool designed primarily for whiteboard-style collaboration. It is very easy to use and optimised for this purpose.

**Note:** The paid version of Miro gives you Azure Architecture Diagram templates - see [miro.com/templates/azure-architecture-diagram/](https://miro.com/templates/azure-architecture-diagram/)


<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'An Azure Architecture Diagram created in Miro',
    shouldDisplay: true
  }}
  src="/uploads/rules/architecture-diagram/miro-arch-diagram.jpg"
/>

**Mermaid**

If you really want to geek out and use markdown, you can try [Mermaid](https://mermaid.live) to build simple diagrams.