Top 5 diagrams for documenting software architecture
A revamp of an old article on the most useful diagrams to document software architecture and tools to create them.
The most difficult aspect of running engineering teams is aligning how we do things. Documenting Software Architecture facilitates the conversations on the approaches, tools and principles we apply to our product. In this article I share the top 5 diagrams I use almost every day: C4 Context and Container diagrams, Deployment Diagram, Sequence diagram and Use Case diagram. Let's go through them.
Context
The c4 website does a pretty good job explaining their diagrams, but I still would like to provide my own understanding.
Your system operates in some context. Primarily, it's their users and other software systems. Users may have different roles like content creator, reader, administrator. Also they can be internal or external. Other software systems may be source of data for your system, or get the information from it. It is important to understand this context to properly design the system and remind yourself to integrate with external systems.
How to draw
Identify the persons who will use your system
Identify the external systems
Create a single rectangle depicting your system
Add connections between the system, users and external systems
Provide meaningful comments on every component
Tools
There are different tools you can use to create the context diagram. There are C4 stencils for OmniGraffle, C4 examples for LucidChart, draw.io has the stencils as well. You can also use PlantUML to leverage diagrams as code. Let's say we want to draw the aforementioned diagram for a neo-banking digital platform with uml:
@startuml
!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Context.puml
' uncomment the following line and comment the first to use locally
' !include C4_Context.puml
Person(customer, "Customer", "A bank client")
System(abc_system, "Digital Platform", "Allows freelancers and business owners see their transactions.")
System_Ext(idnow, "IDNow", "System for KYC and Qualified Eletronic Signatures")
System_Ext(pay, "Google Pay/Apple Pay", "Google Pay and Apple Pay systems")
System_Ext(dms, "DMS", "Document Management System")
System_Ext(crm, "CRM", "CRM")
System_Ext(current, "Existing Banking System", "Banking Backoffice")
Rel(abc_system, pay, "uses")
Rel(customer, abc_system, "Uses")
Rel_L(abc_system, idnow, "integrates")
Rel_Neighbor(abc_system, dms, "uploads files")
Rel_D(abc_system, crm, "integrates")
Rel_U(abc_system, current, "uses")
@endumlWe define a person, a system, external systems and the relations between them. Person, System and System_ext predicates have 3 parameters: a key, a title and a description. Rel predicate has 3 parameters as well, but they are different: a key of one entity, a key of another and a name of the relation.
Basically you can draw a context diagram in any drawing tool you'd like. Several great examples can be found here.
Important highlights
Context diagram is the first thing you create when working on a system. Failing to do so may cost you missed integrations and mistakes during system design.
Context may actually include some lower level details, this is perfectly fine.
I was struggling with a context diagram for one banking system. It would include only a newly created system and a single customer, which didn't bring any value. After the reconcideration I added an API Gateway and an existing Auth Provider we were going to use. That way the context diagram started to make sense and allowed to omit those elements from the lower level diagrams.
- Aleksey, Solution Architect.
We had a learning system in development. At the time of Alpha release we understood, that analytical system is not receiving the data from the client facing app. Should we have a context diagram in place, we won't make that mistake. Luckily, it was easy to fix.
- John, Solution Architect.
Summary.
Context diagram is a crucial view which provides the highest level understanding on the people and systems your future system will interact with.
Containers
Containers don't mean docker containers here. Container is an any deployable entity or data storage from the C4 perspective. It can be a mobile application, a website, a VM, a docker container, a database or an object storage; whatever you can deploy. In my experience this diagram is the most complex and it gains the most attention in the same time. That mean it is almost the main diagram you have to work on!
The trick here is you are zooming in into your system. What was a single rectangle, now consists of some rectangles and arrows. Those rectangles are containers now.
Identify the list of entities: microservices, storages, external services
Place them on the diagram
Add comments on the purpose of each component and the technology it is implemented with
Add connections with arrows
Add meaningful labels to each arrow
Pick up a color scheme and apply it
Create a legend.
Tools
Same as for the context diagram: Draw.io, OmniGraffle, LucidChart and others.
Important highlights
Pay attention that the elements are placed in columns. First column is just an API Gateway, the second - the first group of services, then a second group of services, then some storages. This way you demonstrate the layered architecture, which helps to understand the boundaries and responsibilities.
When microservices count grows beyong a single digit, your connection lines will start to intercept. The academical books say you have to avoid the interceptions for readability. Unfortunately, this is not always possible. Do not get upset: focus on making the diagram readable. You can use different colors or line widths, or different line styles(dotted, solid, etc.)
If you use a custom tool(like I am) you need to include a Legend block. It's not obvious what the arrows mean, and what is the color's meaning. Legend explains it.
The common question when using cloud is: do you include the managed services, like queues and messaging solutions? I tend to answer no. This complicates the diagram instead of making it easier to read. If some services are communicating through a message queue, display it via separate type of arrow.
I teach my fellow architects to follow the layered approach when they create container or components-and-connections diagrams. Those diagrams tend to include many entities and structuring them with layers increases readability.
- Ilya, Enterprise Architect.
Summary
Container diagram provides insight into which deployable items your backend consist of and how those components talk to each other.
Sequence Diagram
The first two diagrams show how the elements of the system relate to each other. However, they can not demonstrate what happens in your system. For example, a user sign ups for your system. Which components are involved? What actions are triggered? How the components interact with each other? Sequence diagram can answer these questions.
How to draw
Choose a business case(a user sign-in, a purchase, etc.)
Identify the entities involved in the use case
Put them on the diagram
Add interactions(arrows)
Provide valuable comments to each arrow
Tools
Unfortunately, OmniGraffle is not suitable for sequence diagrams. Therefore I use draw.io and LucidChart for drawing them. The latter is a good choice because you can choose either to draw the diagram manually or use the UML Sequence diagramming. This is possible as Sequence Diagram is a structured one.
Important highlights
Sequence diagram is an absolute must when designing a new feature you add to the system. It shows the affected parts of the system, points of integrations with external software and contracts which the team will have to create or update.
Sequence diagram is valuable for QA engineers as well. It provides the insights where the potential issues can be located and serve as a source of truth for Test Cases.
Few months in a project, and we still faced the issues when the parts of the system were not ready for a long awaited feature. Stakeholders were not happy at all, and there was a traction between different teams. We discussed the issue and agreed to make architecture design before the imlementation. Sequence diagrams were a great help: now we know the full picture before writing the code, not after.
Vladimir, Solution Architect
Summary
Sequence diagrams allow to document the behavior of the system in different business cases.
Deployment Diagram
Using context, containers and sequence diagrams you can answer what parts of the system consist of and how they relate and interact with each others. But they hardly can answer the questions of availability, scalability and security. Deployment diagram helps with that.
There are several different things you want to display.
Compute resources. This can include virtual machines, docker containers, kubernetes clusters and cloud functions. You can also think of mobile devices and desktop computers as compute resources as well.
Storages. Persistent storages for your data like relational and nosql databases, binary file storages like images, music and video, bigdata storages with parket files and so on.
Messaging resources. Kafka/RabbitMQ installations, Google Cloud pub/sub, AWS SQS and others.
Networks. Your computers use networks to communicate with each others. Both physical and virtual networks should be displayed.
Availability Zones. You can think of them as data centers.
Infrastructure Nodes. DNS servers, Load Balancers, Firewalls, CDNs
The diagram shows the compute, storage and messaging resources alongside with networks and availability zones. It also includes the instrastructure nodes which are not fulfilling any functional requirements, but addressing non-functional instead.
How to draw
Place the major building blocks: browsers, mobile devices, public cloud, data centers
Place the computing and storage resources
Add infrastructure nodes
Add networks
Add the network calls between nodes
Add the monitoring resources
Add scalability comments if required
Another example for AWS cloud:
Deployment diagram complements the understanding of the system from the physical appearence perspective.
Use Case Diagram
The most of previous diagrams were very technical ones. Use Case diagram is more business oriented. It depicts how the persons are interacting with your system in a very high level way. Use cases themselves can be treated as business capabilities, which I were describing in this article.
How to draw
Draw a rectange. This will be our System boundary
Define which persons your system is dealing with
Add use cases inside the system using ovals
Add connections between the actors and use cases
Example
Tools
The architect can draw a diagram with any graphical editor and with the same toolset used for other diagrams. Omnigraffle, LucidChart, Draw.io are working well. Remember, that Use Case Diagram is a structured once so you can use UML for creating it. PlantUml or LucidChart helps with that.
Summary
Use context diagram to show the highest level view on the system
Document the use cases with the corresponding diagram
Zoom on the system internals with containers and deployment diagrams
Document particular business cases with sequence diagrams
Discuss this article on twitter.