Lightweight Architecture Process for the Heavyweight World

I feel that architecture and design are an important part of the software development. Nowadays it’s not getting the attention it needs. At the same time, I think that the old books and papers on software architecture have little to give us. Imposing such frameworks to an agile project should rather be considered harmful. Still, this is what we teach to kids at schools. These are the books that developers read when they dream of becoming awesome architects.

I’ve been feeling this way for a long time. What caused me to write about it now was my visit to QCon London. Second day of QCon London 2016 started with Linda Northrop’s keynote. She works at Software Engineering Institute (SEI). Her keynote was about software architectures. Most of the presentation she spent on the history of software architecture. She described the important books and papers that led to the creation of software architecture as we know it. Little of the presentation talked about what architecture is and should be now and in the future. From someone who has researched this for decades, this was a little disappointing.

I fumed about the situation to a colleague of mine. He then asked me to describe what modern software architecture process should focus on. I gave him an outline in three points which I will elaborate on in the following paragraphs:

  • Understanding and modeling your domain
  • Focusing on allowing growth
  • Automated and lightweight documentation

But let’s start with what’s wrong with the traditional architecture frameworks.

If you have managed to avoid frameworks like Rational Unified Process 4+1 Views, take a look at nice short paper, “A general model of software architecture design derived from five industrial approaches” by Hofmeister et al. It gives you quick overview of bunch of different architecture frameworks and processes.

Same paper’s descriptions reveal the problems most of these frameworks have. Usually they describe a method of transforming well-defined requirements into an architectural specification. But as we know, most requirements are emergent. Customer doesn’t know what exactly he wants and even when he does, he’s usually wrong. And then he ends up changing his mind several times. This means much of the documentation we create upfront is over-specified, useless. It only serves in giving us a false sense of knowing.

Understanding and modeling your domain

I’ve seen several projects where agile is driven to it’s extreme: being purely reactive. It is tempting to think that when new requirements emerge, we will just react and refactor our system to adapt to it. But if you have, in your haste to get to coding, misunderstood one or more of the core domain concepts or their relations, the refactoring to change that is usually painful, risky and time consuming. You could have often avoid this with a little more design and modelling up front.

Now everything, including your neighbour and his cat, is moving to microservices. The importance of focusing on well defined domains, concepts and bounded contexts becomes, even more important. Domain Driven Design seems to be having a new renaissance and I feel it’s well deserved. Eric Evans gave an excellent talk on this topic on the final day of this years QCon London. It’s well worth the watch when it comes online to InfoQ.

Before you open your IDE and create that Customer class, make sure that the concept of a customer is well defined. You should know the context this definition applies to. Your team and stakeholders should understand and use the term the same way. This is of course just the first step, but an important one. From there you go down the rabbit hole and in to the world of better separated concerns, clearer formats for communication and less big balls of mud.

Focus on Allowing Growth

I love Jim Coplien’s definition of what it means to test an architecture: You take your idea of an architecture, you sit down with your stakeholders and ask them: “what do you see this system doing for you, in a perfect world and long in the future?”. If most of the ideas they throw at you make you cringe like “uh, that will be painful to add to this architecture”, maybe right now is the correct time to adjust your architecture. Don’t mistake this with future proofing with unnecessary implementations that won’t be needed. It’s not that. This is where you admit that most requirements are currently unknown and our focus should be on an architecture that will allow these features to emerge and grow without making a mess.

Automated and Lightweight Documentation

In the past, our idea on what architecture documentation should be has been way of the mark. We did not tailor it for the reader. It was not useful and it’s been a nightmare to keep up-to-date.

I can’t tell you what documentation your project needs but you can. You should avoid ready document templates like a plague. Consider who needs the specific document before you start writing it. If you don’t know, don’t write it. When you know, write it so that it’s of maximal use for just that audience.

Recently I have helped several multi-team projects to get their act together on this topic. I usually create what I call an umbrella document. It is a GitHub repository which has either all the relevant documentation or links to all the relevant documentation in one centralised place.

The documentation is in two formats: UML diagrams and markdown. Both are text files in the git repository. UML diagrams are using PlantUML. We write them in a simple text format. Our build server takes this text and runs it through PlantUML to generate images. The images it then uploads to Amazon S3 bucket. We then link those diagram images to the markdown documents. Besides that, we can often generate documentation from code.

With this setup, everyone knows where to start when they need documentation. With no software needed for the editing it’s easy to encourage all team members to get involved in keeping the documentation up-to-date.

Continuous Effort

What’s important to note of course is that all the above is a continuous effort. So although there’s an emphasis on designing more up front, it’s more up front for each iteration, each feature, each story.


To sum up,

  • Putting effort in your architecture and design is imperative, BUT
  • Traditional architecture frameworks are useless and often harmful with modern agile

I hope that more research and practical methods are developed around pragmatic architecture when running agile software projects. I hope we stop teaching kids the old processes. I hope teams take a little step back from purely reactive agile. I hope more teams really get to know the domain they work in, the people they try to help with their software and aim for vocabularies and models which they can all agree on.