This page has been machine-translated and has not yet been reviewed. Parts of its content may be incomplete or incorrect.
Architecture Modeling/Visualization with the ADF
It makes sense not to describe a complex system in a single diagram but to create multiple diagrams for different aspects. The ADF framework defines different view types along with associated elements and relations. For example, in a diagram of the view type “Functions at Runtime,” one can immediately recognize the functional areas, their division, and their interaction. Unlike building architecture (keyword “floor plan” or “blueprint”), no unified notation has been established in software engineering, and often many different aspects are mixed in one diagram.
Using ADF Views
First, one should understand the dimensions by which a system can be decomposed and the different view types.
For an architectural view of a specific type, there are suitable elements and relations.
It is best to look at a few examples of views of different types.
Tooling
Architecture modeling/visualization with the ADF is a method that can be used independently of tools and technologies. ADF views can be drawn with any diagram tools or directly on the whiteboard. For the tools Diagrams.net and PlantUML, we have created pre-made elements and relations that can be used directly.
Other topics in this document:
Why Different Views?
We constantly break down complex matters into manageable parts. To understand how the human body works, a medical student uses many different illustrations showing the skeleton, the muscle system, the vascular system, etc. - and different diagrams for different body parts. The building architect creates a floor plan as an overview, floor plans for each floor, different views of the outer walls and the roof structure, and special diagrams showing power lines and outlets. And what about software?
“It is not possible to capture the functional features and quality properties of a complex system in a single comprehensible model that is understandable by and of value to all stakeholders.” [Rozanski, Woods, 2005]
While it is tempting to describe a software system in all its details in one big diagram (many people try and fail regularly), a much more feasible approach is to describe a system from different perspectives.
No Standard for Architectural Views
UML class, package, and sequence diagrams, which represent the code structure, are well known and widespread but have two disadvantages:
- They describe many implementation details that may not be so relevant for an overall view and also quickly become outdated. (Some people therefore recommend using them sparingly and generating them automatically from the code.)
- They can only be created when source code already exists or at least when it is known where code needs to be written (frontend versus backend, module in monolith versus separate microservice, …). For new developments, it is more sensible to start from the running system, break it down into parts, and then consider how these parts can be implemented as code.
For architecture work, you need views that
- visualize larger contexts, such as the interaction of multiple systems,
- describe systems and components at runtime,
- show the deployment of the system in the infrastructure,
- map development and deployment processes,
- and much more.
Although there are various architectural view frameworks, such as the 4+1 model by Philippe Kruchten or the C4 model by Simon Brown, none of them has established itself as a general standard. The former has a steep learning curve due to the multitude of different diagram types and elements, while the latter is very restrictive with the four fixed “zoom levels.” Most importantly, most models do not distinguish between views of a system at runtime and views of a system at development time.
With the ADF view framework, we provide a model for visualizing and modeling software systems that
- is freely usable,
- is suitable for all types of systems,
- makes it very clear which aspect of the system is being described through an explicit type system along the dimensions of runtime/development time and data/functions/deployment/activities, thus helping to avoid mixing too many different aspects of a system,
- can be used immediately without software installation with a single click,
- has tool support through diagrams.net (draw.io) and PlantUML and is thus fully compatible with the Documentation-as-code approach,
- is extensively documented with examples on this page.
The ADF documentation template complements the ADF view framework by creating a structure in which the views can be embedded.
The ADF Design Guide shows in which iterations one approaches a system decomposition and which views of which type are created.