Architecture Drawing: Tools and Methodology

By Chuheng

Preface

At first glance, the term “architecture drawing” seems somewhat obscure. However, when it comes to “engineering drawing”, most programmers with an engineering background should already be familiar with it. I can even feel the ups and downs of those years in the dormitory with a compass on the left hand and a ruler on the right hand.

Software engineering is also engineering. Therefore, some basic theories of conventional engineering drawing are also applicable in the software industry. However, the differences between the software and traditional manufacturing industries are so essential that their demands and methods in cartography are quite different as well, which cannot be directly applied. As a practitioner in the software industry, you may not understand engineering drawing at all, but you must understand architecture drawing. This is a compulsory course for every programmer in their careers.

The second half of this article describes how to use graphs to describe and communicate your architectural design. It is worth emphasizing that this article will focus on the general methodology behind those excellent methods rather than on a single method or tool. It means that this article will focus on the essence, commonality and best practices of architecture drawing. I hope this article can serve as an introduction to stimulate everyone to follow, examine and think about the architecture and drawing part of your daily work. If this article can really help you improve the drawing efficiency and effect even just a little bit, that would be great.

What Is Software Architecture

Definition of Software Architecture

The definition shown by IEEE is that architecture is the set of fundamental concepts or properties of the system in its environment, embodied in its elements, relationships, and the principles of its design and evolution.

Software Engineering Institute of Carnegie Mellon University (CMU) defined the software architecture of a computing system is the set of structures needed to reason about the system, which comprise software elements, relations among them, and properties of both.

Uncle Bob defined architecture of software system in Clean Architecture is the shape given to that system by those who build it. The form of that shape is in the division of that system into components, the arrangement of those components, and the ways in which those components communicate with each other.

Core Elements of Architecture

Based on authoritative definitions above, software system architecture usually contains following four types of core elements.

• Elements: A system can be split into a group of elements of modules, components, structures, and subsystems.
• Relationships: Relationships between different elements are interaction, dependency, inheritance, composition, and aggregation.
• Properties: Properties that each element has are names, responsibilities, interfaces, implementation restrictions, etc.
• Principles: Reasons for the design include the basis for splitting, design principles, decision-making reasons, etc.

Why Architecture Is Important

Architecture — Blueprint for System Implementation

Recently, there is a very popular web series about a strange suspense story in a skyscraper called “A Murderous Affair in Horizon Tower”. I want to ask a question here. Who built the skyscraper? Maybe you will think the question as meaningless that the skyscraper is just built by construction workers brick by brick. However, if you think about it again, you will find that there are a bunch of architects and civil engineers who are most concerned about the skyscraper. They don’t work like construction workers, but without their hard work of those tedious and rigorous design drawings, skyscrapers cannot be erected as quickly and stably as self-built houses. In rural areas, self-built houses can be constructed just with workers’ experience and imagination.

It is these blueprints that laid the basis for worker’s division and cooperation of labor as well as acceptance criteria. Workers just need to follow blueprints and do their jobs. As long as blueprints are correct and there is no deviation in the construction process, the skyscraper will eventually be completed successfully.

Like the construction, automotive, or any other engineering industries, software also requires blueprints before it is coded. One of the most important blueprints is architecture design. With no architecture but only vague ideas, you might be able to create some nice and useful things such as Linux 0.01 like traditional craftsmen. However, it is unlikely that a complex software system on the scale of a skyscraper, for example, the modern Linux system, could be built in an engineering manner with a team. For one thing, the thinking ability of human is limited. So, we must rely on highly abstract and simplified blueprints of architecture to make the creation, understanding, analysis and management of complex systems feasible. For another, large systems that reach a certain level can only be completed through multiple division of labor. The architecture is just the important foundation for communication and collaboration among people.

Architecture is the Foundation of Communication and Collaboration

The final value output of a software project is the software system. As the soul and framework of the software system, the architecture can play following roles.

• Understanding alignment: All software systems are designed to meet user needs. Whereas, compared with traditional engineering industries, software is more flexible and knowledge iterates faster, so there are infinite possibilities for implementation. Architecture design is to choose the most suitable implementation method. Therefore, lots of key routing decisions are involved including reasons for splitting and for choosing technology A rather than technology B. These important technical decisions need to be recorded and synchronized by architecture description. By doing so, all project team members can reach a consensus on the understanding of the whole system.
• Work quantification: One of the most important steps in project management is working hours assessment, which is the direct basis for determining project schedules. Obviously, workloads of a project cannot be scientifically quantified only by product requirement document (PRD) or interaction graphs. This is because it is difficult to intuitively determine how much code needs to be written and how hard it is to achieve behind a brief requirement or a simple page. With a clear and explicit architecture, most development work can be visible, predictable and detachable theoretically, and be quantified more accurately. Of course, accurate workload assessment has always been an unsolved difficulty in the IT industry. The actual schedule will be affected by too many unknown factors, including skill proficiency, mood, and diet of programmers.
• Standard terminology: Programming, as a creative job, is similar to writing science fiction novels from a certain perspective. All writers of good science fiction novels like to create concepts, such as Sophon in The Three-Body Problem. If you haven’t read the novel, you certainly have no idea of what it is. Compared with science fiction, software system is going further in creating concepts. After all, the world in novels is usually based on our real world, while the world in software depends on modeling of programmers. Slightly more complex software systems will introduce some domain-specific or even brand-new concepts. In order to avoid the communication barriers and ambiguity in understanding during the project, terms describing these concepts must be unified. One important purpose of the architecture is to define and explain all key concepts of a system clearly, and use standard and consistent terms in the entire architecture design and description process. In this way, the communication for everyone will be smoother.
• Specific content: Architecture description is a specific form of materialization. Interaction designers need to collate prototype diagram when discussing product interactions and programmers need to look directly at the code when discussing code details. Just like them, when we discuss some higher-dimensional technical issues, the essential entity in the architecture must be considered. Or otherwise, it will be either a bunch of people talking meaninglessly without any basis, or finding a whiteboard to draw every time we communicate. It is obviously not a long-term solution due to time-consuming and information loss.

Knowledge accumulation and newcomer training: Architecture should be continually accumulated and maintained as document assets like important code. Moreover, architecture is an important basis for newcomers to understand and operate system quickly. Don’t leave your system only with legacy code and without architecture documentation. Otherwise, you will be in struggling to maintain the project alive only with some leftover design memories from mouth to mouth.

Architecture Determines Product Quality

How to measure the quality of a software product? The preceding figure shows the software product quality model defined by ISO/IEC 25010, which covers following eight aspects.

• Functional Suitability: Functional integrity, functional correctness, and functional appropriateness.
• Performance Efficiency: Time behavior like response time, resource utilization, and capacity.
• Compatibility: Interoperability and coexistence capability like coexistence of multi-version components.
• Usability: Learnability, operability, user error protection like automatic error correction, user interface aesthetics, and accessibility.
• Reliability: Maturity, availability, fault tolerance, and recoverability.
• Security: Confidentiality, integrity, non-repudiation, authenticity, and accountability.
• Maintainability: Modularity, reusability, analyzability, modifiability, and testability.
• Portability: Adaptability, installability, and replaceability.

All points listed in the quality model above need to be considered in architecture design. Except function suitability, all other points belong to non-functional requirement, which is the standard for distinguishing good architectures from bad ones. In other words, good architecture design will not only satisfy the most basic functional requirement for the worst architecture design can do the same. More importantly, good architecture design also meets many other non-functional requirements.

You of course cannot have them all. Architecture is a game of tradeoff just like our life. The worst result is nothing will be done in the end. Good architects should seem like “know nothing”, but actually “know everything”. They should know all stakeholders in the system, try to mine all parties’ concerns, balance their own decisions, and finally achieve the ultimate goal for all-win situation.

Additional Reasons

There are actually more reasons than those listed in this page.

• Architecture contains all the most important early decisions. These decisions will in turn affect all subsequent technical decisions. Therefore, although it is difficult, the early architecture design needs to be as rigorous and cautious as possible to make it right at one time. Otherwise, the cost of error correction will be high in latter stages;
• Architecture has a very high reuse value within the organization because there are many commonalities of products in the same organization, such as requirements, restrictions, and environment. This means it is suitable for maximizing reuse at the architecture level and avoiding repeated resolution of similar problems.
• Conway’s Law points out that the software architecture reflects the organizational structure. So, good architecture can make the organizational structure more efficient.
• The larger and more complex the system is, the more important the architecture is. Only a good architecture can effectively control, manage and reduce system complexity.
• Maybe you will become confused as if there are infinite kinds of explanations of architecture. But don’t worry about it. Gang of Four (GoF) has described in their design model: “architecture is about the important stuff. Whatever that is.” So just remember that architecture is very important.

How to Design a Good Architecture

After understanding concepts and the importance of architecture, you have just begun to become a real architect. The question of how to design a good architecture is obviously a broad and profound topic, but it is not the focus of this article. Therefore, only some basic principles and classic modes are presented in this article. Architecture design is closer to an empirical discipline. It is not enough to blurt out some mysterious and lofty theoretical concepts. You also need to put yourself into practice and try to deliberate architecture design through the combination with actual work and business scenarios. Or otherwise, you will always just discuss about theories.

Principles

SOLID principles are a set of classic and popular architecture principles.

• Single responsibility principle: It is similar to “Do one thing and do it well” advocated by Unix philosophy.
• Open / closed principle: It uses extension instead of modification (destroying existing encapsulation), which is similar to the idea of immutable in functional expression.
• Liskov Substitution principle: The “Is-A” relationship of inheritance can be proofed only when parent classes appear, the subclass must appear.
• Interface segregation principle: Do not allow one class to depend on an interface that is not used in another class. In short, it means to minimize the interface dependency and coupling between components.
• Dependency Inversion principle: Abstract classes and interfaces, rather than concrete implementations are relied on. Let low-level modules depend on the stable abstraction of high-level modules to achieve decoupling.

In addition, following principles will be obeyed as much as possible when designing the architecture. These principles are similar to the above SOLID principles in essence.

• Orthogonality principle: The orthogonality of components separated from the same level of architecture should be ensured, that is, these components should be mutually independent and have clear boundaries without overlap.
• High cohesion principle: The inside of the same component should be highly cohesive, like an indivisible whole, or otherwise it should be separated.
• Low coupling principle: Coupling between different components should be reduced as much as possible to reduce the mutual impact of changes and enhance component reusability.
• Change isolation principle: The essence of many architecture principles and patterns is the isolation of changes. When changes occurred, other stable parts may need modification on code and re-testing, or may cause hidden problems. By isolating parts that are expected to undergo changes, these bad impacts can be reduced.

Patterns

Architectural patterns are not same as design patterns we often discuss. However, if we interpret them only from the perspective of “patterns”, the idea of both is the same, that is, a general and reusable solution to a commonly occurring problem within a given context. The main difference is that architecture patterns used at the architecture design level are more high-dimensionally abstract and more comprehensive.

Common architecture patterns include some traditional patterns such as layering, C/S, MVC and event driving, and also some new patterns such as cloud native, microservices, and Serverless. Different patterns have different applicable scenarios. A mature architect should be like a feelingless killer that always objectively evaluate and choose the most suitable solution for the moment, even if it will seem simple and boring. On the contrary, an immature architect always wants to do something, such as forced applying microservices architecture, rather than solving issues.

How to Describe Your Architecture Design

With a good architecture design, the road to the successful architecture has already reached more than half. It is just like a delighted young director who meets a good script for the first time. He seems to foresee the brilliant box office after the movie is on. Of course, the rest of the road is not as flat as imagined. The same design will have different qualities by different architects. A good architect should have the ability to describe a good architecture design. Even if he cannot add more points to the wonderful part, he should not lose points due to improper description of its form. Otherwise, he will feel so wronged and sad like losing points in writing in an exam.

Significance of Architecture Description

Why should I describe the architecture rather than just keeping it deeply in my mind? There is a proverb in the west that the faintest ink is better than the best memory.

Anything without persistence is volatile, just like memory. In addition, as mentioned earlier, architecture is the basis for communication and collaboration. Without architecture description for relative person in the object, the only carrier of communication and dissemination will be lost.

According to my personal observations, there is no objection to the “architecture demand description”. So most projects produce some sample architecture description documents more or less. However, there is a huge difference between architecture description and good architecture description, which is even huger than the difference between “having architecture description” and “having no architecture description”. If you have read countless architectural documents like me, you may feel the same.

Ways of Architecture Description

For a same thing, a writer uses words to describe it, while a painter uses paintbrushes to draw it. Both of them want to present the same information, but different ways of description will lead to huge difference in effect. Architecture description is also divided into text and diagram, each of which has its own advantages.

• Text depends on a rigorous and complete set of language. So its description can be very precise and exhaustive, and it is also very convenient to be written on whatever notepad software. In addition, just like writing code, version control can be easily completed for text with the help of simple text tools such as diff. By doing so, you can easily compare detail differences between different versions.
• By contrast, diagram does not have unique characteristics of text, but it also has its own unique advantages. Diagram is intuitive and visual. It conforms to the inherent visual recognition instinct of human beings. Moreover, diagram is stronger in expression. Most of the time, a small diagram can present information such as spatial location relationship, color classification, and icon shape, which may be unable to be comprehensively described with text.

You may think that can’t we have both text and diagram? Of course we can. The ideal architecture description must be illustrated with both text and diagram, but the real world is obviously crueler than an ideal one. In actual software programs, it is unlikely to give you enough time to produce a perfect architecture document first. Considering the return on investment (ROI), you will definitely give priority to diagram.

Reasons of Giving Priority to Diagram

The Manifesto for Agile Software Development mentioned that working software is more important than comprehensive documentation. This, of course, does not mean that there is no need to write documents. It just advocates there is no need to write too comprehensive documents. The reason is that comprehensive documents expend a lot of writing and maintenance costs, which does not conform to agile development principles of small-step iteration and rapid response to changes.

So, in today’s era of comprehensive agile development, how can we also follow the trend for more quickly writing architecture documentation? ROI is your friend, meaning that you should try to express the core content with simplest expressions. From content, the high ROI part is usually the top-level overall architecture or the core procedure. This is also reflected in the C4 model concept that will be introduced later. From form, diagram has an unparalleled expressive advantage compared with text, which is obviously a choice with higher ROI.

Reason of Learning to Draw

Is it necessary for us to learn how to draw? Architecture diagram is not art painting or just a bunch of stripes, and anyone with a little engineering knowledge can draw it. The painting is a bit ugly? It doesn’t matter. You just need to align lines and frames and add colorful background gradient or something. Then it will look very professional.

Maybe you will pour scorn on that again and think that it is obviously not so simple. Indeed, everyone knows the truth. Architecture drawing, like engineering drawing, is a matter that needs to be taken seriously and rigorously. However, in reality, most people really don’t have the time to do that. For example, the two common architecture diagrams posted above. Needless to say that the first diagram is good to satisfy yourself rather than show to others. The second diagram looks fine, but actually, when you measure it more carefully, you will find a lot of ambiguity and uncertainty in this diagram. For more information, please refer to the source article of this picture: The Art of Crafting Architectural Diagrams.

So, being able to draw diagrams doesn’t mean being able to draw diagrams well. It is difficult to seize key points for drawing a nice and readable diagram only by intuition and comprehension. You still need to learn continuously and practice deliberately. In addition, wrong diagrams are often worse than no diagrams. Even if just thought that “It’s OK to be just about right”, you should at least understand some key elements of scientific drawing. These key elements will avoid blurring an already complicated project, or even confusing or misconducting users.

Objectives of Architecture Drawing

Before discussing specific drawing methods and tools, we need to erect clear drawing objectives. Tools are the ladder of human evolution. However, if tools are understood and used improperly, human will easily be restricted or even enslaved by tools in return, forgetting original objectives of inventing and using tools. There are already so many methods and tools for architecture drawing. The original objective I think is to turn drawing into a scientific engineering from a free craft, achieving its systemization, strictness, integrity and standardization. At the same time, the process of drawing can be repeatable, sustainable and efficient.

P.S: Please forgive me. I was too busy at that time, so pictures in PPT have to be very simple.

Architecture Drawing Methods and Tools

After brief introductions in previous chapters, I believe that everyone has enough understandings of background knowledge for architecture drawing. In this chapter, I will specifically list and describe some typical architecture drawing methods and tools. Some of which are common and some of which are rare. The focus is to hope that through the horizontal comparison of various methods, everyone can understand well on the nature of drawing methods.

Unified Modeling Language

Unified modeling language (UML) is probably the most familiar drawing method for most people. The latest version of UML 2.x consists of following two types of diagrams.

• Structural diagrams: Through object, property, operation, and relationship, structural diagrams emphasize static structure. The most common types of structural diagrams include class diagram, component diagram, and deployment diagram.
• Behavioral diagrams: By showing collaborative relationships among objects and state changes within objects, behavioral diagrams emphasize dynamic behavior of the system. The most common types of behavioral diagrams include use case diagram, activity diagram, sequence diagram, and state machine diagram.

The universal UML contains 14 different types of diagrams, which can comprehensively meet various drawing requirements in software design, including architecture drawing. At the same time, as UML regards itself as a language, it has rigorous definition on various notations and semantics without any uncertainty or ambiguity. In addition, after decades of development and promotion, UML has already become a standard norm widely used worldwide. The hidden value of UML is the low cost for communication within the team by supposing that most technicians can comprehend the meaning and usage of UML.

However, although UML was once regarded as the silver bullet in software design, it is still not omnipotent. The most criticized shortcoming of UML is that it is too complicated. It is not UML itself to blame because it is designed to be universal, rigorous and powerful enough after all. These goals run counter to simplicity, and let it evolve step by step into today’s complicated and rigid language. Although we confidently supposed that most technicians can comprehend UML, I think an average of 20% would be good if you ask me how many of UML can they comprehend. Most of technicians just know several common class diagrams and sequence diagrams. It is estimated that it is even difficult for them to accurately express meanings of various arrows in class diagrams.

Whatever, UML should still be one of the most commonly used and necessary tools for every programmer. Of course, it should not be the only one, because there are some other good tools and methods that cannot be missed below.

4 Plus 1 View Model

What is “4 plus 1”? It doesn’t matter if you haven’t heard of it. Have you ever heard of the famous TV show named “6 plus 1”? “6 plus 1” has no relation with “4 plus 1” at all. They just sound similarly, like Sherry, Shirley, and Shirly.

So, what exactly does “4 plus 1” mean? Wikipedia defines it as a kind of view model and architecture describing software-intensive systems through multiple coexisting views. These views are based on viewpoints of different project stakeholders, such as end users, developers, system engineers, and project managers. “4 plus 1” consists of four basic views and some selected use cases or scenarios, that is, additional “plus 1” view. Following are specific meanings of each view.

• Logical view describes functions provided by the system for end users, which are usually represented by class diagrams and state machine diagrams of UML.
• Process view describes dynamic behavior of the system, including execution process and interaction. It is usually represented by sequence diagrams, activity diagrams and communication diagrams of UML.
• Development view explains the system from the perspective of programmers. It is also known as implementation view, which is usually represented by component diagrams and package diagrams of UML.
• Physical view describes the system from the perspective of system engineers, including the physical topology of system components and physical connections between each component. It is also known as deployment view, which is usually represented by deployment diagrams of UML.
• Scenarios are used for describing an architecture based on a small number of use cases or scenarios, including the interaction sequence among various objects and processes in the system. It is also known as use-case view. These scenarios can be used to identify architectural elements, illustrate and verify the entire architecture design, and act as the starting point for testing the architecture prototype.

Although views of “4 plus 1” mentioned above are generally represented by UML diagrams, in fact, “4 plus 1” itself is a kind of universal view model. Marks and tools of drawing are not limited. For engineers, this partially theoretical method may not be directly used in their work, but one key architecture drawing idea of “4 plus 1” is very valuable. That is the architecture needs to go through various views for description, while these views are based on viewpoints of different project stakeholders. Only in this way can architecture descriptions be comprehensive, three-dimensional and objective.

C4 Model

C4 model is an abstraction-first architecture drawing method, which is also inspired by UML and “4 plus 1” view model, but is relatively simpler and more lightweight. C4 model is easy to be learned and used with only a small set of abstractions and diagrams.

Definitions, Goals and Key Ideas

C4 model describes a static structure of the software system by abstraction such as containers, components, code, and people. Its core goal is to create maps of code, at various levels of details, in the same way as Google Maps to zoom in and out of an area. Its most crucial idea is to gradually split the static structure of the system by top-down algorithm, and describe responsibilities, relationships, and external dependencies of objects at all levels in sequence. In addition to the core hierarchical and static structure view, it also includes supplementary views such as dynamic view and deployment view.

The figure on the left shows mapping relationships of abstractions in various levels of C4 model. One software system consists of one to N containers, while one container consists of one to N components and one component consists of one to N code structures. The figure on the right takes a simple Spring PetClinic as an example, demonstrating the hierarchy of a real software system in the C4 model. The top layer is the PetClinic software system, which can be split into several containers like databases and web applications. Web applications contain components like ClinicService, which includes components of ClinicService interface, ClinicService implementation, and domain objects such as Owner, Pet, and Visit.

Architecture drawing through C4 model is essentially the visualization of above-mentioned abstractions. The specific way is to create types of structural diagrams from rough ones to detailed ones in sequence, which are Context, Container, Component, and Code (optional). This is also the reason why it is called C4 model.

Level 1: System Context Diagram

As the first level (L1), context diagrams of the system provide a big picture with the comprehensive view of the system. The big picture includes the central software system, peripheral users, and other systems with interactions. There are two key concepts in it.

• Person: It refers users of the software system, such as consumers, operators, system administrators of an online mall system.
• Software system: As the highest level of abstraction, software system describes the software products that create value for users. Both the software system currently being designed and other software systems with dependency relationships are included. A software system is usually the responsibility of a single software development team.

When drawing context diagrams of the system, there is no need to care about any underlying details such as technology stacks and protocols. These diagrams have a large range of audiences, because anyone can understand and obtain enough information from them. It is true for technical and non-technical personnel, as well as members within and outside the team.

Level 2: Container Diagram

After understanding the positioning of the system in the entire IT environment through context diagrams, the next step is to enlarge the framework of the system and see in detail which containers are included. Here please pay enough attention to the differences between container and docker.

In the C4 model, a container is a single application or data storage. Generally, a container can be deployed and run independently because it has independent process space and communicate by IPC mechanism. The container includes Spring Boot microservices, React SPA, mobile App, database, Serverlss function, and Shell script.

The container diagram in the second level (L2) not only shows how to further divide responsibilities of the system. It also includes key architecture information such as main technology selection and communication between containers. This type of diagram is intended for all technical personnel, including architects, developers, O&M personnel, and support professionals.

Level 3: Component Diagram

The next step is to partially zoom in containers in the system and further split each container into multiple components. In the C4 model, a component is a group of related functions that are encapsulated together through good interface definition. These functions are usually run within the same process space, for example, a controller in Spring. Controller includes not only main class controllers that define REST interfaces, but also all the related controllers of implementation classes, such as Service and Repository.

Similar to container diagrams, component diagrams of the third level (L3) include not only the division of container components, but also the responsibility definitions, technologies, and implementation details of each component. As layers deepen and details increase, the audiences range of component diagrams narrows. Target audiences generally only include software architects and developers. For other people, it is not necessary for them to understand, not mention that they are usually unable to understand.

Level 4: Code (Optional)

By scaling up the component, we will see the detailed information in bottom layer. This is the code of level 4 (L4). Of course, the so-called code here still takes the form of diagrams such as UML class diagrams and database E/R diagrams. These diagrams show the code structure in classes- or file-level granularity, but they are not the real code. Even so, code diagrams are too detailed in 99% of architecture description scenarios. On the one hand, they are numerous and have high cost of drawing. On the other hand, they are easy to be changed and have high maintenance costs. Therefore, only important and complex components need to use this layer for description. If you do need to draw code diagrams, you’d better give priority to the automatic ways. For example, many IDEs support automatic generation of UML class diagrams.

Supplementary Diagrams: Landscape / Dynamic / Deployment Diagram

In addition to static structure diagrams of each level above, the C4 model also proposes a series of supplementary diagrams as follows.

• System landscape diagram: It has the similar drawing method with the system context diagram. The difference between them is that, from the perspective of the enterprises or organizations, the system landscape diagram shows all software systems panoramically, including those not directly related to the current system. It also shows related users and system interactions. In other words, it furtherly zooms in the scope of the architecture diagram.
• Dynamic diagram: As the structure diagram can only describe the static structural properties of a system, we recommend you use communication diagrams or sequence diagrams of UML in the C4 model. These diagrams provide supplementary descriptions for dynamic behaviors of key procedures in the system. In other words, it shows the “combination of dynamic behaviors and static properties”.
• Deployment diagram: In addition to the lack of dynamic properties, the structure diagram has another limitation. It only describes the abstract logic architecture of the system, but does not describe the specific physical architecture in actual deployment. Therefore, we recommend you use deployment diagrams of UML in the C4 model. They provide supplementary descriptions for mapping relationships between logical nodes (generally referring to containers of L2) and physical nodes (such as physical machines, virtual machines, Docker containers, and application runtime). In other words, the deployment diagram shows the “combination of virtual and physical architectures”.

With the combination of these supplementary diagrams, the C4 model could be a complete architecture drawing method for comprehensively describing all aspects of the software architecture in depth.

Arc42

Strictly speaking, arc42 is not an architectural drawing method, but an architecture document template. Although diagram is a better choice than text in the architecture description as mentioned earlier, you still need to produce a relatively complete architecture document with both texts and diagrams. Arc42 is designed to help you better write architecture documents including the most important architecture diagram in the architecture documents. Multiple core chapters of arc42 introduction are related to the architecture diagram, and corresponding drawing methods are described in detail. Here I will not introduce the arc42 in detail, but briefly introduce similarities and differences of drawing methods between arc42 and C4 model.

Great ideas are always similar, and arc42 is no exception. The right part of the figure on the left summarizes several core chapters of arc42 that related to drawing.

• Chapter 3 Context: This chapter introduces the background and context of the system, so its drawing idea is almost equivalent to system context diagram (L1) in C4 model.
• Chapter 5 Building block view: This chapter introduces basic elements of the system. Its guiding idea is similar to the top-down hierarchical splitting idea in C4 model. The only difference is that arc42 does not stipulate specific levels of splitting, only provides a splitting direction from “black box” to “white box”, if needed.
• Chapter 6 Runtime view: It is equivalent to the supplementary runtime diagram in the C4 model.
• Chapter 7 Deployment view: Similarly, this is equivalent to the supplementary deployment diagram in the C4 model. However, arc42 emphasizes that the deployment diagram can also be split in a top-down hierarchy like the structure diagram. For more complex deployment architectures, hierarchy is really necessary.

Therefore, in essence, drawing methods advocated in arc42 are equivalent to and compatible with those in C4 model, and they can be used together. In practice, we use arc42 as the architecture document framework, and C4 model for architecture drawing.

Other Drawing Methods and Tools

In addition to above methods, many other excellent architecture drawing methods have emerged during decades of vigorous development of the software industry. These methods include some universal methods such as SysML, AADL, ArchiMate, and some domain-specific methods such as BPMN commonly used in background business modeling scenarios of enterprises. If you are interested in these methods, please search and explore on your own.

So far, this chapter has introduced various methods of architecture drawing. However, in the actual process from methods to practices, there is still a crucial step. That is, what kind of tools should be selected for drawing? As the promoter of digital reform, programmers must fully use digital tools. I believe that everyone must have collected a lot of handy drawing tools in your daily work. Here, I only recommend two that I use the most.

• draw.io: This is an open-source and on-line drawing software that many people may have used. For data security reasons, I recommend you use off-line desktop edition. As a programmer-friendly drawing tool, the biggest advantage of draw.io is its support for third-party plug-ins. For example, the open-source c4-draw.io plug-ins could help you draw C4 model architecture diagrams in draw.io more conveniently.
• PlantUML: As the representative tool in text drawing, PlantUML can be used to draw various types of UML diagrams, and other diagrams that are applicable to text drawing scenarios, such as the open-source C4-PlantUML extension. In these scenarios, text drawing has many advantages over visual drawing in lightweight, efficiency, versioning, automation, consistency, and easy reuse. Text drawing tools have been born for a long time. For example, the widely used Graphviz first released in 1991. However, it is believed that with the awakening of various modern consciousness of XXX as Code, this kind of Diagram as Code tools will attract more users. By the way, Yuque’s documentation has already supported embedded PlantUML drawing.

Summary of Architecture Drawing Methodology

It is better to teach people methodology than to introduce methods. Although the word “methodology” has been used widely in enterprises, it does have its value and meaning.

Methodology is the abstraction of methods in higher dimension, from which detailed methods for solving problems can be derived. Only after understanding the methodology, you can achieve a thorough understanding and master essential key points of solving problems. You will not be limited by a single specific method, because any method can be used quickly and flexibly, and you can get almost the same effect.

Therefore, in the last part of this article, I summarize various architecture drawing methods and try to extract a general architecture drawing methodology. I hope to help you better understand principles and ideas of architecture drawing. Even though those well-known methods and tools will eventually be out of date, you can still take it as the transition from old ones to new ones. In the past, there was UML; now we have C4 model, and what will there be in the future? However, this is not important, because even if those methods will be out of date, the methodology will not.

The question is what kind of core methodology is supporting those numerous methods? With “painstaking” efforts for nearly 15 seconds, I finally summed up the following set of methodology. Just kidding! Since it contains five interlocking points, just call it the five rings theory.

Understand Drawing Objectives

The first main point of architecture drawing is to have a deep understanding of drawing objectives. The so-called “take the beginning as the end” teaches us to move forward clearly only with the goal. Or otherwise, we may lose our way or even get the opposite result. Many of drawing objectives actually have been mentioned earlier. Here I’d like to give a brief summarization.

• Accuracy: A wrong diagram is worse than no diagram. Even if a diagram is accurate at the beginning, it still needs to be regularly updated and proofread.
• Completion: Drawing needs to cover core elements and key information of the architecture, providing a complete architecture design for audiences.
• Clarity: It is best to use legends, such as different shapes, colors, line types and arrows when drawing. You also can add annotations by texts when it is hard to explain only by diagrams.
• Consistency: For example, it is better to use the same tick style to reduce understanding difficulties for audiences in diagrams of the same type. In addition, inconsistency may also cause confusion.
• Conciseness: On the basis of meeting above four points, it is also necessary to make the diagram more concise. For one thing, it is easier to be accepted. For another, it is also lower in update and maintenance costs.

Identify Audiences and Their Concerns

The second point of architecture drawing is to find out audiences and their concerns. If you can’t find it, either the effect will be greatly reduced, or it will be hard for your audiences to understand. Some common audiences and concerns may include as follows.

• Research personnel usually focus on many implementation-related details, such as technical selection, implementation feasibility, and maintainability. After all, they are the most direct consumers of the architecture.
• O&M engineers do not care much about the specific technology implementation in an application, but they care about physical deployment methods, network connectivity, and O&M performance of each application instance.
• Security professionals only focus on security risks in the system, such as malicious code or permission vulnerabilities. If you have undergone a security review, you should be impressed.
• Products promotion staff only care about whether the project can be launched on schedule in most cases. However, they really don’t care about or understand other aspects.

Top-down and Layer-by-layer Description

The third point of architecture drawing is top-down and layer-by-layer description through reasonable application of hierarchy. Whether it is C4 model or arc42 template, hierarchy is deeply applied and significantly emphasized. The reason is that it contains two universal principles.

• Divide-and-manage principle: It is the most effective way in controlling and dealing with complex systems in the software field. Hierarchical splitting is essentially a divide-and-manage method. By this method, the system is split into multiple relatively independent and low-coupling elements such as subsystems, applications and components according to detailed degrees of different levels.
• Pyramid principle: My core idea is to present the main point first and then demonstrate it with each sub-point in turn in a top-down way. This way of communication is more in line with human thinking logic and easier for audiences to accept. In short, it focuses on key point. This principle helps audiences focus on key point, instead of throwing out a lot of scattered things for understanding and deducing by their own.

Use Multiple Architectural Views

The fourth point of architecture drawing is similar to the traditional engineering drawing methodology, which refers to using multiple architectural views to describe the architecture. In engineering drawing, any three-dimensional products, from machine tools to parts, need to be described by at least three views: main view, top view and left view. As a reflection of the real world, the software system is also multi-dimensional, and it is impossible to cover all the key architecture information with only one view. Even if all this information is forcibly stuffed in one diagram, it will certainly be too complicated to be understood.

In the field of architecture design, architectural view has a special definition. It is a description of one aspect of a system’s architecture, and each view covers one or more architecture concerns of the stakeholders. The above definition shows that different architecture views have different focuses. At the same time, other details unrelated to the current view are omitted when describing aspects you focus on. This is actually similar to divide-and-manage principle of hierarchical splitting. Architectural view is the dimension decomposition for the complete system, while the hierarchy is for a specific view to do top-down vertical drill-down. Both are orthogonal and can cooperate with each other. For example, the structure view, the deployment view, and even the dynamic view mentioned above can all be furtherly split in a hierarchical manner.

Follow Specifications and Best Practices

The fifth point in architecture drawing is an old saying, but it is a truth. Follow specifications and best practices. This point is no longer limited to architecture drawing, but has risen to the level of universal methodology in the field of engineering practice. As stated in the previous chapter, the goal of learning architecture drawing is to change it from a craft to an engineering. So, the drawing process of architecture certainly should conform to the engineering thinking.

On the one hand, drawing needs to follow clear specifications, and conduct constraint and guidance on the theoretical level. Thus, the high quality and standardization of processes and products can be ensured.

On the other hand, drawing also needs to follow best practices in the industry, continuously absorb excellent experience in practical level, and constantly improve drawing skills of ourselves and the team.

Appendix: Standardized Conceptual Model of Architecture Description

In fact, special standards, such as ISO, IEC, IEEE 42010:2011, have been established for the architecture description internationally. Many concepts of these standards are mentioned in this article, including stakeholder, concern, view, and viewpoint.

Original Source:

Architecture Drawing: Tools and Methodology