A Solution Architect's Tips - The 5 Types of Architecture Diagrams

statement:
This article is transferred from the DEV Community website, and the article translation is provided by the developer community;
Click the link below to view the original English text:

• https://dev.to/aws-builders/solutions-architect-tips-the-5-types-of-architecture-diagrams-3pl3

In a conference you've attended, has anyone ever explained how a software system works?

I was talking to a new solution architect who was trying to describe to me a system they had designed: about eight different components that communicated with each other in different ways.

In describing the solution, they used gestures non-stop, as well as a lot of "this part communicates with that part through..." sentences.

I know every word they say, but when they connect it, I don't understand it.

Language loses meaning when explaining complex conceptual architectures. I'm following a train of thought to build a mental model. I need a visual representation.

i need a graph

But not an ordinary graph. Architecture diagrams are not a one-size-fits-all solution.

We discussed recently that as a solutions architect, it is important to effectively communicate your ideas to technical and non-technical audiences.

Your chart must take this into account. If you want to pass your ideas on to different people, you have to make different versions of the diagram.

What we're talking about here is that there should be 5 different types of charts based on 5 different audiences.

We will take the real API, Gopher Holes Unlimited as an example, and add a new query gopher to the system.

flow chart

Flowcharts are the most versatile and influential diagrams. It is a mid to high level diagram that contains all the parts of the workflow.

This diagram shows the active parts of a business process.

audience

The audience for flowcharts is generally technical. It can be used to articulate an idea to an architecture committee or to describe to developers how a business process works.

Precautions

The architecture flowchart is mainly composed of various moving parts. In our serverless AWS environment, we label each managed service and which services can communicate with each other.

We do not describe in detail how the parts interact with each other, but show the connections, that is, show how data flows through the system.

service map

A service graph shows connectivity at a high level. It doesn't contain details like workflow or how the service works, but shows the key parts that work. The following diagram shows the internal and external services used in the application.

audience

IT and network engineers tend to be most interested in this type of diagram. They care about how to connect to external services, and they also want to know if any internal connections need to be monitored.

I often use service diagrams to explain to executives how a system works. They want to know how the main applications are connected, and there is nothing better than a service graph to present those connections.

Precautions

When building an architectural service diagram, it's a good idea to list all the microservices that make up an application or ecosystem. Identify which services communicate with each other, and make sure to distinguish between internal and external services.

In such high-level diagrams, there is no need to detail how each service works. This is true for all services that make applications run.

role map

It's important to show that your architecture solves a business problem. The role diagram presents a chronological view of the different roles within a specific workflow. It's the best tool to demonstrate that you have your business in mind when crafting your solution.

audience

The target audience for this type of chart includes business-oriented individuals and product owners. They focus on roles, and how they interact with the system. Such a "who, when, what" diagram perfectly describes your system to your audience.

Precautions

The role diagram is somewhat similar to the BPMN model, using swimlanes to show the different roles in a workflow. This type of diagram tends to be low-level because it contains more detail. Identify roles, workflows, and how business processes move from one step to another.

Persona graphs can also help developers who are new to a field by providing rich context for what they are about to develop.

Infrastructure map

An infrastructure map is a "what you see is what you get" model. It represents everything that has been implemented. It is essentially a low-level diagram that includes everything that exists in the service/application/ecosystem.

Infrastructure diagrams are meant to show what has been established and how the system currently works. Think of it as a blueprint for the applications you build.

audience

Infrastructure diagrams have different audiences. It can be used to show developers what needs to be dealt with in a specific microservice. It can also be used to show customers all the resources your company uses to accomplish a task.

Technicians are the primary users of infrastructure maps. Since you are providing a checklist rather than showing an idea or business process, the intended use of this type of diagram is limited to information. It's for those who like "the little things."

Precautions

When making an architectural infrastructure diagram, don't leave out any parts. The goal of this type of diagram is to show everything in the application and how they are connected. You don't need to dive into all the details, but make sure to include all parts of your application in the diagram.

developer map

The developer graph is the best choice when you need to gain insight into the situation. It contains everything a developer needs to build a solution. The goal is to answer any questions that may arise when looking at the flowchart and incorporate it into the design. This is the lowest level diagram, designed to convey your thoughts without your presence.

Someone should be able to read the diagram and know exactly what to do.

audience

The audience for such diagrams is the developer implementing the solution. For people outside the team, the level of detail included in the diagrams is not necessary. Sometimes too much detail can be a bad thing for audiences who don't need too much detail.

Providing implementation details to people outside the development team is a good example of how too much detail is not a good thing. It causes distraction and obscures other messages you want to convey.

Precautions

Developer diagrams are essentially flowcharts with added detail. Mark any specific implementation details you can think of, and also mark important transitions.

Such diagrams don’t replace user stories, but they do help reinforce user stories and improve understanding across the development team. Use when you can use the developer map, because after the implementation is over, you have a tool that you can refer to in the future.

Summarize

There are many types of architecture diagrams. Each has a special purpose and serves a different audience. As a solutions architect, you must be able to present ideas while delivering the right type of diagrams to the right audience.

In many cases, one version of the chart is not enough. When I start a new design, I always start with a flowchart. I'll write down all my thoughts and get other solution architects to agree. Once we agree on a solution, I turn it into a role map and show it to the business.

When I get the consent of the business unit, I can make the developer graph and the service graph. The service map is for executives to make sure they have a high-level understanding of what we're doing. The developer map is for those engineers who will be implementing the solution.

Once the solution is built, we can update the infrastructure map to include the new work.

A picture is worth a thousand words, but an architecture diagram may be worth five thousand. Being able to easily and quickly understand your ideas is the key to being a good solutions architect.

Be able to build different types of charts for different audiences and you're set for success.

PS - I'm used to using draw.io to build diagrams. This is a free tool that provides everything you need to create beautiful and detailed diagrams, models, and illustrations.

Article author: Allen Helton
Allen Helton for AWS Community Builders