The author | 3 Alibaba technology experts

Takeaway: * * * * the value of technology spread, not only reflected in the through commercial and open source projects to shorten product we build the path of the application, to accelerate business online rate and also in good engineers to the improvement of working efficiency and improve product performance optimization and the user experience sharing of experience, in order to improve our professional ability. This article was published on Alibaba’s internal technology sharing platform. Zi Jing, Peng Sheng and Yu Le also contributed to this article.

When we try to describe our system in one or more pictures, do we often encounter the following situations:

• Don’t know what to do with the canvas, delete and come again?
• Describe my system in a picture that product, operations, and development can all see?
• Half of the picture is not clear who the audience is?
• Is it a product diagram, a functional diagram, a technical diagram, or a hodgepodge?
• There’s a little bit of a lack of boxes in the picture. Do you need to find some boxes to put in?
• The layout is not satisfactory…

If you are similarly confused, this article will introduce a drawing methodology to make architecture diagrams clearer.

Let’s clear up some basic concepts

1. What is architecture

Architecture is an abstract description of the entities in the system and the relationships between the entities. It is a series of decisions.

Architecture is structure and vision.

The system architecture is the embodiment of the concept, the allocation of the correspondence between the function of the object/information and the formal elements, and the definition of the relationship between the elements and the relationship between the elements and the surrounding environment.

Getting architecture right is a complex task and a big topic that I won’t go into here. Once you have an architecture, stakeholders need to understand and follow decisions.

2. What is an architecture diagram

The system architecture diagram is an abstract representation of the overall outline of the software system and the interrelationships and constraints between the various components, as well as the overall view of the physical deployment of the software system and the evolution direction of the software system.

3. The role of architecture diagrams

A picture is worth a thousand words. For stakeholders to understand and follow architectural decisions, the architectural information needs to be communicated. Architecture diagrams are a good vehicle for this. So, the easel composition is for:

• Solve communication barriers
• Reach a consensus
• To reduce ambiguity

4. Classification of architecture diagrams

A lot of data is collected, and there are many categories. One popular view is the 4+1 view, which is the scene view, the logical view, the physical view, the process view and the development view.

• Scene view

The scenario view is used to describe the relationship between the actors of the system and functional use cases, reflecting the final requirements and interaction design of the system, and is usually represented by use case diagrams.

• Logical view

Logical view is used to describe the component relations, component constraints and boundaries after the disassembly of system software functions, and reflect the overall composition of the system and the process of how the system is constructed. It is usually represented by UML component diagram and class diagram.

• Physical view

The physical view describes the mapping between the system software and physical hardware, reflecting how the system components are deployed on a set of computable machine nodes, and guiding the deployment and implementation of the software system.

• Process view

The process view is used to describe the time sequence of communication between system software components, the input and output of data, and reflect the functional flow and data flow of the system. It is usually represented by time sequence diagram and flow chart.

• Development view

The development view is used to describe the module division and composition of the system, as well as the composition design refined to the internal package, which serves the developers and reflects the implementation process of the system development.

The above five architectural views represent different characteristics of a software system from different perspectives and are combined as an architectural blueprint to describe the system architecture.

What is a good architecture diagram

The above classification is a summary of previous experience, and the pictures are also picked from the Internet, so are these pictures good? Are we going to draw something like this?

To leave the first figure is good, we through the classification of these graphs and action, thinking and summary, we believe that before the draw a good architecture diagram, first should clear its audience, and would like to give them what message clear, therefore, not to paint a physical view to the physical view, In order to draw a logical view to draw a logical view, it is necessary to accurately express the picture according to the audience and the different information conveyed. The final picture may be in some of these categories. A direct criterion for a good picture, then, is whether the audience has accurately received the intended message.

With these two points in mind, a good architecture diagram does not need to be explained from the audience’s point of view, it should be self-describing, consistent and accurate enough to respond to the code.

Common problems with easel composition

What does the box stand for?

Why does it apply to a box instead of a circle? Does it have any special meaning? Arbitrary use of boxes or other shapes can cause confusion.

2. What do dotted lines and solid lines mean? What does the arrow mean? What does color mean?

Arbitrary use of lines or arrows can be misleading.

3. Run-time compile-time conflict? Hierarchy conflict?

Architecture is a complex business, and using a single diagram to represent it can easily lead to unaccountable semantic confusion.

The drawing method recommended in this article

The C4 model uses containers (applications, data stores, microservices, etc.), components, and code to describe the static structure of a software system. These diagrams are relatively easy to draw and give the gist of what to draw, but most importantly, we think, it specifies the audience and meaning each diagram is likely to have.

The following examples are from the C4 website, and then add some of our understanding to see how to better express software architecture.

1. System Context Diagram

This is an imaginary Internet banking system to be built. It uses an external mainframe banking system to access customer accounts and transactions, and sends emails to customers through an external E-mail system. As you can see, it is very simple and clear, and I believe it does not need to be explained. It contains the system itself that needs to be built, the customers of the system, and the surrounding systems that interact with the system.

use

A simple diagram like this tells us what the system is to build; Who its users are, who will use IT, and how IT fits into the existing IT environment. The audience for this diagram can be internal, external technical, or non-technical members of the development team. That is:

• What is the system being built
• Who will be using it
• How to integrate into the existing IT environment

How to draw

In the middle is its own system, surrounded by users and other systems that interact with it. The key to this diagram is to sort out the users and high-level dependencies of the system to be built, and it only takes a few minutes to draw it.

2. Container Diagram

The container diagram is an expansion of the system to be built in the context diagram.

In the figure above, in addition to users and peripheral systems, the system to be built includes a Web application based on Java spring MVC to provide the functional entrance of the system, a mobile app based on Xamarin architecture to provide the functional entrance of the mobile side, a Java-based API application to provide services, and a mysql database for storage. The interactions between each application are indicated on the arrow line.

When you look at this picture, you don’t pay much attention to whether it’s a rectangular box or a rounded box, whether it’s a solid arrow or a dotted arrow, or even where the arrow is pointing.

We have many drawing methods, all of which define the meaning of box and line, which requires both the drawing and the viewer to clearly understand these definitions in order to read the entire information in the drawing. But the reality is that this is often a very high requirement, so many drawings can only be seen in a general sense.

use

The audience for this diagram can be internal or external to the team, developers, or operations. Uses can be listed as:

• It shows the overall shape of the software system
• Represents high-level technical decisions
• How are responsibilities distributed in the system and how do containers interact with each other
• Tell developers where to write code

How to draw

Represented by a block diagram, the internal may include names, technology choices, responsibilities, and interactions between these block diagrams, preferably with clear boundaries if external systems are involved.

3. As can be seen from the Diagram (Diagram)

A component diagram is an expansion of a container to describe its internal modules.

use

This diagram is mainly for internal developers to see how to organize and build code. Its uses are:

• Describes what components/services the system consists of
• Relationships and dependencies between components are clarified
• Provides a framework for how software development breaks down delivery

As can be seen from the Diagram /Class Diagram

This diagram is obviously for technical people to see, it’s quite common, so I won’t go into details.

Case sharing

Below is an architectural diagram of an internal real-time data tool. As an architecture diagram that should be self-describing, I won’t explain it here. If you can’t understand it, it’s definitely not good enough.

There are many ways to draw architecture diagrams, and this article focuses on C4, which is also evolving. But no matter which method of drawing, we go back to the original purpose of drawing, better communication, we do not have to be limited by the rules in the process of drawing. In short, think before you draw: whom to show, what to see, and how to understand without explaining.

References:

• C4 website
• Why do you need a software architecture diagram

Author’s brief introduction

Three paintings, Alibaba technology expert. He has been engaged in the research and development of workflow engine for many years, and now focuses on the architecture and development of high concurrency mobile Internet applications. Contributors to this article are all from alibaba Retail Connect department.

The selection of welfare

What efforts have you made to become an architect in the comment area of alibaba public account before 10:00 on April 17th?

• The top 2 who receive the most likes will get 1 book “Ali Cloud Operation and Maintenance Architecture Practice Secret book” by China Machine Press;
• The number 3-5 with the most likes will get a doll.
• The 6th to 10th with the most likes will get one CNCF legitimate fidget spinner.

“Alibaba Cloud Primitive focuses on micro-service, Serverless, container, Service Mesh and other technical fields, focuses on cloud native popular technology trends, cloud native large-scale practice, and does the public account of cloud native developers who understand the most.”