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

<div class="cs-rating pd-rating" id="pd_rating_holder_1819065_post_1725"></div> <p class="wp-block-paragraph">Pictures<em> are “worth a a thousand words”</em> and in the software industry they can save time and help inspire the <strong>collective</strong> imagination</p> <p class="wp-block-paragraph">A good picture about a software system at right level can convey the right details. It is about what you <strong>leave out </strong>as much as what you put in and <strong>structure</strong> – there are therefore, <em>different pictures describing varying perspectives </em>In this article we will discuss the <strong>value and types</strong> of <strong>diagrams</strong> in <strong>software architecture and design</strong></p> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-8.44.17-am-1.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-8.44.17-am-1.png?w=914&quot; alt="" class="wp-image-1736" /></a></figure> <h3 class="wp-block-heading">Layers, Perspectives and Needs</h3> <p class="wp-block-paragraph">Good diagrams are <em>self-explanatory</em> 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</p> <p class="wp-block-paragraph">In-order for us to talk about different types of diagrams, it is key to <em>orient</em> ourselves around how software is viewed at various levels and ask “<strong>who</strong> cares? about <strong>what</strong>? and <strong>where</strong>?”</p> <p class="wp-block-paragraph">Funny story,<em> 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</em>! <strong> Perspectives matter</strong></p> <h5 class="wp-block-heading">Enterprise </h5> <p class="wp-block-paragraph">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 </p> <h5 class="wp-block-heading">Product</h5> <p class="wp-block-paragraph">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</p> <p class="wp-block-paragraph">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</p> <h4 class="wp-block-heading">Platform</h4> <p class="wp-block-paragraph">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</p> <p class="wp-block-paragraph">Diagrams here need to show the the underlying technology and its attributes (security, scalability etc) especially as they evolve over time</p> <h4 class="wp-block-heading">Operations</h4> <p class="wp-block-paragraph">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</p> <p class="wp-block-paragraph">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</p> <h2 class="wp-block-heading">My favourite top 10 Diagrams </h2> <p class="wp-block-paragraph">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 </p> <h3 class="wp-block-heading">Wardley Maps</h3> <p class="wp-block-paragraph">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</p> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/sample-maps.jpg"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/sample-maps.jpg?w=1024&quot; alt="" class="wp-image-1739" /></a><figcaption>Wardley Map: Sample from a Miro template</figcaption></figure> <p class="wp-block-paragraph"><strong>Learn more: </strong>I follow Simon Wardley on Twitter to learn more (ref: <a href="https://twitter.com/swardle">https://twitter.com/swardle</a>y) </p> <h3 class="wp-block-heading">Domain Context Maps</h3> <p class="wp-block-paragraph">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)</p> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/picture-1.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/picture-1.png?w=777&quot; alt="" class="wp-image-1742" /></a><figcaption>DDD Context Maps with Context Boundaries, Teams, Models, Relationships</figcaption></figure> <p class="wp-block-paragraph"><strong>Learn more: </strong> </p> <ul class="wp-block-list"><li>This free resource from Orielly publishing is great <a href="https://www.oreilly.com/library/view/what-is-domain-driven/9781492057802/ch04.html">https://www.oreilly.com/library/view/what-is-domain-driven/9781492057802/ch04.html</a></li><li>Explore resources from Michael Plöd <a href="https://www.youtube.com/watch?v=VjtMt689ql8">here</a&gt; and read his book <a href="https://leanpub.com/ddd-by-example">here</a&gt; </li></ul> <h3 class="wp-block-heading">Activity flow diagrams</h3> <p class="wp-block-paragraph">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</p> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-9.13.41-am.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-9.13.41-am.png?w=1024&quot; alt="" class="wp-image-1744" /></a><figcaption>Activity flow diagram for an end-to-end process with swim-lanes for systems, lines representing integration interfaces</figcaption></figure> <p class="wp-block-paragraph"><strong>Learn more: </strong> About process modeling techniques online and checkout this UML lesson on activity flows <a href="https://www.uml-diagrams.org/document-management-uml-activity-diagram-example.html">https://www.uml-diagrams.org/document-management-uml-activity-diagram-example.html</a></p&gt; <h3 class="wp-block-heading">C4 Diagrams</h3> <p class="wp-block-paragraph">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</p> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-9.21.28-am.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-9.21.28-am.png?w=1024&quot; alt="" class="wp-image-1747" /></a><figcaption>Source: https://c4model.com/ </figcaption></figure> <p class="wp-block-paragraph"><strong>Learn More:</strong> See the documentation here <a href="https://c4model.com/">https://c4model.com/</a></p&gt; <h3 class="wp-block-heading">Component and Sequence diagrams</h3> <p class="wp-block-paragraph">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)</p> <figure class="wp-block-image size-large is-resized"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-9.22.47-am.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-9.22.47-am.png?w=1024&quot; alt="" class="wp-image-1749" width="778" height="445" /></a><figcaption>Source: https://www.uml-diagrams.org/component-diagrams.html</figcaption></figure&gt; <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-9.24.43-am.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-9.24.43-am.png?w=1024&quot; alt="" class="wp-image-1751" /></a><figcaption>Source: https://www.uml-diagrams.org/sequence-diagrams.html</figcaption></figure&gt; <p class="wp-block-paragraph"><strong>Learn More</strong>: See<a href="https://www.uml-diagrams.org/component-diagrams.html"&gt; https://www.uml-diagrams.org/component-diagrams.html </a>and <a href="https://www.uml-diagrams.org/sequence-diagrams.html">https://www.uml-diagrams.org/sequence-diagrams.html</a></p&gt; <h3 class="wp-block-heading"><strong>Infrastructure & Network Diagrams</strong></h3> <p class="wp-block-paragraph">These describe how the underlying platform is connected, secured and hosted so that teams extending or operating can easily enhance and scale</p> <figure class="wp-block-image size-large is-resized"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.29.17-am.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.29.17-am.png?w=848&quot; alt="" class="wp-image-1767" width="765" height="561" /></a><figcaption>Sample cloud network and infrastructure diagram </figcaption></figure> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.31.15-am.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.31.15-am.png?w=1024&quot; alt="" class="wp-image-1769" /></a><figcaption>An on-premise network and infrastructure diagram</figcaption></figure> <p class="wp-block-paragraph"><strong>Logical Architecture Diagrams</strong></p> <p class="wp-block-paragraph">Show an abstract view of things, for example services and layers </p> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.18.24-am.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.18.24-am.png?w=1024&quot; alt="" class="wp-image-1755" /></a><figcaption>Logical services architecture diagram showing current state and target state</figcaption></figure> <p class="wp-block-paragraph"><strong>Domain story Diagrams</strong></p> <p class="wp-block-paragraph">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.</p> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-03-23-at-6.31.16-pm.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-03-23-at-6.31.16-pm.png?w=1024&quot; alt="" class="wp-image-1760" /></a><figcaption>Domain story diagram with contexts, commands and queries</figcaption></figure> <p class="wp-block-paragraph"><strong>Event Storming Views</strong></p> <p class="wp-block-paragraph">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</p> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.25.18-am.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.25.18-am.png?w=1024&quot; alt="" class="wp-image-1763" /></a></figure> <h3 class="wp-block-heading"><strong>Domain Aggregate Maps, Data Models, Entity Relationship diagrams</strong></h3> <p class="wp-block-paragraph">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</p> <figure class="wp-block-image size-large"><a href="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.27.25-am.png"><img src="https://alok-mishra.com/wp-content/uploads/2021/04/screen-shot-2021-04-11-at-10.27.25-am.png?w=1024&quot; alt="" class="wp-image-1765" /></a></figure> <h2 class="wp-block-heading">Recap</h2> <p class="wp-block-paragraph">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</p> <p class="wp-block-paragraph">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</p> <h2 class="wp-block-heading">Conclusion</h2> <p class="wp-block-paragraph">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</p> <p class="wp-block-paragraph">If software is eating the world then software diagrams show how it is happening and its efficacy</p> <h2 class="wp-block-heading">Talk Back!</h2> <p class="wp-block-paragraph">I am keen to hear from you in the comment about your favourite diagrams, mapping technqiues and stories. Tell me what do <strong>you</strong> describe, how and techniques you use regularly</p> <p class="wp-block-paragraph"></p>