The author | ChuHeng

preface

The term “architecture drawing” may seem obscure at first glance, but when it comes to “engineering drawing”, it is believed that most programmers with engineering background will be familiar with it. They can even recall the days when they spent all those years in the dormitory making drawings with their left hand compasses and right hand ruler until late at night.

Software engineering is also engineering, so some basic theories of traditional engineering drawing are also applicable in software industry. On the other hand, there are fundamental differences between software and physical manufacturing, so the requirements and methods of drawing are so different that they cannot be applied directly. As a software professional, you don’t have to know anything about engineering drawing, but you have to know architectural drawing — it’s a required course in any programmer’s career.

The second half of this article will describe how to describe and communicate your architectural design using diagrams. It is important to note that this article does not focus on a single approach or tool, but rather on the general methodology behind those good approaches: the nature, commonality, and best practices of architectural drawing. It is hoped that this paper can serve as a guide to arouse people’s attention, examination and thinking about architecture and drawing in their daily work. So much the better if it can actually improve the efficiency and effectiveness of cartography a little bit.

What is software architecture?

1. Software architecture definition

Architecture is defined by IEEE as a set of basic concepts and properties of a system in an environment, represented by its elements, relationships, and principles for design and evolution.

CMU Software Engineering Institute definition: architecture is a set of structures used to represent the system, specifically composed of software elements, relationships between elements, and their properties **.

As defined by Uncle Bob in Clean Architecture, Architecture is the shape given to the system by the creator. The specific form of this form comes from the division and arrangement of system components, and the way these components communicate with each other.

2. Architecture core elements

Combining the above authoritative definitions, the architecture of a software system generally needs to contain the following four core elements:

  • Elements: Breaking up a system into a set of elements – modules, components, structures, subsystems;
  • Relationships: Relationships between different elements — interactions, dependencies, inheritance, composition, aggregation;
  • Properties: Attributes that each element has – name, responsibility, interface, implementation restrictions, etc.
  • Principles: Why it was designed this way – break down the rationale, design principles, decision reasons, etc.

Why is architecture important?

1. Architecture is the blueprint for system implementation

Recently, there is a popular online TV series called Skyscraper, which tells a strange and mysterious story. Why are you talking about that? Because I want to borrow the title of the play to ask a question: Who built the skyscrapers? You might say to yourself, “Duh, the builders put it up brick by brick.” Think it over? Are there a bunch of distracted architects (like the handsome Jason Lin) and civil engineers behind them? They do not carry bricks or cement, but without the intricate drawings they produce, skyscrapers could not have been erected as quickly and smoothly as rural houses, relying only on the experience and imagination of workers.

It is the blueprints that allow the hundreds of thousands of workers to work with each other and set standards for acceptance: they follow the blueprints and add the tiles they are responsible for; As long as the blueprint is correct and the construction process is correct, it is only a matter of time before the project is completed.

Like architecture, automotive, or any other engineering industry, software needs blueprints before it can be implemented (coded); One of the most important blueprints is the architectural design. With no architecture, and just a vague vision in the programmer’s head, you might be able to create something nice and useful by yourself like a traditional craftsman (like Linux version 0.01), But it is not possible to engineer a team to build a complex software system the size of a skyscraper (like the modern Linux system). On the one hand, the human mind is ultimately limited and must rely on architecture, a highly abstract and simplified blueprint, to make the creation, understanding, analysis and governance of complex systems feasible. On the other hand, large-scale systems with a certain degree of magnitude can only be completed by the division of labor and cooperation of many people, and architecture is also an important basis for the communication and collaboration of many people.

2. Architecture is the foundation of communication and collaboration

The final value output of a software project is the software system, and architecture, as the soul and skeleton of the software system, can play the following roles:

  • Understanding alignment: All software systems are designed to fulfill user needs, but there are an infinite number of possible ways to do so (software is more flexible and knowledge iterates faster than in traditional engineering). Architectural design is about choosing the most appropriate implementation path, and therefore involves a lot of key path decisions (why split? Why choose technology A over technology B? . These important technical decisions need to be recorded and synchronized in the form of architectural descriptions so that all project team members can align their understanding of the system and reach a consensus.

  • Quantification of work: One of the most important steps in project management is man-hour assessment, which is the direct basis for determining project schedule and milestones. Obviously, it is impossible to quantify the project workload scientifically only through PRD/interaction diagram, because it is difficult to intuitively judge how much code is needed and how difficult it is to implement behind a brief requirement or a simple page. With a clear architecture, the vast majority of development effort is theoretically visible, predictable, and disassembled, and can naturally be quantified more accurately. Of course, accurate workload estimation has always been a mystery in the IT industry, where the actual time limit can be influenced by so many unknowns, including a programmer’s skill level, mood, and hunger.

  • Standard terminology: Programming as a creative endeavor is in some ways akin to writing science fiction. Good science fiction likes to build concepts, such as Tomoko in the Three-Body Problem. If you haven’t read the novel, you won’t know what it is. Software systems are just as good at creating concepts as science fiction, because the world in fiction is usually set in reality, whereas the world in software is modeled by the creator (programmer). Slightly more complex software systems introduce domain-specific or even entirely creative concepts. In order to avoid the chicken-and-duck communication barrier and misunderstanding during the project process, it is necessary to unify the terms used to describe these concepts. An important purpose of architecture is to define and explain all the key concepts involved in the system, and to use standard and consistent terminology throughout the architecture design and description process, so that everyone can truly communicate on the same channel.

  • It makes sense: Just as you need to look at the prototype diagram when discussing product interaction and code details when looking directly at the code, architecture is a necessary physical object (the concrete physical form is called an architectural description) when discussing higher-dimensional technical problems. Otherwise, it’s either a bunch of people talking to each other in the air (you can’t talk on paper), or you have to draw on a blank board every time you communicate (it’s time-consuming and easy to lose information, obviously not a long-term solution).

  • Knowledge deposition & Newcomer Training: Architecture should be continuously deposited and maintained as a document asset as important as code, and an important basis for newcomers to the project to quickly understand and get started with the system. Don’t make your system look like some legacy system in your company where the code is left behind, but the architectural documentation is not. Only some residual design memories passed on by word of mouth, struggling to maintain the life of the project.

3. Architecture determines product quality

How to measure the quality of a software product? The figure above is a software product quality model defined by ISO/IEC 25010 standard, which includes the following 8 categories:

  • Functional fitness: functional integrity, functional correctness and functional appropriateness;
  • Performance efficiency: time performance (e.g., response time), resource utilization and capacity;
  • Compatibility: co-existence (e.g., co-existence of multiple versions of components) and interoperability;
  • Usability: learnability, operability, user error protection (e.g., automatic error correction), UI aesthetics, accessibility;
  • Reliability: maturity, availability, fault tolerance, recoverability;
  • Security: confidentiality, integrity, non-counterfeiting, authority and auditability;
  • Maintainability: modularity, reusability, analyzability, modifiability, testability;
  • Portability: adaptability, installability and substitutability.

All of the points listed in the quality model above are important considerations for architectural design. Which in addition to the functional suitability, other all point belongs to the category of nonfunctional requirements, which is to distinguish the real watershed – a good architecture design, architecture will not stay on the only meet the functional requirements of this most basic needs level (the worst architecture design can do the same), what is more important and more difficult to deal with many other non-functional requirements.

Of course, you can’t have your cake and eat it too. Architecture, like life, is also a game of tradeoffs, not to be the same as the mother of Dragons in the eighth season: both want and want, but finally nothing. Good architects should learn from Comrade Snow and “know nothing” but “know everthing” : All stakeholders of the system can be identified, concerns of all parties can be explored, and architectural decisions can be balanced accordingly so as to achieve the ultimate architectural goal of good for all.

4. I can tell you more

But for the limited space, this PPT page is obviously not enough:

  • Architecture contains all of the system’s most important early decisions, which in turn influence all subsequent technical decisions, large and small. Therefore, early architectural design needs to be very rigorous and careful, as much as possible “do it right once” (although it is difficult), otherwise the cost of correcting errors later will be higher;

  • Architecture has a very high reuse value in an organization, because products in the same organization must have many commonalities (requirements, limitations, environment, etc.), which is suitable for maximizing reuse at the architecture level to avoid solving similar problems repeatedly.

  • Conway’s Law states that software architecture reflects organizational structure. The reverse is also true: good structures make organizations more efficient;

  • The larger and more complex the system, the more important the architecture is, because only a good architecture can effectively control, manage and reduce the system complexity;

  • Does it seem like architecture has an infinite number of interpretations and meanings? Don’t get too tangled up, follow GoF’s design pattern: Architecture is about the important stuff. Whatever that is. Yeah, whatever it is, just remember that architecture matters.

How to design a good architecture?

Once you understand the concept and importance of architecture, the path of true architect training has just begun. How to design a good architecture? This is obviously a very broad and profound topic, but it is not the focus of this article, so here are just some basic ideas (principles) and classic patterns (patterns). Of course, architecture design is closer to an empirical discipline, and it is not enough to just blurt out some mysterious and lofty theoretical concepts. It is necessary to practice and figure out more based on the actual work content and business scenes. Otherwise, it can only be considered as wandering outside the door of architecture, even unable to talk about the beginning.

1. Principles of Architecture

SOLID Principles are a classic and popular set of architecture principles (mostly well named) :

  • Single responsibility: Consistent with the Unix philosophy of “Do one thing and Do it well”;

  • The open/close principle: to replace modification (breaking existing encapsulation) by adding (extending), which is similar to the immutable idea of functions;

  • Where A parent class can appear, A subclass must appear, so that they have an inherited “IS-A” relationship;

  • Interface isolation: Do not make one class dependent on an interface that is not used by another class. In short, this means minimizing interface dependencies and coupling between components.

  • Dependency inversion: Relying on abstract classes and interfaces rather than concrete implementations; Let the low-level modules depend on the stable abstraction of high-level modules to achieve decoupling.

In addition, we try to follow the following principles in our architectural design (which is essentially the same as the above SOLID principles) :

  • Orthogonality: Components separated from the same level of the architecture should be as orthogonal as possible, that is, each other’s responsibilities are independent, the boundary is clear, and there is no overlap.

  • High cohesive: A component should be highly cohesive, like an indivisible whole (it should be dismantled otherwise);

  • Low coupling: Components should be coupled as little as possible to reduce interaction and enhance component reusability.

  • Isolate change: The essence of many architectural principles and patterns is to isolate change — to isolate the parts that are expected to change, and to reduce other stable parts that are affected (requiring code changes, retesting, or potential failures) when changes occur.

2. Architectural Patterns

Architectural patterns are not the same thing as the design patterns we often talk about, but when viewed only as “patterns,” the idea is the same: generic, reusable solutions to problems that often arise in a given context. The main difference is that the architectural pattern is more dimensional abstraction and more holistic (applied at the architectural design level, after all).

Common architectural patterns include both traditional ones (e.g., layered, C/S, MVC, event-driven) and emerging ones (e.g Cloud native, microservices, Serverless). Different patterns have different application scenarios, and no one pattern can kill all requirements. A mature architect should act like an emotionless killer, always objectively evaluating and choosing the best solution for the moment, even if it seems tedious to do so; Immature architects, on the other hand, focus on making things happen (e.g., imposing microservices architectures) rather than actually fixing the problem.

How would you describe your architectural design?

With a good architectural design, the long march has already gone more than half way. It’s like a young director meeting a good script for the first time, his heart surging and his eyes shining, as if he had already foreseen the box office success of the movie. Of course, the remaining half will not be as smooth as imagined – the same script, different directors will have the same quality of difference. A good “best director” is capable of making “best picture” even when faced with a script that is not “best screenplay”. Similarly, a good architect should be able to describe a good architectural design; Even if you can’t add extra points for the wonderful content, you shouldn’t lose points because you haven’t described them well in form. Otherwise, you will feel oppressed and sad just like losing points for your composition in the college entrance examination.

1. Significance of architecture description

Why describe architecture? Can’t I just keep it in the back of my mind? There is a saying in the West: a bad pen is better than a good memory. Anything that is not persisted is volatile, just like memory. On the other hand, as mentioned above, Architecture is the basis of communication and collaboration. If Architecture Description is not deposited for all stakeholders to see, the only carrier of communication and dissemination will be lost.

From personal observation, there is no disagreement that architecture needs to be described, so most projects will produce some form of architecture description document. But the gap between “architectural description” and “good architectural description” is huge, even bigger than the difference between “not” and “have.” If you’re like me, you’ve been through countless architectural documents, clapped your hands in gratitude, or slapped your thighs in anger.

2. The way architecture is described

A writer will choose words to describe the same thing, while a painter will use pictures. Although the message is the same, the difference in the way it is described can make a huge difference in effectiveness. There are also two forms of architectural description: Text and Diagram, each of which has its own advantages:

  • Behind the text is a set of rigorous and complete language as a support, so its description can be very precise and detailed, but also very convenient to write, just open a notepad software can write; In addition, like writing code, text is easy to version, with a simple text diff tool that makes it easy to compare the details of different versions at a glance.

  • In contrast, the graph does not have the unique characteristics of the above characters, but it also has its own unique advantages: the graph is intuitive and graphic, which conforms to the innate visual recognition instinct of human beings; In many cases, the information conveyed by a small picture (such as spatial location relationship, color classification, icon shape) may not be fully and accurately described in a thousand words. In other words, “a picture is worth a thousand words”.

Cleverness of you sneer 1: hum, again be not a child must do choice topic, difficult way can’t text and graph all want? Of course, the ideal architectural description must be graphic. But the real world is harsher than the ideal, and it’s hard to leave enough time for a perfect architectural document on a real software project. If you think in terms of ROI as an adult, drawing will be your priority.

3. Why should you draw first?

The Agile Software Development Manifesto states that Working software over comprehensive documentation is more important. This doesn’t mean you don’t need to document, just that you don’t need to document too much. Why is that? Because detailed documentation requires a lot of writing and maintenance costs, it does not conform to the principles of agile development such as small iterations and rapid response to change.

So, in today’s age of fully agile development, how do you adapt to the trend of more agile architectural documentation? ROI is your friend – not much, but refinement, try to express the most core content with the least amount of ink. In terms of content, the part with high ROI is generally the top-level overall architecture or the most core key link, which is also reflected in the C4 model concept later. In terms of form, pictures have incomparable expressive advantage in front of text, which is obviously a choice with higher ROI.

4. Why do you need to learn to draw?

Drawing is all right, but is it necessary to specialize in it? It’s not a sketch, just a bunch of rules and regulations. Anyone with a little engineering knowledge can do it. It’s a little ugly, right? That has nothing to do with, at most use the artistic aesthetic feeling of innate bit again, pair of these a few lines align that a few boxes swing is put, what of the setting color of dot multicolor again, appear very professional?

See here, the screen before you scornfully smile again: hum, apparently not so simple. Indeed, we all know that architectural drawing, like engineering drawing, is a matter that needs to be seriously and rigorously treated. But in reality, most people don’t have the time to make the effort, like the two common architectural diagrams posted above. The first picture needless to say, this kind of sketch daub is good, but put out to see people is your wrong. What about the second picture, which looks a little bit like that? Not really. If you look a little bit more closely, you’ll see a lot of ambiguity and imprecision underneath this map (see The Art of Architectural Diagrams).

So being able to draw doesn’t mean being able to draw well; It takes constant learning and deliberate practice to make beautiful and readable pictures, and it is difficult to grasp the key points by intuition and understanding alone. In addition, the wrong figure is often worse than no figure, even if you only embrace “have figure, almost mean that got” mentality, also should understand at least some key elements of scientific cartography, avoid to the already complex difficult projects and covered a layer of fuzzy filters, and even have the adverse effect of confusion and misleading.

5. Objectives of architectural drawing

Before discussing specific mapping methods and tools, we need to establish clear mapping objectives. Tools are the ladder of human evolution, but if not properly understood and used, it is easy to be restricted by tools or even enslaved, forgetting the original purpose of inventing and using tools in the first place. There are so many different methods and tools available for architectural drawing, what is the original intention of using them? I think it’s all about transforming cartography from a free craft into a scientific project: systematic, rigorous, complete, standardized, repeatable, sustainable, and efficient.

P.S: I was in a hurry to make PPT at that time, so I had to take the minimalist route for the illustration from this chapter. Please forgive me…

Architecture drawing methods and tools

After the “brief” paving of the previous chapters, I believe that everyone has enough cognition of the background knowledge of architectural drawing. This chapter will list and describe some typical architectural drawing methods and tools in detail, some of which are common and some are rare. The emphasis is to deepen people’s understanding of the essence of drawing methods through horizontal comparison of various methods.

1. Method 1: UML

UML is probably the drawing method most people are most familiar with, and the latest UML 2.x release consists of two broad categories of diagrams:

  • Structural Diagrams: The static structure of the system is emphasized through objects, properties, operations and relationships, among which the most common types include Class diagrams, Component diagrams and Deployment diagrams.

  • Behavioral Diagrams: Emphasizing the dynamic behavior of the system by showing collaboration between objects and state changes within them, The most common types include Use Case diagrams, Activity diagrams, Sequence diagrams, and State Machine diagrams.

As the universal “Unified Modeling Language”, UML contains a total of 14 different types of diagrams, covering the full range of cartographic requirements in software design, including, of course, architectural cartography. At the same time, because UML considers itself a language, its notion and sematics are rigorously defined, without ambiguity or ambiguity. Finally, after decades of development and promotion, UML has become a standard specification widely used around the world. The hidden value of UML is that the cost of communicating with UML within a team is lower, because it can be assumed that most technical people can understand the meaning and usage of UML.

However, UML is not a panacea (although historically it has been regarded as the silver bullet of software design), and its most notorious shortcoming is that it is too complex. You can’t blame UML. After all, it was designed to be universal, rigorous, and powerful enough, goals that were the antithesis of “simplicity” and helped it evolve into the complex, rigid behemoth it is today. Although we confidently assume that most technical people know UML, with a degree quantifier, I think the average “know” is good at about 20% — most of them know a few common class diagrams, sequence diagrams, and have a hard time saying exactly what the arrows in a class diagram mean.

After all, UML should still be one of the most commonly used and necessary tools in every programmer’s graphics toolbox. Of course, it shouldn’t be the only one, because there are also some must-see items below.

2. Method 2:4+1 View Model

“4 + 1” is what? Never mind if you don’t know. Have you ever heard of “six plus one”? Yeah, the “Very 6+1” show I used to watch as a kid. It has as much to do with 4+1 as it does with Shao Jiayi, Zhang Jiayi and Shen Jiayi, except that they happen to share the same suffix.

So what exactly does “4+1” mean? 4+1 is a view model that describes the architecture of a software-intensive system through multiple co-existing views. These views are based on viewpoints of different project stakeholders, such as end users, developers, systems engineers, and project managers. “4+1” consists of four basic views and a few selected use cases or scenarios (additional “+1” views), each of which has the following meanings:

  • Logical view: Describes the functions provided by the system for end users. It is usually represented by class diagrams and state diagrams in UML.

  • Process view: describes the dynamic behavior of the system, including processes and interactions. It is generally represented by sequence diagrams, activity diagrams and communication diagrams in UML.

  • Development View: Describes the system from the programmer’s point of view, also known as the “implementation view”, usually represented by component diagrams and packages in UML;

  • Physical view: Describes the system from the perspective of a system engineer, including the Physical topology of system components and Physical connections between components. Also called deployment view, it is generally represented by deployment diagrams in UML.

  • Scenarios: Architecture is described through a small set of use cases or Scenarios, including the sequence of interactions between various objects and processes in the system, also known as a “use case view.” These scenarios are used to identify architectural elements and to illustrate and validate the overall architectural design, and can also be used as a starting point for testing architectural prototypes.

Although the various views of “4+1” mentioned above are generally represented by UML diagrams, in fact “4+1” itself is a general view model and does not limit the notations and tools for drawing. For engineers, this more academic approach may never be used directly, but the key architectural mapping idea is valuable: an architecture needs to be described through multiple views from different stakeholders; Only in this way can a set of comprehensive, three-dimensional and objective architectural description be produced.

3. C4 Model

The C4 model is an “abstract-first” architectural drawing method, which is also inspired by the previous UML and “4+1” view model, but is relatively simple and lightweight, containing only a small set of abstractions and diagrams and is easy to learn and use.

1) Definition, concept and key ideas

The C4 model describes the static structure of a software system through the abstractions of containers, components, code and people. Its core idea is to build a navigation Map for code that can be enlarged and shrunk through different levels of detail like Google Map. The key idea is to split the static structure of the system step by step from the top down, and describe the responsibilities, relationships and external dependencies of objects at each level in turn. In addition to the core hierarchical static structure view, it can also contain dynamic view, deployment view, and other complementary views.

The left figure above shows the mapping between levels of abstraction in the C4 model: 1 software system consists of 1 N containers, 1 container consists of 1 N components, and 1 component consists of 1~N code structures. The figure on the right takes a simple Spring PetClinic project as an example to demonstrate the hierarchy of a real software system under the C4 model. The top layer is the PetClinic software system, which can be split into several containers such as database and Web application. Web applications can be further separated into ClinicService components, which in turn contain ClinicService interface classes, ClinicServiceImple implementation classes, Owner/Pet/Visit domain object classes, and so on.

Architectural charting using the C4 model is essentially a visualization of these abstractions. This is done by creating the following structure diagrams from thick to thin: Context, Container, Component, and Code (optional), which is where the C4 model gets its name.

2) Level 1: System Context diagram

The system context diagram, as the first level (L1), provides a big picture view of the entire system, including the central software system, surrounding users, and other interacting systems. The two most critical concepts are:

  • Person: refers to the user who uses the software system, such as the consumer of an online shopping mall system, the operating minor, the system administrator, etc.

  • Software System: As the highest level of abstraction, describing Software products that create value for users; This includes both the software system currently being designed and other software systems that the system depends on (or is dependent on). A software system is usually the responsibility of a single software development team.

When drawing a system context diagram, you don’t need to care about any of the low-level details such as technology stacks, protocols, and so on. The audience for this type of diagram is the widest, because it is accessible and informative to anyone, both technical and non-technical, as well as team members and non-team members.

3) Table 2

After understanding the positioning of the system in the overall IT environment from the L1 context diagram, the next step is to zoom in on the system frame and see in detail what “containers” (not to be confused with Docker containers) IT contains. . The container in C4 model refers to a single application or data store, which can be deployed and run independently (with independent process space and communicate with each other through THE IPC mechanism), such as SpringBoot microservice, React SPA, mobile App, database, Serverlss function, and Shell script.

The L2 container diagram not only shows the further separation of responsibilities of the system, but also includes key architectural information such as key technology selection and communication modes between containers. This kind of diagram can be aimed at all technical personnel, including architects, developers, operations personnel, technical support personnel, etc.

4) Level 3: Component diagram

Continuing the previous routine, the next step is to enlarge each container in the system and further divide each container into multiple components. In the C4 model, a component is a set of related functions (usually running in the same process space) encapsulated by a well-defined interface, for example: A Controller in Spring (including not only the main Controller class that defines the REST interface, but also all the associated implementation classes such as Service/Repository).

Similar to the container diagram, L3 component diagram not only contains the component division of the container, but also includes the responsibility definition, technology and implementation details of each component. As the layers sink down and the details grow, the audience for component diagrams Narrows further, typically only for software architects and developers (other roles don’t necessarily understand it, and generally don’t).

5) Level 4: Code (optional)

As you zoom in on the component, the most low-level and detailed information you can see is L4’s Code. Of course, the “code” here is still in the form of diagrams (e.g., UML class diagrams, database E/R diagrams) showing the class – or file-granular code structure, not the actual code itself. Even so, code diagrams are too detailed in 99% of architectural description scenarios. On the one hand, they are massive and costly to draw. On the other hand, it is easy to change and the maintenance cost is very high. Therefore, only very important and complex components typically need to be described at this level. If you do need to draw, automation should be a priority, as many ides support automatic generation of UML class diagrams.

6) Supplementary Diagram: Landscape/Dynamic/Deployment Diagram

In addition to the static structure diagrams of each level above, C4 model also puts forward a series of Supplementary diagrams, including:

  • System Landscape diagram The drawing method of panorama is similar to that of system context diagram, but the difference lies in that it shows all software systems (including those not directly related to the current system) and related user and system interactions from the perspective of enterprise or organization, that is, further enlarging the scope of architecture diagram.

  • Dynamic diagram: Since the structural diagram can only describe the static structural attributes of the system, it is recommended to use the communication diagram and time sequence diagram in UML in C4 model to supplement the Dynamic behavior of the key links in the system, that is, the combination of Dynamic and static.

  • In addition to the absence of dynamic attributes, the above structure diagram also has a limitation: it only describes the abstract logical architecture of the system and does not describe the physical architecture of the actual Deployment of the system. Therefore, the C4 model recommends reusing UML deployment diagrams for both system logical nodes (typically L2’s “container” granularity) and physical nodes (e.g The mapping between physical machines, virtual machines, Docker containers, and application Runtime is described, that is, the combination of virtual and real.

The C4 model combined with these supplementary diagrams is the complete architecture drawing method that can describe all aspects of software architecture comprehensively and stereoscopic.

Method 4: ARC42

Strictly speaking, ARC42 is not an architectural charting method, but rather an architectural document template. Although, as mentioned above, “graphics” is a better choice than “words” in architectural descriptions, you still need to produce a relatively complete architectural document with graphics and words during the course of a real project. Arc42 is designed to help you better document your architecture; As one of the most important architectural diagrams in architecture documents, arc42 is obviously not missing either — several of the core chapters are related to architecture diagrams and describe in detail the corresponding drawing methods. I will not introduce arc42 in detail here (not to steal the next article), but I will briefly introduce the similarities and differences between arc42 and C4 model.

Great ideas are all alike, and ARC42 is no exception. The right part of the upper left figure summarizes several core chapters related to cartography in arc42 template, which are:

  • Chapter 3 – Context: This chapter introduces the background and Context of the system, so its mapping idea is almost the same as L1 (System Context diagram) in C4 model;

  • Chapter 5 – Building Block View: This chapter is used to introduce the basic elements of the system. According to the official guiding ideology, it is the same as the top-down splitting thought in C4 model. The only area is that ARC42 does not specify the specific level of splitting, so as long as necessary, it can be divided according to the routine of “black box -> white box”.

  • Chapter 6 -** Runtime View ** : This is equivalent to the run-time view in the C4 model.

  • Chapter 7 – Deployment View: Again, this is equivalent to the complementary Deployment view in the C4 model; However, Arc42 emphasizes that the deployment view can be split hierarchically from top to bottom just like the structural view (which is necessary for more complex deployment architectures).

Therefore, in essence, the mapping method advocated in ARC42 is equivalent and compatible with THE C4 model, and can be fully used together: ARC42 is taken as the framework of the architecture document, in which the more specific C4 model is used for architectural mapping. This is actually the approach we are using in our project.

5. Other methods & drawing tools

In addition to the above methods, many other excellent architectural mapping methods emerged during the decades of software industry boom, including both general methods such as SysML, AADL, ArchiMate, and domain-specific methods such as BPMN, which is common in back-end business modeling scenarios in the enterprise. Describing each approach in more detail would obviously make this article (though it seems predestined at the time of writing) too long for interested readers to search and explore for themselves.

Up to this point, this chapter has covered various approaches to architectural drawing; However, in the actual process from method to landing, there is still an unavoidable link: what kind of tools to choose to draw? You can’t really use pen and paper like you do engineering drawings, can you? As digital innovators, programmers should embrace digital tools. You must have accumulated a lot of handy drawing tools in your daily work, so HERE I only recommend two that you use a lot:

  • Draw. IO: This is an open source online drawing software that many of you have used. For data security reasons, it is recommended that you use a completely offline desktop version. As a programmer friendly drawing tool, the biggest advantage of Draw. IO is that it supports tripartite plug-ins, such as the open source C4-draw. IO plug-in, which makes it easier to draw C4 model architecture diagrams in Draw. IO.

  • PlantUML: As the representative tool for text drawing, PlantUML can be used to draw various types of UML diagrams, as well as other diagrams suitable for text drawing scenarios (such as this open source C4-Plantuml extension). In these scenarios, text cartography has incomparable advantages over visual cartography: light weight, high efficiency, versioning, automation, consistency, easy reuse and so on. Although text charting tools have been around for a long time (such as the widely used Graphviz, which was first published in 1991), it is believed that with the modern awareness of various XXX as Code tools, this kind of Diagram as Code tools will gain more popularity (BTW, Sparrow documentation has long supported embedded PlantUML mapping.

Summary of architectural drawing methodology

As the old saying goes: teach a man to fish is better than to give him fish. By extension: it is better to teach methodology than to teach method. What is methodology? While the word is overused in the corporate world, it does have value and meaning: methodology is a higher-dimensional abstraction of methods that can be derived to solve problems. To understand the methodology, to master the essence of solving problems; You’re no longer limited to one specific method, because you can use any method quickly and flexibly, and get almost the same results.

Therefore, the last chapter of this paper will summarize various architectural drawing methods, and try to extract a general architectural drawing methodology, hoping to help people better understand the principles and ideas behind architectural drawing. Even if the various methods and tools we are familiar with will eventually become obsolete, it is still possible to look at them in a light light: ** UML was then, C4 is now, what is the future? It doesn’t matter, ** because even if the method is outdated, the methodology behind it isn’t.

So, what is the core methodology behind the vast number of methods? After nearly 15 seconds of painstaking thinking, the author finally concluded the following classic methodology (P.S: just make up the numbers, don’t take it too seriously ~). Because it contains five interlocking points, we can call it the theory of five rings.

1. Understand the mapping objectives

The first point of architectural drawing is to have a deep understanding of the drawing objective. As the saying goes, “The beginning is the end”. Only with a goal can we move forward clearly. Otherwise aimlessly channeling, often take many detours, or even the opposite direction. What is the goal of architectural drawing? In fact, the previous article has been mentioned a lot, here is a simple summary:

  • Accurate: A wrong picture is worse than no picture at all; Even if it is accurate at the beginning, it needs to be updated regularly.

  • Complete: the core elements and key information of the architecture should be covered to present a complete architecture design without imperfections to the audience;

  • Clear: it is best to bring legends (shapes, colors, lines, arrows) when drawing. Use pictures to describe unclear places, but also can add text annotations to supplement;

  • Consistent: for example, if a graph of the same type is consistent, it is better to use the same token style, so as to reduce the understanding cost of the audience; Inconsistencies often lead to confusion;

  • On top of the above four points, you’ve also got to make your graphics simpler, on the one hand, easier to accept (no reading = no writing), and on the other, cheaper to update and maintain.

2. Identify your audience and focus

The second point of architectural drawing is to identify the audience and their respective concerns of your drawing. If you don’t get it right, it’s either less effective (which is not what they want to hear) or it’s like casting pearls before swine (which they don’t understand). Some common audiences and concerns may include:

  • R&d: They tend to focus on many implementation details, such as technology selection, implementation feasibility, maintainability, etc. After all, they are the most direct consumers of the architecture;

  • Operation and maintenance: do not care much about the specific technical implementation within the application (as a black box), but care about the physical deployment mode, network connectivity, operation and maintenance of each application instance;

  • Security: Only pay attention to whether the system has security risks, such as the possibility of malicious code injection and permission vulnerabilities. If the experience of safety review, should be very physical;

  • Products: In most cases, I only care about whether the project can be launched on time, and other aspects… May show some concern on the surface, in fact, either do not care or really do not understand.

3. Describe from top to bottom

The third key point of architectural drawing is the proper use of hierarchical routines and top-down description. Both the C4 model and the ARC42 template are deeply used and strongly emphasized behind this. Why do we have to do this? There are two general principles:

  • Divide and conquer: In software, divide and conquer is the most effective way to control and deal with complex systems. In essence, hierarchical split is a means of divide and conquer: the system is divided into several relatively independent and low-coupling elements (subsystems, applications, components, etc.) level by level in a coarse to fine granularity.

  • The Pyramid Principle: The core idea of this book is to start with the subjective points and then use the sub-points to demonstrate them in a top-down fashion. This way of communication is more in line with the logic of human thinking, and easier for readers to accept. To put it simply, it is to “get to the point first”, to help the reader to summarize and highlight, rather than throw out a lot of details and scattered things for the reader to digest and deduce.

4. Use multiple architectural views

The fourth point of architectural drawing pays homage to the traditional engineering drawing methodology: use multiple architectural views to describe your architecture. In the world of engineering drawing, any three-dimensional artifact, from a machine tool to a part, needs to be described through at least three views (main view, top view, left view). As a mapping of the real world, software systems are also multi-dimensional and three-dimensional, and it is impossible to cover all key architectural information with a single view. Even if all this information were forced into one picture, it would surely be too complicated to understand.

In architectural design, there is a special definition of an architectural view: a description of an aspect of a system architecture; Each view covers one or more of the stakeholders’ concerns. As you can see from the above definition, different architectural views have different emphases and describe what they focus on without other details that are irrelevant to the current view — this is a divide-and-conquer idea similar to hierarchical resolution, except that it is a dimensional decomposition of the entire system. Layering is a top-down drill-down for a specific view; The two are orthogonal and can work together, such as the structural view, the deployment view, and even the dynamic view mentioned above, which can be split hierarchically.

5. Follow specifications and best practices

The fifth point of architectural drawing is really just the right nonsense: follow specifications and best practices. This point is not limited to architectural drawing, but to the engineering practice of the general methodology level. As mentioned in the previous chapter, “The goal of learning architectural drawing is to transform it from a craft to a project”, so the “construction” process of architectural drawing should also conform to engineering thinking:

  • On the one hand, cartography needs to follow clear norms, restrain and guide at the theoretical level to ensure the high quality and standardization of process and product;

  • On the other hand, cartography needs to follow the best practices in the industry, continue to learn from the best practices, and constantly improve their own and the team’s cartography skills.

Attached: The architecture describes the standardized conceptual model

In fact, there are special international standards for architecture description (ISO/IEC/IEEE 42010:2011), many of which are mentioned in this paper (e.g. Stakeholder, Concern, View, Viewpoint). Those of you who are interested can go further.

conclusion

If you’ve sat through all of this, there’s no doubt that you’re the kind of person our team is looking for to make it big:

Welcome to join the EMAS team of Aliyun Cloud Native application DEVELOPMENT platform. We focus on a wide range of cloud native technologies (Backend as a Service, Serverless, DevOps, low code platforms, etc.) and are committed to providing one-stop application development and management services for enterprises and developers. Direct email: pengQun. Pq # alibaba-INC.com.

“Alibaba Cloud originator focuses on micro-service, Serverless, container, Service Mesh and other technical fields, focuses on the trend of cloud native popular technology, large-scale implementation of cloud native practice, and becomes the public account that most understands cloud native developers.”