The delivery mechanism is an annoying detail

Unfortunately it can be a relatively large annoying detail though

In my The Frustrated Architect presentation at GOTO Aarhus in October*, I talked about how there are a number of "classic" software design techniques from the pre-agile era that are being used less and less. For example, things like UML, class-responsibility-collaboration cards and component-based design. This is a shame because some of these techniques can complement an agile way of working and would perhaps prevent some wheels from being reinvented. If people don't know about these techniques though, how will they adopt them? I'll come back to this shortly but, first, I was intrigued by this tweet from Uncle Bob a few weeks back.

The architecture of an accounting app should scream accounting not Spring & Hibernate.

I don't necessarily disagree with this statement, although I like to see a software architecture grounded in reality, and that includes technology choices. Another tweet from Uncle Bob...

A good architecture allows you to defer framework decisions. A good architecture allows frameworks to act as plugins to the app.

Again ... maybe, maybe not. Surely if there are some key technology choices that need to be made, then they should be made, right? Finally, another tweet...

I am amazed by the fact that some people actually disagree that a good software architecture allows you to defer framework decisions.

Hmmm, if I don't or can't defer decisions, does this mean that I have a bad architecture? Shouldn't deferral be a conscious decision rather than a rule? All of this and the discussion that followed on Twitter intrigued me enough to stump up the cash for Clean Code Episode VII - Architecture, Use Cases, and High Level Design to see what Uncle Bob's perspective on architecture is.

Clean Code Episode VII - Architecture, Use Cases, and High Level Design

Now that I've watched it, what do I think? Well I'm really pleased to see coverage of a couple of things. The first is describing functionality through delivery mechanism independent use cases, where there is no discussion of web pages, screens, buttons, technology, etc. And the second is the follow-up technique where you decompose a use case down into a number of different classes, each of which has a distinct responsibility. These are entities (e.g. business objects), controllers (also known as interactors, which represent the actual flow of control described in the use cases) and boundaries (which represent an interaction with an actor through the "delivery mechanism"). What these techniques basically do is allow you to describe and implement a use case in a way that is completely independent from the way that the use case will be delivered. In effect, you can bolt-on a number of different delivery mechanisms (e.g. a web or console app) without changing the actual core of "the application", which is ultimately the functionality that is being described by the use cases. As I said at the start of this post, these are the sort of techniques that many people don't know about, so I'm really pleased to see them being communicated here.

I'm in agreement then?

Coming back to Uncle Bob's tweets, I can now see his perspective. Adopting this approach does allow you to defer technology decisions and from the perspective of the use cases, this technology stuff is really just an "annoying detail".

You can plug-in the delivery mechanism to the application

I agree that the boundary-controller-entity technique is a great way to design software because the result is a really nice separation of concerns, which ultimately leads to something that can be easily unit tested and extended in the future. This is all about partitioning and isolation. OK, so I'm agreeing with Uncle Bob then? Hmm, not quite.


Throughout the video, Uncle Bob says the following (which I've paraphrased).

The architecture of an accounting app should scream accounting. A web and console version of the same accounting app should have identical architectures. The web delivery mechanism is a detail.

This is repeated a number of times through the video and it's based upon all of the good stuff that I've talked about above. However, I find myself in strong disagreement with the message as a whole. And here's why ... because the word "architecture" is being used. At face value this might sound pedantic but let's consider for a moment what Uncle Bob is actually talking about by redrawing the above diagram. Let's imagine that you're building an accounting app that you want to deliver over the web. Security is important so let's break it into multiple physical tiers. And we need to store all of the accounting data somewhere, so let's use a database. How does that annoying detail look now then...

Architecture is about the big picture

That's right, the annoying detail is actually a large chunk of the system and, for me, architecture is about more than just what's contained within "the application". Structure is very important, but what about that tricky stuff like non-functional requirements, the actual delivery mechanism (technologies, frameworks, tools, APIs, etc), infrastructure services (e.g. logging, exception handling, configuration, etc), integration services (internal and external), satisfying any environmental constraints (e.g. operations and support), etc. For me, this is what "architecture" is all about and *that's* "the whole enchilada".

*I'll be presenting The Frustrated Architect at Skills Matter in London on the 15th of November and you can sign-up for free


If you don't have the video but want to get a feel for Uncle Bob's approach to architecture, take a look at the following links...

About the author

Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.

You can find Simon on Twitter at @simonbrown ... see for information about his speaking schedule, videos from past conferences and software architecture training.

Re: The delivery mechanism is an annoying detail

Hi Simon, I also found some recent tweets from Uncle Bob confusing. He's using Twitter to promote his Clean Code, which is no problem at all. But some tweets themselves are quite misleading to the community.

Re: The delivery mechanism is an annoying detail

Hi Simon One time we met at your presentation in London. There were a lot of good things there. Thanks Concerning Clean Architecture I think you have not got the topic ... 1) Uncle Bob does not say that delivery (frameworks,DB etc) is not important. He just say what is most important. 2) He says something about plug-ability So that means that you have the possibility to change the framework any time you want etc ... You can experiment with minimum risks... In my opinion this is one of the dreams of many architects Frameworks comes and goes but Application (domain, use-cases etc) just evolves ... 3) if you defer your delivery decisions you do not build the business code, framework specific. 4) We all have stereotypes It takes time to adopt new things ...

Re: The delivery mechanism is an annoying detail

After reading your article, and not being familiar with the book of Uncle Bob, I would like to make the following observation.

To me the 'boundries, controllers and entities' part is not architecture. It looks a lot like functional design, maybe even technical design and there probably are some architectural concerns being covered. But the whole of it should not be called architecture. As you say: It is a part of the big picture.

Re: The delivery mechanism is an annoying detail

Also the ability to put off this decision is very much dependent on how much your projects follow an existing pattern - which in almost all cases seems to be a database-driven driven business system. It's really easy to put off major technology decisions when actually you're only picking from a couple anyway because you're basically in the same sort of problem domain as you always are. When you start to push those boundaries a little - maybe getting into intersection with real physical systems such as augmented reality, a set-pieces for museums, ticketing systems for trains. Or maybe you're utilising relatively new technology where different approaches give you different options, such as in the mobile space. In these cases technology is a major part of your architecture decision which can open up or close down many avenues, and putting this decision off is absolutely impossible. Every system needs architecture, not just traditional enterprise business systems. I get a little frustrated when I see software engineering articles only really talking from the perspective of this single vertical market.

Keep functional and non-functional requirements separate.

I responded to Uncle Bob on his Posterous blog when he posted this opinion. Like you, I define an architecture as that which solves the non-functional requirements, independent of the domain. So I have to disagree when he asserts that the architecture should scream the domain.

I see things quite differently. Functional requirements change frequently. Non-functional requirements change infrequently. To be agile enough to respond to business changes, we can't let the architecture depend upon the domain. I lay out my argument in Keep functional and non-functional requirements separate.

Keep functional and non-functional requirements separate.

"I define an architecture as that which solves the non-functional requirements, independent of the domain"

I wouldn't agree with that at all. Architecture is there to support the fulfilment of all requirements. Sure, if your functional requirements don't rely on any aspect of the tech then you might conclude that architecture and functional requirements are orthogonal, but that's just a particular type of project rather than a global rule. Of course, that tends to be the implied context in many of these discussions.

There are many environments where the delivery mechanism and architecture supporting that is very much a functional requirement, and where the architectural solution isn't swappable without functional effect.

For traditional DB-driven business systems, where you're given a business process to automate / assist users with, the underlying tech, architecture & delivery channel are not necessarily significant factors that anyone other than developers/ops sees, but that's far from the only kind of software that needs architecture.

When you choose not to decide...

I think the key irony underlying Bob's description of the accounting app is that he has, in fact, chosen an architecture. And he has done so quite early. The choice to structure the application in terms of controllers and entities is precisely an architectural choice.

Less pedantically, I distinctly remember a generation of applications that were thin "webifications" of desktop apps. These attempted to build a core application independent of the delivery mechanism, precisely as Bob suggests. All of them ended up hopelessly snarled in state management nightmares. They didn't scale, tended to lock up badly (due to database transactions), and were painful to use because they did too many page reloads.

At the root, I think the architecture of a system must balance the forces acting on it. Some of those forces emerge from the application domain, but many of them also emerge from the technology domain.

One of these delivery media responds best to command-oriented transactions that do not rely on keeping state in memory. The other works best when state is kept in memory for rich interaction. With so many fundamental forces in opposition, how could we expect the architecture to be the same?

Would one ever build web applications out of a bunch of .ocx'es in containers? Would one ever build a desktop application out of hyperlinked resources? Only as an exercise in perversity. This isn't because we have bad frameworks or leaky abstractions (though both exist). It's because the fundamental nature of desktop and web applications are different. Ignoring that entire aspect just because it doesn't come from the business domain is irresponsible.

When you choose not to decide...

I think the key irony underlying Bob's description of the accounting app is that he has, in fact, chosen an architecture. And he has done so quite early. The choice to structure the application in terms of controllers and entities is precisely an architectural choice.

I agree, and the choice to defer decisions (e.g. through the use of layers, adapters, etc) is also a significant decision. People often tell me that they use an ORM (e.g. Hibernate) in order to defer the database decision. Of course there's still a significant decision here ... but it's the ORM rather than the database. Significant decisions don't necessarily disappear, they just move elsewhere.

When you choose not to decide...

In all fairness, Bob wasn't advocating delaying architecture decisions. He was advocating creating an architecture that allows you defer framework decisions.

When you choose not to decide...

Except for the part where he says that you can build your entire application without considering your technology decisions if you decouple appropriately ... and then plug-in your delivery mechanism at the end. ;-)

Re: The delivery mechanism is an annoying detail

It is interesting that no one has mentioned the origin of the BCE pattern.

Ivar Jacobson may be best know for introducing use cases, but his book "Object-Oriented Software Engineering: A Use Case Driven Approach" actually included a complete, end-to-end modeling methodology. Use cases are used to capture the requirements of a system, and that does, in fact, drive the rest of the process. But the next step is to do "robustness analysis", which involves modeling system functionality meeting the use case requirements in terms of boundary, controller and entity objects (I believe "boundary" was initially "interface", but that later become confusing with other uses of the term).

What I think is key here is that the BCE pattern is used as part of analysis. It was not intended to provide an overall "architecture" for the system. Indeed, once one adds in consideration of those annoying implementation details, there is an immediate need to control complexity. This then leads to the internal division of a system into subsystems, which can be done in various ways, with various trade-offs. The whole rest of Jacobson's approach handles these sorts of considerations, allocating functionality down to subsystems and then, if necessary, recursively analyzing and designing those subsystems. After all, Jacobson's background was in the telecom industry in which the architecture of very large "systems of systems" is paramount!

Jacobson's own view on all this has, of course, evolved over the years (he is a big proponent of agile these days). But still, to me at least, an important lesson is that architecture has to do with mediating the stakeholder requirements for a system with the engineering realities of building the system. A good analysis technique like BCE can be a crucial link in doing this. But that is really just the beginning of the architect's work.

In any significant system, the devil is often in those annoying details!

Re: The delivery mechanism is an annoying detail

That's actually where I first came across BCE ... during the analysis phase of a large RUP project. We had some coaching from Rational (as they were at the time) to help us take our use cases through to BCE style diagrams. It was then a "simple" transformation from controllers to J2EE session beans and from entities to J2EE entity beans. I seem to remember that Rational Rose even had a set of icons for the appropriate EJB stereotypes. Ah, good times. ;-)

But yes, the devil is indeed in those annoying details!

Re: The delivery mechanism is an annoying detail

Simple transformation, ha!

In the late 90's I worked on a modeling and transactional coding (just pre-EJB) framework that started with use case patterns tied to BCE analysis patterns on the front end. But there were then two more levels of architectural models before you had worked out all the implementation decisions! Not to mention the possibility of recursing into analysis of the subsystems of a large system.

In order to be able to flexibly handle changes in architectural and implementation decisions, you need to have an explicit record for what those decision were. To me, "agile" really requires being able to quickly and efficiently move back and forth between all these levels between requirements and code.

Re: The delivery mechanism is an annoying detail

Good to see some Rational Rose vets in here ;) I spent about 5 years from 2001 with Rose on a large project which was half-EJB (we used session beans and connectors but not entity beans because their performance was terrible!). We used most of Rose's features from analysis downwards, and below a certain level generated the tedious aspects such as glue code. There was also a fairly formal hand-off between architecture, design and coding, and I was in all the roles at one point or other. What I learned from this process was that far from helping with managing scale and complexity (small projects typically having multi-purpose architecture/developer roles by nature), in a large project your model and division of responsibilities can become a burden. It got to the stage where our wiki which covered the architecture, design principles, idioms etc was far more useful than the model itself, simply because it was digestible and more easily applied. Having an architecture and good design / coding idioms was essential, but beyond that, rather than trying to scale up to lots of low-level developers with a couple of designers and trying to manage that with detailed modelling, you were better with just a small number of highly experienced developers who could cut across all levels, and who didn't really need a (full) model at all. I haven't used formal UML diagrams or model->code generation since 2006, and I don't miss them. :)

Re: The delivery mechanism is an annoying detail

I would agree that "trying to scale up to lots of low-level developers with a couple of designers and trying to manage that with detailed modelling" is generally a losing proposition.

On the other hand, in my experience, models can be a great way for "a small number of highly experienced developers" (very much the kind of team I like to have!) to communicate amongst themselves and with stakeholders. But models are just a means for communication and documentation toward the end of developing a successful system. Certainly, if the models you are doing aren't helping you do you do your job better and faster, then don't do them!

But that's the topic of a whole other conversation...

Re: The delivery mechanism is an annoying detail

Yes, I agree. It's not that I stopped modelling, I just stopped trying to make the model 'complete'. A decade ago there was definitely an environment that promoted the model as the #1 repository of information about your system, from top to bottom, use-case analysis to code generation. I wholeheartedly agree with Simon's "Just enough architecture" approach (which I assume implicitly means 'just enough modelling' too) based on this experience.

Re: The delivery mechanism is an annoying detail

Considering that models are best used for communication, how much effort should be spent on keeping them in sync with the code? Presumably, the communication for which they were first created has already taken place.

Re: The delivery mechanism is an annoying detail

For me, one of the most important uses of models is communicating over time. The need for communication only ends when all development on a system ends. And I don't particularly believe in separating "development" and "maintenance" (the latter is were most of the effort is, anyway!)

Even when a lot of effort is focused on producing good code, too many programming details have to be mixed in to allow the code to communicate overall system design and architecture well enough. Good models can do that -- as long as they do stay in sync with the code. You can do that through process discipline or tooling support -- or even by making your models executable so they become the code.

But if you can't keep your models in sync and they end up communicating the wrong information, then that's worse than not having them.

Re: The delivery mechanism is an annoying detail

Keeping the model at a high level, dealing with architecture and idioms rather than every specific instance of those patterns is the key IMO.

Having participated in projects where the model went right down to an implementation level, whether that's for communication or direct code generation, I find it pretty unworkable at any non-trivial scale. Try getting version control set up for a large, very detailed model for instance where many people have to be involved, we used to partition our heavily to try to deal with that, but it was always far slower and more cumbersome for detail work than the code was. Better to just represent the high-level architecture, principles and idioms in the model (and it doesn't even need to be in a modelling tool for that, in fact something more free-form like a wiki was often more powerful) and let the implementors instantiate / specialise the patterns appropriately. Another reason a wiki was better than a formal model was that these implementors could feed back any specialisations or issues for peer review far more easily.

Re: The delivery mechanism is an annoying detail

Thanks for this, great post, I found it very useful. I was considering buying a couple of Uncle Bobs videos but they seemed a bit pricey, I might start with this one first and test the water :-)

Re: The delivery mechanism is an annoying detail

Uncle Bob wants to defer decisions to the last RESPONSIBLE moment. That is as late as possible, where you can make an informed decision instead of guesswork. Pretty agile I would say! :)

The last responsible moment for decisions like what language to use and what SCM to use is right at the project start. Which database to use is not decided upfront. So even Uncle Bob agrees that some decisions can not be deferred for very long. :)

Here is a talk by Uncle Bob at the Norwegian Developers Conference where he talks about Clean Architecture. He obviously explains it a lot better than I do. :)

Re: The delivery mechanism is an annoying detail

I found your points interesting. Uncle Bob doesn't give you the whole answer. And I am quit sure that is by intent. You don't want to lecture people om which pattern approch you want your readers to use because that would derail the main message in the talk; that the use cases should be in the center of the architecture, not frameworks, not delivery mechanisms and not patterns. Although the patterns may help you. I was just now searching the web for an answer to the same question you where having. (How to isolate the delivery mechanisms from the application) And I think I found the obvious answer. One way of isolating the delivery mechanism is by using ports and adapters: Alistair Cockburn has a very good explanation on how you can go about using it. So if you where to use a rail framework then you would have to extend your controllers with an interface that you would have adapt your application into using by writing an adapter for using rail framework., Delegation of workflow , inversion of dependencies/dependency injection and/or service locator, maybe also pipes and filters if you need to use events, would have to be used to be able to make it work depending on the complexity of your application. I think what uncle Bob is saying, is that there isn't one solution out there, but a collection of them that you would have to apply in the right order and context.

Re: The delivery mechanism is an annoying detail

Robert C. Martin’s proposal is completely coherent with the Ports and Adapters architectural pattern a.k.a. Hexagonal pattern as described by Alistair Cockburn.

Add a comment Send a TrackBack