- Solution Architect Tips — The 5 Types of Architecture Diagrams
- Originally by Allen Helton
- The Nuggets translation Project
- Permanent link to this article: github.com/xitu/gold-m…
- Translator: Luo Zhu
- Proofread: PassionPenguin, Zz Zhaojin
Have you ever been in a meeting where someone tried to explain how a software system works?
I had a conversation with a new solution architect. He was trying to describe their proposed system of about eight different components, all of which interact in a variety of ways.
They use hand gestures and lots of “Between this and this by…” To explain the solution.
I could understand every word that came out of their mouths, but putting the words together made no sense to me.
Verbal representation is weak when it comes to explaining complex architectural concepts. I tried to build a mental model as I went along. I need a picture.
I need a chart.
But that doesn’t mean you can go anywhere with one map. Architecture diagrams are not a “one size fits all” solution.
We recently discussed that an important ability as a solution architect is to effectively communicate your ideas to both technical and non-technical audiences.
Your chart must take this into account. If you want to communicate your idea to different groups of people, you have to make multiple versions of the image.
Today, we’re going to talk about five different types of charts you should make for five different audiences.
We’ll discuss an example where the business is imaginary but the API is real: the infinite gopher hole, where we add a new gopher to the system to track.
1. The flow chart
The most general, and in general the most far-reaching, diagrams you can make are flowcharts. It is a mid – to high-level diagram that shows all parts of the workflow.
The figure illustrates the flow part of the business process.
The audience
The audience for this type of diagram is usually technical people. It can be used to present an idea to the architecture board, or to describe to developers how a business process works.
Matters needing attention
The main content of the architecture flowchart is the part that contains all flows. In the case of a serverless AWS environment, we annotate each managed service and the communication between the services.
The details of how these parts interact with each other are not described, but the diagrams do show these connections. It shows how data flows through the system.
Figure 2. The service
Service diagrams illustrate connectivity at a high level. It does not show any details of how the workflow or service works, but rather shows the main parts of the action. This is a diagram designed to show the internal and external services used in an application.
The audience
IT and network engineers tend to be most interested in this type of diagram. They care about any connection you have to external services. In addition, they need to know if there are any internal connections that need to be monitored.
I often use this diagram to describe how the system works to executives. They want to know the connections between the major applications, and nothing better represents those connections than a service diagram.
Matters needing attention
When building an architecture service map, it’s a good idea to list all the microservices that make up your application or ecosystem. Identify which services communicate with each other and be sure to distinguish between those owned by your company and those outside it.
Details about how the service works are not necessary for this high-level diagram. This is all about the services that make the application run.
3. The role of figure
It is important to indicate the business problem that your architecture needs to solve. A role diagram describes a chronological view and roles in a particular workflow. This is the best tool to prove that you have taken business considerations into account when building your solution.
The audience
Enterprise-oriented individuals and product owners are the target audience for such diagrams. They focus on characters and how they interact with the system. Show them a picture of who did what and when, and it will perfectly describe what your system is doing.
Matters needing attention
The architectural role diagram makes some attempts at the BPMN model. Use swimlanes to display different roles in the workflow. This type of diagram tends to be low-level because it contains more detail than other diagrams. Be sure to identify roles, workflows, and any assumptions about how the business process moves from step to step.
These diagrams can also help developers who are new to a field and provide a deep context for what they will be building.
4. Infrastructure map
The infrastructure map is a “what you see is what you get” model. It represents everything that has been achieved. It is a low-level diagram designed to encompass services, applications, and everything that exists in the ecosystem.
The purpose of this diagram is to show what has been built and how the system currently works. Think of it as a blueprint for the application you’re building.
The audience
The infrastructure map has a different audience. It can be used to show developers what they must use in a particular microservice. It can also be used to show customers all the resources your company is using to complete a task.
Technical people will be the primary audience for your infrastructure map. Since you are providing a checklist rather than communicating ideas or business processes, the intended use of this diagram is limited to information. This is for those who like “minutiae” details.
Matters needing attention
When building your infrastructure architecture map, don’t miss a single piece. The goal of this type of diagram is to show everything in your application and how they are connected. You don’t need to go into too much detail on how, but focus on getting all parts of your application included in the diagram.
5. Developer chart
When you need to start working on a problem, the developer chart is your best bet. It includes everything a developer needs to build a solution.
Our goal is to answer any questions that might arise from looking at the flowchart and include them in the design. This is the bottom of a pile of diagrams designed to convey ideas without you being there.
Someone should be able to read this picture and know exactly what to do.
The audience
The developer implementing the landing scenario is the audience for this type of diagram. The figure contains a level of detail that is not necessary for people outside of your team. Sometimes too much detail can be a bad thing for an audience that doesn’t need it.
Providing implementation details to people outside the development team is an example of being too detailed. It leads to distraction and obscures the other message you’re trying to convey.
Matters needing attention
A developer architecture diagram is essentially a flow chart filled in with details. Mark each piece with any implementation details you can think of, and be sure to mark important transformations.
This type of diagram is not a substitute for user stories, but it does help enhance them and increase the understanding of the entire development team. When you can use them, because when the implementation is complete, you will have a useful material to refer to in the future.
conclusion
There are many types of architecture diagrams. Each has a unique purpose, and many serve a different audience. As a solution architect, you must be able to pitch your idea to the right people with the right types of diagrams.
Often, one version of the diagram is not enough. When I start a new design, I always start with a flow chart. I wrote all the ideas down and then recommended them to other systems architects. Once we agreed on a solution, I would take the diagram, turn it into a persona diagram, and show it to the business people.
Once I get the business people to sign off on it, I’m free to make developer maps and service maps. The service map is for senior management to make sure they have a high-level view of what we are doing. The developer diagram is for engineers who will be implementing the solution.
Once the solution is built, we can update the infrastructure diagram to continue with the new work.
A picture is worth a thousand words, but when it comes to architectural drawings, they can be worth five thousand. Being able to get your ideas across quickly and easily is the key to being a good solution architect.
With the ability to build different types of charts for different audiences, you can set yourself up for success.
I use P.S. all the timedraw.ioTo construct my chart. This is a free tool that gives us everything we need to make beautiful diagrams and models of all kinds.
If you find any mistakes in your translation or other areas that need to be improved, you are welcome to the Nuggets Translation Program to revise and PR your translation, and you can also get the corresponding reward points. The permanent link to this article at the beginning of this article is the MarkDown link to this article on GitHub.
The Nuggets Translation Project is a community that translates quality Internet technical articles from English sharing articles on nuggets. The content covers Android, iOS, front-end, back-end, blockchain, products, design, artificial intelligence and other fields. If you want to see more high-quality translation, please continue to pay attention to the Translation plan of Digging Gold, the official Weibo, Zhihu column.