Software Architecture Diagrams Should Be Maps of Your Source Code

if you've ever worked on a codebase that's more than just a sample application, you'll know that understanding and navigating the code can be tricky, certainly until you familiarize yourself with the key structures within it. once you have a shared vocabulary that you can use to describe those key structures , creating some diagrams to describe them is easy. and if those structures are hierarchical, your diagrams become maps that you can use to navigate the codebase.

if you open up something like google maps on your smartphone and do a search for jersey , it will zoom into jersey. this is great if you want to know what's inside jersey and what the various place names are, but if you've never heard of jersey it's completely useless. what you then need to do is pinch-to-zoom-out to get back to the map of europe, which puts jersey in context. diagrams of our software should be the same. sometimes, as developers, we want the zoomed-in view of the code and at other times, depending on who we are talking to for example, we need a zoomed-out view.

a feature that has been built into structurizr is that you can link components on a component diagram to code-level elements, which provides that final level of navigation from diagrams to code. you can try this yourself on the software architecture diagrams for the spring petclinic application .

whatever tooling you use to create software architecture diagrams though, make sure that your diagrams reflect real structures in the code and that the mapping between diagrams and code is simple. my free the art of visualising software architecture ebook has more information on this topic.