Capturing the essence of your software with diagrams: Techniques for the engineer, designer and architect


Pictures are “worth a a thousand words” and in the software industry they can save time and help inspire the collective imagination

A good picture about a software system at right level can convey the right details. It is about what you leave out as much as what you put in and structure – there are therefore, different pictures describing varying perspectives In this article we will discuss the value and types of diagrams in software architecture and design

Layers, Perspectives and Needs

Good diagrams are self-explanatory and cover the precise point-of-view of the software system they describe. There are various types of software diagrams and maps covering details at different layers and from different perspectives of a software system

In-order for us to talk about different types of diagrams, it is key to orient ourselves around how software is viewed at various levels and ask “who cares? about what? and where?”

Funny story, I once managed to capture all the 400+ integrations between 20+ systems into a single, neat picture. While this was quite an achievement for me, the picture scared C-suite executives! Perspectives matter

Enterprise

Coming top-down we find the “Enterprise” layer up top with business, products, systems, security etc. as the perspectives. Diagrams at this level need to cover the breadth of the entire business portfolio and solutions it needs to be secure, functional, customer oriented and profitable

Product

The next layer is where the cross-functional teams live and deliver mission critical software. Diagrams at this level need to tell the stories of the tribes, their constrains and interactions as they build solutions. Often they need more than a diagram here, perhaps a map with layers and spatial orientation

The product layer is where project streams are funded to deliver software changes of value. The diagrams thus need to cater for changing contexts, solutions, technology etc over time to help show the evolution of software over time

Platform

Platform is where the technology supporting the solutions lives. Like the enterprise team they may cover the entire width of the enterprise or just parts of it using a variety of technology and tools

Diagrams here need to show the the underlying technology and its attributes (security, scalability etc) especially as they evolve over time

Operations

Operations teams keep the software running smoothly and manage its lifecyle after it is delivered. In some organisations the Ops teams make the changes themselves until the very end of the utility value of these systems

The diagrams for operational layer require an “alarm” to “impact” view as the mission critical systems may need observing and tuning under stresses of real life use

My favourite top 10 Diagrams

Now that we know all the contexts for software diagrams, below are my top favourite diagrams with details around which layer and perspective they describe and how you can learn more about them

Wardley Maps

Wardley maps from Simon Wardley show the value chain and maturity on map of systems with a left to right flow. This view is useful for a birds-eye view of an enterprise landscape and helps top-level stakeholders identify areas of their services to customise vs standardise

Wardley Map: Sample from a Miro template

Learn more: I follow Simon Wardley on Twitter to learn more (ref: https://twitter.com/swardley)

Domain Context Maps

These come from business-domain oriented view vs a typical EA enterprise architecture map of systems. I love it because they show a birds-eye view of the bounded-contexts, domain models, interactions between contexts and team topology. These come from domain driven design (DDD)

DDD Context Maps with Context Boundaries, Teams, Models, Relationships

Learn more:

Activity flow diagrams

Process modeling techniques show end-to-end processes and a version uses the left-to-right time flow with swim lanes for users and systems. I love showing integration interfaces in this view as it helps the integration engineers, system testers and others in a cross-functional team view the end-to-end process. This is my hack over an existing technique

Activity flow diagram for an end-to-end process with swim-lanes for systems, lines representing integration interfaces

Learn more: About process modeling techniques online and checkout this UML lesson on activity flows https://www.uml-diagrams.org/document-management-uml-activity-diagram-example.html

C4 Diagrams

Great for show 4 layers of a solution context, containers, components and code. Love it as it keeps the users in stark focus and key to Product teams

Source: https://c4model.com/

Learn More: See the documentation here https://c4model.com/

Component and Sequence diagrams

Great for engineering teams building and maintaining a product as well as operations. These use standard notations like UML and depict interactions between modules and components of a software system as well as the code components (container and class)

Source: https://www.uml-diagrams.org/component-diagrams.html
Source: https://www.uml-diagrams.org/sequence-diagrams.html

Learn More: See https://www.uml-diagrams.org/component-diagrams.html and https://www.uml-diagrams.org/sequence-diagrams.html

Infrastructure & Network Diagrams

These describe how the underlying platform is connected, secured and hosted so that teams extending or operating can easily enhance and scale

Sample cloud network and infrastructure diagram
An on-premise network and infrastructure diagram

Logical Architecture Diagrams

Show an abstract view of things, for example services and layers

Logical services architecture diagram showing current state and target state

Domain story Diagrams

These contain stories of a specific user and their interactions (queries, commands) with systems to achieve a business outcome. These diagrams can be analysed into DDD models, commands and queries for APIs & Events etc.

Domain story diagram with contexts, commands and queries

Event Storming Views

These are not diagrams, rather the output of a group of people in a workshop contributing to an end-to-end business oriented view of the software with the goal of relating Domain Events to Commands, Queries, Policies etc. These views provide a birds-eye view of a product area and help discover bounded contexts with the help of this workshop

Domain Aggregate Maps, Data Models, Entity Relationship diagrams

These diagrams show how the information model is represented in the software. Domain aggregate map is not the same as a database entity-relationship model. Aggregates are coarse and over a business domain or an interaction context, what is persisted may be parts of an aggregate in different tables. It often helps to show these aggregates in a spider-diagram with value objects and also systems – showing the master systems and copies in other systems

Recap

A Visual representation of our software and its relationship to business is key to consensus as we fund, discover, design, build, QA, release, maintain and support them

Good diagrams address the key stakeholder within the layer they live and address the perspective of the viewer. Good diagrams reduce the cognitive load and convey information with clarity – they remove everything until nothing else can be taken away

Conclusion

It is therefore important to recognise there are layers like enterprise, product, platform, operations within an organisation and their interests in the software the build and manage is vastly different. Good diagrams tell the story about as-is and show how the software has evolved over time as well

If software is eating the world then software diagrams show how it is happening and its efficacy

Talk Back!

I am keen to hear from you in the comment about your favourite diagrams, mapping technqiues and stories. Tell me what do you describe, how and techniques you use regularly

Leave a Comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s