Even when working for an agile software development company you may be required to write an architecture spec. It may be a client requirement or may be something required in an RFP; once in a while you have to write something like this.

The first thought of someone in this situation is that she needs to create a very detailed spec and the agility in this project is already dead under heaps of BDUF. That’s not necessarily the case, you can try to create a spec that not only won’t fall in BDUF and may even –believe it or not!– be useful as a starting point.

In my first days as a consultant/team lead/architect/you-name-it, some years ago, I found it very hard to create these specs. I looked in my company’s bloated and useless document management system for examples, but everything I found smelled like BDUF. I wasn’t working in an agile project or even an agile company but already knew that detailed specifications tend to be obsolete in the first 30 minutes of a project.

So I searched publications from academia and industry for some inspiration. After reading dozens of pages -on everything from UML profiles to formal methods verification of architectures- I decided that the good old 4+1 Model developed by Philippe Krutchen was the way to go. Most implementations of this technique end up being bureaucratic and worthless but the model itself is not that bad, at least in its core.

At first I was strictly following the 4+1 Model but after some time my specs changed into something a bit different. I’ll try and describe what I do, hopefully it can help other people stay away from bloated and useless specs.

Purpose

If you are trying to document an existing architecture or write the specification that will be followed by your code monkeys there’s not much in this text for you. The kind of architecture spec I’m talking about here is one someone is actually required to write. If you are writing an architecture spec because you feel like it is the best way to document your software or to specify the work programmers will perform I have to tell you that you may be missing several decades of evolution in technology and processes.

When I’m required to write an architecture spec I keep in mind that the only goal for it is to communicate ideas. You may be either telling your colleagues about how you think the system should look like or telling your clients how your company wants to develop their system.

Similar to a user story, the architecture spec I describe here is nothing but a starting point for a conversation between stakeholders. So you do not have to supply all details in it, just enough to get the big picture, check if it makes sense and keep talking.

Views

Krutchen says that views are “described by a blueprint using its own particular notation”. His work has evolved into IEEE Standard 1471. This standard defines a very structured and formal set of concepts that should be used when describing architectures. Nevertheless I think we can summarise its concept of view into this simple sentence:

A view is a representation of a whole system from the perspective of a set of concerns

That definition is probably enough for us, I’d just drop some words from it. For me a view is a representation of a system or part of it from a given perspective.

As our purpose is communication -not specification or documentation- I don’t think that the views proposed by Krutchen in the 4+1 model are applicable. Our views must be way simpler.

So what would those be? It all depends on the level of formality and BDUF required by the audience. My specs often have these two:

• Logical Components: Describes the subsystems and the Bounded Contexts
• Physical Components: Maps the logical components with deployment units such as web applications, desktop applications, web services, servers, etc.

As they are important aspects of all systems I’ve took part in development. Some other views I’ve found useful in the past are:

• Deployment: Where components are installed, how the machines communicate, minimum specs for servers, etc..
• Component Implementation: Described the technology stack, frameworks, libraries and all that jazz. Usually required for RFPs but not that often when you’re just proposing an initial design.
• Scalability: Describes how components of the system are meant to scale. Flags bottlenecks and propose strategies.

I use these last views only when required, usually to address an explicit enquiry made by stakeholders -and remember that developers are stakeholders too!

Logical Components

The Logical Components view is probably the most important part of the spec. Martin Fowler says that architecture “includes how the system is divided into components and how the components interact through interfaces” and this view is exactly about the components and how they interact.

The Diagram
Usually you are going to present a diagram of how those components are logically placed. I believe that if you think that you need more than one simple diagram in this view it may be the case that you are actually dealing with more than one system and trying to represent it as one single thing. It is probably good to revisit your understanding of the solution.

And how does this diagram look like? Well, once more it all depends. I used to only draw those diagrams using UML, not the full 738-pages gorilla but just the basic syntax. Nowadays I tend to use simple block diagrams.

UML has semantic constructs that sound really interesting but I don’t think that the noise caused by them is worth it. Here’s a simple diagram using a simplified UML dialect:

And here is the same diagram using simple blocks:

Of course that simple blocks cannot capture everything an UML model can. Some times we can use simple resources to make some concepts explicit, like the colours presented in the example below that are used to express how the components are developed as –something that would probably be expressed in UML stereotypes.

In some other occasions we do have to use UML constructs. This is not bad at all, I don’t have anything against UML (as sketch). The only reason I avoid using it for my specs is to reduce the noise in the communication. UML per se is a complex topic and it is pretty common to find people that can’t really understand what most constructs mean. Reducing everything to simple blocks let us focus on what is relevant and forget about language idiosyncrasies.

The Description
The description of each component is generally important for the spec. Even fully featured UML models can’t describe all relevant aspects of the represented components.

I used to have a little, 1 or 2 paragraphs long, description of each component. I always thought that this was extremely inefficient and didn’t provide much value.

The problem with the textual description is that prose is not always the best way to describe things. As an illustrative example, suppose you are reading the Programming Ruby book and wants to know what the Integer#times method does. You can either read the textual description of numbers or go straight to the the class reference section.

I got convinced that Structured or semi-structured information is probably a good way to describe components. The problem I had then was to find out what is enough information and what is too much.

As said previously, I’ve read a lot of papers and books about this topic and the academia has produced some really interesting stuff, like Domain-Specific Languages and formal methods for this kind of task. Although some of those even made up their way to mainstream tools, processes or techniques they are way out of what I think is good enough.

After some time trying different approaches I ended up using a fairly old technique: Class-Responsibility-Collaborator. The CRC technique was introduced by Kent Beck and Ward Cunningham “as a way of giving learners a direct experience of objects”.

CRC maps an object to three dimensions:

The class name of an object creates a vocabulary for discussing a design. […]

Responsibilities identify problems to be solved.[…] The responsibilities of an object are expressed by a handful of short verb phrases, each containing an active verb. The more that can be expressed by these phrases, the more powerful and concise the design. Again, searching for just the right words is a valuable use of time while designing.

[…] We name as collaborators objects which will send or be sent messages in the course of satisfying responsibilities. Collaboration is not necessarily a symmetric relation.

What I do is to describe components using those dimensions. The Uploader component we saw before could be described as something like this:

Uploader
Responsibilities:

• Receives a stream of bytes from the uploaded file.
• Saves the stream into the Video Storage.

Collaborators:

• Video Storage

Sometimes I still use a one-paragraph textual description, but for most specs this is enough information.

With CRC we address the components, their responsibilities and interactions. What we miss is something that tells the reader how those map to systems and applications.

Physical Components

The components we just described will be contained by applications and other systems. The other view I often use tells the audience about how those are related. It is a very simple view, usually composed of a diagram and some textual explanation about it. The diagram would be something like this:

I don’t think that there is a lot of value here but it is good to keep everyone in the same page. Sometimes people see the Logical Components diagram with tens of boxes and think that each box will be a different application.

Two tricky things about this view:

1. It leaks technology implementation information, try to keep this to a minimum. If you really, really, really need to place technology stack information on this document use a different view.
2. It has to be synchronized with the Logical diagram, what is a real pain. Do not repeat all information from the Logical diagram here, keep it to the minimum.

What’s Next?

After you write your half-dozen pages long architecture spec what happens? It all depends.

If you needed that document to place a bid proposal –and assuming you got that accepted- it is probably worth using the document as the starting point but keep in mind that it’s not supposed to dictate how your architecture will be. It is just a first take on it, based on very little information that was available at that time.

If your spec was created to make your company’s process team happy then you may have to update it frequently. If you followed my advice I imagine that your spec has very little implementation detail and won’t change daily. It would be very interesting in this case to place some tests under Continuous Integration just to be warned when the document does not reflect the architecture anymore, so someone can update the spec. Ideally you should be able to generate the spec from the code.

The most important thing to keep in mind is that this document will be outdated, and probably very quickly. Do not waste too much time trying to not let that happen because it will.

In my next post we will look at some options of how to get to the candidate architecture in a less sucky way.