Documenting software architecture is not about choosing a notation or filling a template. It is about communicating the right structure to the right audience at the right level of abstraction.
We do not mandate symbology {: note}
Every diagram can indeed use only boxes and arrows. That is not the point. Neither is a symbology what we mandate. The point is that each diagram represents one level of abstraction — and that level defines what a box means. The same box symbol means a System at the Conceptual level, a Product at the Logical level, a Module at the Physical level, and a Deployment Unit at the Implementation level. Although it is not “forbiden”, mixing levels on one diagram can destroy the meaning of it.
Existing industry visualisation frameworks — C4, arc42 — do not follow these principles consistently. They are reviewed in Legacy Ways of Software Documenting.
We favour visualisation that follows partioning logic. Which is based on DBJ Taxonomy.
Logical and physical partitioning
| Abstraction Level | Digrams Shows | As Made of | Comment |
|---|---|---|---|
| Conceptual | Business Landscape | Systems | Non-functional view. In the wider environment of the commercial enterprise |
| Logical | Systems Landscape | Components | Usualy systems are made of products and other components. They exist as a re-action to business requirements |
| Physical | Components Landscape | Modules | Fuctional view. Modules exhibit functional end points |
| Implementation | Modules Landscape | End Points | Functional End Points are implemented as APIs. Code is behind API’s |