Key Takeaways
The introduction of software diagrams has been scaled back due to the shift to agile methodologies. When diagrams are created, they’re often puzzled and doubtful. The C4 version comprises a hierarchical set of software structure diagrams for context, boxes, components, and code. The hierarchy of the C4 diagrams gives specific abstraction levels that apply to a one-of-a-kind target audience. Avoid ambiguity in your diagrams using sufficient text and a key/legend for your notation.
Software architecture diagrams are a notable way to talk about how you plan to construct a software machine (up-the-front layout) or how an existing software program machine works (retrospective documentation, expertise sharing, and getting to know). However, it’s very in all likelihood that most people of the software architecture diagrams you’ve visible are a harassed mess of boxes and lines. An unlucky and unintended aspect of the Manifesto for Agile Software Development is that many teams have stopped or scaled back their diagramming and documentation efforts, together with using UML.
These identical groups generally rely on ad hoc diagrams that they draw on a whiteboard or prepare using preferred-motive diagramming gear and Microsoft Visio. Ionut Basin wrote “The Art of Crafting Architectural Diagrams” last year, which describes several not-unusual issues with doing this, related to incomprehensible notations and doubtful semantics.
(Click on the photo to amplify it)
Ambiguous software architecture diagrams result in misunderstanding, which can gradually bring a good group down. In our enterprise, we should strive to create higher software structure diagrams. After years of building software programs and working with teams worldwide, I’ve made the “C4 model”. C4 stands for context, containers, additives, and code — a set of hierarchical diagrams that you may use to explain your software structure at exceptional zoom stages, each useful for extraordinary audiences. Think of it as Google Maps for your code.
(Click on the photograph to amplify it)
To create those maps of your code, you first need a common set of abstractions to create a ubiquitous language to describe a software machine’s static structure. The C4 model considers the static systems of a software program machine in phrases of containers (programs, facts shops, microservices, etc.), components, and code. It also considers the folks who use the software systems that we construct.
Personal clients of financial institutions use the Internet banking system to view facts about their financial institution bills and make payments. The Internet banking machine uses the bank’s present mainframe banking system to do this and uses the bank’s present email gadget to send emails to clients. Color coding inside the diagram indicates which software program structures already exist (the gray boxes) and which people are to be built (blue).
Level 2: Container diagram
Level 2, a container diagram, zooms into the software program gadget and suggests the bins (programs, data shops, microservices, etc.) that make up that software device. Technology choices also are a key part of this diagram. Below is a sample field diagram for the Internet banking gadget. It suggests that the Internet banking system (the dashed box) comprises five boxes: a server-facet net software, a purchaser-facet single-page software, a cellular app, a server-aspect API application, and a database.
(Click on the photo to increase it)
The web application is a Java/Spring MVC net utility that serves static content material (HTML, CSS, and JavaScript), including the content that makes up the unmarried-page application. The single-page utility is an Angular utility that runs within the client’s Internet browser, imparting all the Internet banking capabilities. Alternatively, customers can use the move-platform Xamarin cellular app to access a subset of the Internet banking capability. The single-web page software and cellular app use a JSON/HTTPS API, which another Java/Spring MVC utility walking on the server facet provides. The API software receives user records from the database (a relational database schema). The API utility additionally communicates with the present mainframe banking device, a proprietary XML/HTTPS interface, to get facts about bank debts or make transactions. The API software also uses the existing email device to ship email to customers.
Level 3: Component diagram
Level three, a thing diagram, zooms into an individual field to reveal its additives. Here is a pattern component diagram for the fictional Internet banking device that shows some (in preference to all) of the components within the API software. These components must map to actual abstractions (e.g., code grouping) on your codebase.
(Click on the photo to make it bigger)
Two Spring MVC Rest Controllers offer to get entry to points for the JSON/HTTPS API, with each controller, in the end, using different additives to get entry to statistics from the database and mainframe banking machine.
Level 4: Code
Finally, if you need or want to, you can zoom into a man or woman factor to reveal how that element is carried out. This is a sample (and partial) UML elegance diagram for the fictitious Internet banking machine showing the code factors (interfaces and instructions) that comprise the MainframeBankingSystemFacade element.
(Click on the picture to increase it)
It shows that the thing is made from several classes, with the implementation information immediately reflecting the code. I wouldn’t always recommend developing diagrams at this stage of detail, especially while you may obtain them on-demand from maximum IDEs.
Notation
The C4 version would not prescribe any unique notation. In those pattern diagrams, you see a simple notation that works well on whiteboards, paper, sticky notes, index playing cards, and diffusion of diagramming gear. You can also use UML as your notation with the perfect use of packages, components, and stereotypes. Regardless of the notation that you use, I could endorse that every detail consists of a name, the detail type (i.e., “Person,” “Software System,” “Container,” or “Component”), a technology choice (if appropriate), and a few descriptive textual contents. It may seem uncommon to have a lot of text in a diagram. However, this additional text eliminates a lot of ambiguity usually visible on software program structure diagrams. Finally, do not forget approximately the diagram name, which has to be on each diagram to describe each diagram’s type unambiguously and scope (e.g., “System context diagram for Internet banking system”).
More statistics
The C4 version is an easy way to communicate software architecture with extraordinary degrees of abstraction so that you can inform unique memories to distinct audiences. It’s also a way to introduce (frequently reintroduce) some rigor and lightweight modeling to software program development groups (frequently, reintroduce). See c4model.Com for greater statistics about the C4 model, in addition to supplementary diagrams (runtime and deployment), examples, a notation tick list, FAQs, videos from conference talks, and tooling options.
About the Author
Simon Brown is an impartial representative specializing in software structure and the author of “Software Architecture for Developers” (a developer-friendly guide to software program structure, technical management, and the balance with agility). He is likewise the author of the C4 software structure model, a technique for developing maps of your code. Simon is a normal speaker at international software program improvement meetings and travels the arena to help organizations visualize and file their software structure.
