What is a proper diagram to describe software architecture

Question

I wonder if there are well accepted/standardized types of diagrams to describe the architecture of a software implementation, for example, a Clean Architecture.

By software architecture, I mean a set of defined modules using high-level abstractions without including any libraries, frameworks, or databases.

So far, I have found only the Component Diagram as a suitable diagram. Is this correct for representing the different layers of my software? And is this sufficient to document the software architecture?

Answer 1

What is the purpose of the layers ?

The clean architecture aims to achieve separation of concerns, by dividing the software into concentric layers. The main difference compared to the traditional layered architectures is the principle of dependency: the outer parts depends on the inner part and not the contrary.

In layered architecture, the the higher strates are dependent on the lower strate. However, for graphical reasons, the lowest level tends to rely (and therefore depend) on the a data access layer which is in the outside ring in clean architectures. This leads then to entities that are dependent of the database access layer, so of their implementation.

For concentric as well as layered architecture, there is however one common ground: the layers correspond to a logical grouping of dependencies. These groupings can in some cases coincide with components, but it's not a general rule.

How to diagram the layers in UML

In UML there is no single architecture diagram that summarizes everything. As for a building, whose architecture will be described by several diagrams (e.g. front facade diagram, side diagram, ground diagram for the implementation of the building on the terrain, and a diagram for every floor) software architecture will be described with different diagrams that each focus on different aspects.

For the layers, the logical grouping of related software artifacts and their dependencies are best shown in a package diagram. A package may group not only classes, but also components, and use cases. Here a nice example.

More architecture

Structural views

At the highest level, you'll describe the system under consideration in its environment, and describe the main functions. For this you'll have a use case diagram.

Then you may divide the system into independent components, and show how these are related to each other. You'll describe this in a component diagram.

Then you can zoom in and show the inner structure of the componenets, and show the classes that being assembled make the component. You show this with a composite diagram.

Finally, you'll zoom in further, and show the details of the classes and their associations in a class diagram.

Behavioral view: the inner life of your structure

For each of these structural aspect, you can also show relevant behavioral aspects:

• for every classifier, you can document its lifecycle by explaining in a state diagram the different states that an object or a component could have, and how events are changing this state.
• with sequence diagram you can model how objects interact
• with activity diagrams you can model the overview of a complex flow of execution involving objects.

Physical view

All these components and artifacts were considered so far from the logical point of view (i.e. how the developper sees it). However, it is sometimes necessary to get an understanding of how these componennts will be deployed on the operational infrastructure, for example what happens on the server, and what happens on the client.

For this, you can use the deployment diagrams, that show how the components/artifacts are distributed between nodes (e.g. hardware, and within one device, different operating environments (OS, virtual servers, etc...).

Final note

The order above is purely illustrative. In general the elaboration of such a model is iterative. So you can also start with a class diagram, elaborate the interactions, fine-tune the classes, assemble them in composites, etc...

Answer 2

Consider Simon Brown's C4 model. In summary (from Wikipedia),

• Context diagrams (level 1): they show the system in scope and its relationship with users and other systems;
• Container diagrams (level 2): they decompose a system into interrelated containers. A container represents an application or a data store;
• Component diagrams (level 3): they decompose containers into interrelated components, and relate the components to other containers or other systems;
• Code diagrams (level 4): they provide additional details about the design of the architectural elements that can be mapped to code.

Some other highlights (from Simon's Youtube talk) that make me like the model:

• Extensibility. One can first start with this structural breakdown (C4 model), and then add other diagrams like behavioral diagrams for use cases. This seems like an intuitive way to sequence the order in which to make these architectural diagrams.
• Flexibility. There are not many rules to the C4 model, so not only can one throw out parts of the model that aren't useful to one's particular problem, but also one can modify the model to add more emphasis to some parts of the architecture via shapes and colors, as needed.

Answer 3

There are many approaches to developing software. Some don't use any diagrams at all. So there is no single "right" answer.

That being said, if you are looking for ideas for architecture diagrams, maybe consider the 4+1 architectural view approach, which could include:

• Component diagrams
• Package diagrams
• Class diagrams
• State diagrams
• Deployment diagrams
• Activity diagrams
• Sequence digrams
• Use case view

Answer 4

Short Answer - It depends.

Longer answer, it depends on the audience. Is the diagram aimed at the developers who will implement the software or the 'C' level executives that will agree the funding to implement the software? The same diagram doesn't satisfy both groups. As TOGAF puts it, it's all about the "viewpoint" and the same architecture can look very different to different stakeholder groups.

Work your way to lower level models of increasing detail, maybe the Solution Architects are better placed to create these. Build on what's there, create what isn't start high level and tactically add detail as areas are worked on. Don't waste time / money on exhaustively detailing a stable system that is not about to be worked on.

Use high level diagrams to show the main building blocks and what talks to what. Use colour to highlight similarities and differences, use colour to highlight areas of concern. Executives are pretty much hardwired to eliminate Red and Amber, use that psychology to your advantage.

At lower levels maybe a more formal notation is appropriate (e.g. UML) but only if the consumers of the model can understand the notation and get value from it otherwise you're wasting your time.

Architecture diagrams are primarily a communication tool so don't get too hung up on formality unless you are in a very formal environment.