Diagram Solution Architecture
We will follow the C4 approach to architecture diagramming. https://c4model.com/
- The creation of software diagrams has been scaled back as a result of the shift to agile methodologies. When diagrams are created, they are often confusing and unclear.
- The C4 model consists of a hierarchical set of software architecture diagrams for context, containers, components, and code.
- The hierarchy of the C4 diagrams provides different levels of abstraction, each of which is relevant to a different audience.
- Avoid ambiguity in your diagrams by including a sufficient amount of text as well as a key/legend for the notation you use.
Software architecture diagrams are a fantastic way to communicate how you are planning to build a software system (up-front design) or how an existing software system works (retrospective documentation, knowledge sharing, and learning).
However, it's very likely that the majority of the software architecture diagrams you've seen are a confused mess of boxes and lines. An unfortunate and unintended side effect of the Manifesto for Agile Software Development is that many teams have stopped or scaled back their diagramming and documentation efforts, including the use of UML.
These same teams now tend to rely on ad hoc diagrams that they draw on a whiteboard or put together using general-purpose diagramming tools such as Microsoft Visio.
Ambiguous software architecture diagrams lead to misunderstanding, which can slow a good team down. In the DMC, we really should be striving to create better software architecture diagrams to support knowledge transfer, support teams, learning, maintainability, etc.
To create these maps of your code, you first need a common set of abstractions to create a ubiquitous language to use to describe the static structure of your software system. The C4 model considers the static structures of a software system in terms of containers (applications, data stores, microservices, etc.), components, and code. It also considers the people who use the software systems that we build.
A System Context diagram is a good starting point for diagramming and documenting a software system, allowing you to step back and see the big picture. Draw a diagram showing your system as a box in the centre, surrounded by its users and the other systems that it interacts with. Detail isn't important here as this is your zoomed out view showing a big picture of the system landscape. The focus should be on people (actors, roles, personas, etc) and software systems rather thantechnologies, protocols and other low-level details.
Note: This is the same as the Solution Architecture Canvas.
- Scope: A single software system.
- Primary elements: The software system in scope.
- Supporting elements: People and software systems directly connected to the software system in scope.
- Intended audience: Everybody, both technical and non-technical people, inside and outside of the software development team. To be delivered as part of the initial project concept.
- Artifacts: DMC Solution Architecture Canvas, Github Repo Readme.md
The next step is to illustrate the high-level technology choices with a Container diagram. A "container" is something like a web application, mobile app, desktop application, database, file system, etc. Essentially, a container is a separately deployable unit that executes code or stores data. The Container diagram shows the high-level shape of the software architecture and how responsibilities are distributed across it. It also shows the major technology choices and how the containers communicate with one another.
- Scope: A single software system.
- **Primary elements: **Containers within the software system in scope.
- Supporting elements: People and software systems directly connected to the containers.
- Intended audience: Technical people inside and outside of the software development team; including software architects, developers and operations/support staff. To be created before software development starts.
- Artifacts: Visio or Powerpoint file, Github Repo Readme.md
- Notes: This diagram says nothing about deployment scenarios, clustering, replication, failover, etc.
Next you can zoom in to each container further to visualize the major structural building blocks and their interactions. The Component diagram shows how a container is made up of a number of components, what each of those components are, their responsibilities and the technology/implementation details. If your components don’t all fit on a single diagram, create multiple versions showing different portions of the container.
- Scope: A single container.
- Primary elements: Components within the container in scope.
- Supporting elements: Containers (within the software system in scope) plus people and software systems directly connected to the components.
- Intended audience: Software architects and developers. To be created before software development starts.
- Artifacts: Visio or Powerpoint file, Github Repo Readme.md
Finally, if you really want or need to, you can zoom into an individual component to show how that component is implemented. This is an optional level of detail and is often available on-demand from tooling such as IDEs. Ideally this diagram would be automatically generated using tooling (e.g. an IDE or UML modeling tool), and you should consider showing only those attributes and methods that allow you to tell the story that you want to tell. This level of detail is not recommended for anything but the most important or complex components.
- Scope: A single component.
- Primary elements: Code elements (e.g. classes, interfaces, objects, functions, database tables, etc) within the component in scope.
- Intended audience: Software architects and developers. To be created as part of the transition to support.
- Artifacts: Github Report Readme.md
A deployment diagram allows you to illustrate how containers in the static model are mapped to Dow’s infrastructure/cloud environments. This deployment diagram is based upon Dow’s standard cloud deployment diagram, although simplified slightly to show the mapping between containers and deployment nodes. A deployment node is something like physical infrastructure (e.g. a physical server or device), virtualized infrastructure (e.g. IaaS, PaaS, a virtual machine), containerized infrastructure (e.g. a Kubernetes container/cluster), an execution environment (e.g. a database server, Azure PaaS), etc.
.png)
- Scope: A single software system.
- Primary elements: Deployment nodes and containers within the software system in scope.
- Intended audience: Technical people inside and outside of the software development team; including software architects, developers and devops staff. To be created early on in the project to allow DevOps to provision cloud resources.
- Artifacts: Visio diagram, Github Report Readme.md
The C4 model doesn't prescribe any particular notation, and I would recommend that you stick with a simple notation that works well on whiteboards, paper, sticky notes, index cards, and a variety of diagramming tools. You can use UML as your notation, too, with the appropriate use of packages, components, and stereotypes. Regardless of the notation that you use, I would recommend that every element includes a name, the element type (i.e., "Person", "Software System", "Container", or "Component"), a technology choice (if appropriate), and some descriptive text. It might seem unusual to include so much text in a diagram, but this additional text removes much of ambiguity typically seen on software architecture diagrams.
Make sure that you have a key/legend to describe any notation that you're using, even if it's obvious to you. This should cover colours, shapes, acronyms, line styles, borders, sizing, etc. Your notation should ideally remain consistent across each level of detail. Here is the diagram key/legend for the container diagram shown previously.
And here are some recommendations related to notation.
Diagrams
- Every diagram should have a title describing the diagram type and scope (e.g. "System Context diagram for My Software System").
- Every diagram should have a key/legend explaining the notation being used (e.g. shapes, colours, border styles, line types, arrow heads, etc).
- Acronyms and abbreviations (business/domain or technology) should be understandable by all audiences, or explained in the diagram key/legend.
Elements
- The type of every element should be explicitly specified (e.g. Person, Software System, Container or Component).
- Every element should have a short description, to provide an "at a glance" view of key responsibilities.
- Every container and component should have a technology explicitly specified.
Relationships
- Every line should represent a unidirectional relationship.
- Every line should be labelled, the label being consistent with the direction and intent of the relationship (e.g. dependency or data flow).
- Relationships between containers (typically these represent inter-process communication) should have a technology/protocol explicitly labelled.
The C4 model is a simple way to communicate software architecture at different levels of abstraction so that you can tell different stories to different audiences. It's also a way to introduce (often, reintroduce) some rigor and lightweight modeling to software development teams.
This gives you enough information to start discussing with the business / non-tech people (Context), then move to the infrastructure / non-coding people (Container) and finally show to the technical / programming people the desired approach (Component) . For the most part, the first 3 Cs will be sufficient.
After this you can extend the diagrams to what fits the needs based of the project.
- Do you need to model an entity which constantly changes states and guides the flow on your application? If so, create a state machine diagram.
- Do you need to show the interaction between your newly created classes that nobody else knows? If so, Draw a sequence diagram.
- Do you want to show how you imagine the user view of the web application? Draw it in a napkin, whiteboard, paper (and then have the XD team create the appropriate wireframes).