Visualizing Your (Real) Architecture

Editorial note: I originally wrote this post for the NDepend blog. Go check out the original at the NDepend site. Take a look around at the other posts while you’re there as well — there’s a lot of good stuff to be had.

Diagrams of software architecture have a certain aesthetic appeal to them. They usually consist of grayscale or muted pastel colors and nice, soft shapes with rounded edges. The architects that make them assemble them into pleasing patterns and flowing structures such that they often resemble 7-layer cakes, pinwheels, or slalom courses. With circles and ovals arranged neatly inside of rectangles connected by arrows, there is a certain, orderly beauty. If you’re lucky, there will even be some fluffy clouds.

If you want to see an example, here’s one that has it all. It’s even got a service bus. Clearly, the battle for quality was over long before the first shots were ever fired. After the initial conception of this thing, the mundane details of bringing the architecture to life would likely have been a simple matter of digital paint by numbers. Implement an interface here, inherit from a framework class there, and Presto! Instant operational beauty that functions as smoothly on servers as it does in the executive readout power point.

At least, that’s the plan.

Architectural Vision

In terms of visualization, it’s frequently the case that all we ever get is the plan. Ideas for organization of the software’s architecture start in conversations, migrate to the whiteboard, and eventually end up in Visio and published to Power Point, but that’s all the further they go. They are, at this point, frozen in time, looking like this.

The project then starts, and programers begin to implement the green and blue rectangles and the arrows. Eventually, they get to the larger rectangles and larger arrows. All of this takes months or years, and the architectural diagram remains tacked up to some wall somewhere, offering mute guidance. Perhaps the occasional rectangle or oval is added, or perhaps even a 3-D cylinder representing a database. Maybe, a cloud even makes its way in. But, by and large, the architectural vision remains static.

As the project goes along, if you ask the folks working on it for a visual of the architecture, they will dutifully point to the original up on the wall. Regardless of what happens during implementation, this is the picture that managers and executives will retain when they picture the system. The architects may retain this picture as well, while the developers… they might not be quite so sure.

For the developers, each hack they add, each workaround that they implement to get a feature finished, and each design concession they make all contribute to a blurring of the image. Most likely, their image of the original architecture with some shapes scratched out, a bunch of new lines added, and some bits of miscellaneous dirt and cruft here and there. Perhaps they think the images corners should be crinkled and dog-eared or that the whole thing should take on a yellowed-with-age pallor.

Architectural Reality

Reality is often much harsher. A lot of people don’t realize it, but there are tools that will generate actual diagrams of your architecture based on your source code and project(s) structure. Still more realize they exist, but don’t actually use them. And if someone like, oh, say a consultant doing a code assessment, were to come along and generate a visualization of the architecture, they would almost invariably be shocked and embarrassed to see that, in reality, it looks like this.

For many, many organizations, there’s a huge blind spot when it comes to actually visualizing software composition. As the project wears on, all parties may talk about ideas like technical debt, needed rework, “bad spots,” global variables, and other such things. But these often do not translate into alterations of the actual, visual model.

If one were to draw parallels to the building metaphor so often used for software, this would be akin to drawing a blueprint and building a model to show off, but never altering course from there. As construction proceeded and stakeholders asked what the building looked like, you’d continue to show them pictures of the model… even after completion.

Reconciling the Two

At its core, software architecture is about dependency management. As I’ve talked about in the past, companies form hierarchies to address problematic complexity overhead. Departments and teams exist to cut down on communication channels with structure, thus isolating different concerns within the company. The same is true of software structure (i.e. architecture). Architecture exists to define dependency flow and to create strategic pockets of isolation, both to minimize the impact of necessary changes and to help with organization and division of labor.

As soon as you start to lay finger to keyboard with implementation of a software project, dependencies start to emerge and take shape. And there is absolutely nothing to guarantee that the dependencies emerging are those called out in a pretty architectural diagram. To keep things under control and to keep reality in sync with the vision, it absolutely critical to start capturing a diagram of reality from the get-go.

Many teams have what’s known as a build radiator (or, more generally, information radiator). The idea is to make something like build quality visible to all at all times. As the pithy saying goes, “sunlight is the best antiseptic.” If everyone can see a broken build, a team tends to keep the build non-broken.

Apply this to the team’s architecture. Incorporate a view of the reality of architecture (dependency graph) into your team’s radiator. If you apply this strategy, you won’t later by mystified by why changes are so difficult and time consuming when the architecture diagram suggest that they should be straightforward. You won’t have that reality deficit. So make sure you take steps to ensure that everyone can always see what the architecture really looks like.