Blog Posts tagged with: architecture

Aug 28 2013


Architecture and Financial Success

At our most recent internal conference, Tim Ewald gave us a passionate talk on the topic of architecture and design. He said that a successful solution must deliver features, while exhibiting certain desirable properties and meeting constraints. Features are the things it should do: send email, display cat photos, and display notifications. Properties are the less visible characteristics, sometimes called "non-functional requirements." Constraints are the boundaries that the solution cannot exceed.

In a contrived example: For structures, the force of gravity is a constraint. Standing for the next 50 years is a property. An auditorium for performances is a feature.

While features are the simplest things to identify, they are not what determines how successful a solution is.

For example, there must be thousands of ways to place a "registration form" on the Web. Custom coded in dozens of languages, countless SaaS sites, platforms like Google docs, the number of possible solutions to this problem goes on and on. You could write a CGI perl script to run on a Raspberry Pi plugged in to a covert power outlet in your neighborhood coffee shop, running on free wifi.

All of these solutions provide the necessary features. So what makes one solution a better fit than another? How do you choose among the array of possibilities? You eliminate the solutions that won't exhibit the necessary properties. Then choose among the remainder.

For instance, does your registration form need high availability? Scalability? Is it OK to miss a few people here and there? Is it OK if the entire list gets revealed? Or are there lives on the line?

Among these properties, I think the most important ones are those that affect the financial success of the system. We tend to relegate all money matters to project managers. However, I think architects are the people who have the right skills to answer the trade-offs inherent in these questions:

  • Can it be built cost-effectively?
  • Can we profit from it, or will operational costs overwhelm us?
  • Will it be available and responsive enough to win customers?
  • Can we support an economically interesting user base?
  • Is it going to be so hard to defend that we end up losing customer data or spending a fortune on security?

All of these questions sit at the intersection of time, cost, and functionality. The architecture skill set helps a team balance these concerns and guide the system to the most positive possible outcome. Viewed this way, architecture is about creating positive financial outcomes.

Jun 07 2013


The Rule of Three

Every solution comes with costs and consequences. If you get stuck on the first thing that comes to mind, you aren't necessarily choosing the solution with the most desired balance of costs and consequences.

I use something I call "The Rule of Three."

Read More »

Feb 11 2013


Two Recent Talks

Video for two of my recent talks has gone live. Here they are!

Whence Complexity

As programmers we grapple with complexity. Whether we classify it as "essential" or "accidental" complexity, we all agree that complexity is poison. At the same time, as living beings, we are sustained by complexity. Complexity allows us to sustain our existence far from thermal equilibrium. In natural systems, complexity produces robustness. In human-created systems (whether information, social, political, or economic) complexity tends to create fragility and extreme non-linear responses to stimuli.

At Clojure/conj last November, I discussed the origin of complexity as the result of ongoing dynamic processes.

Thanks to some last-minute calculations about spherical chickens, there was also an excessively vivid mental image included, for which I apologize.

This one is on Youtube.

Loopholes in CAP

Last November, I also spoke at QCon San Francisco on the subject of the CAP Theorem (a.k.a. Brewer's Conjecture.) CAP says that, of the three qualities of "consistency", "availability", and "partition-tolerance", a distributed system can achieve at most two.

I have to confess that this was a particularly nerve-wracking talk, because I followed Eric Brewer on to the stage. Yes, that Eric Brewer, he of the Conjecture itself and one of the field's top experts.

CAP went from "conjecture" to "theorem" in 2002, when Seth Gilbert and Nancy Lynch proved it. And, thus, a thousand database products were launched. Like any theorem, though, there are subtleties to consider. In this playful talk, I look at all the assumptions underlying CAP and try to violate them all, with examples from real systems.

You can see this talk at

Nov 15 2011


Documenting Architecture Decisions


Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins.

Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team itself can have value, but only if they are kept up to date. Large documents are never kept up to date. Small, modular documents have at least a chance at being updated.

Nobody ever reads large documents, either. Most developers have been on at least one project where the specification document was larger (in bytes) than the total source code size. Those documents are too large to open, read, or update. Bite sized pieces are easier for for all stakeholders to consume.

One of the hardest things to track during the life of a project is the motivation behind certain decisions. A new person coming on to a project may be perplexed, baffled, delighted, or infuriated by some past decision. Without understanding the rationale or consequences, this person has only two choices:

  1. Blindly accept the decision.

    This response may be OK, if the decision is still valid. It may not be good, however, if the context has changed and the decision should really be revisited. If the project accumulates too many decisions accepted without understanding, then the development team becomes afraid to change anything and the project collapses under its own weight.

  2. Blindly change it.

    Again, this may be OK if the decision needs to be reversed. On the other hand, changing the decision without understanding its motivation or consequences could mean damaging the project's overall value without realizing it. (E.g., the decision supported a non-functional requirement that hasn't been tested yet.)

It's better to avoid either blind acceptance or blind reversal.


We will keep a collection of records for "architecturally significant" decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.

An architecture decision record is a short text file in a format similar to an Alexandrian pattern. (Though the decisions themselves are not necessarily patterns, they share the characteristic balancing of forces.) Each record describes a set of forces and a single decision in response to those forces. Note that the decision is the central piece here, so specific forces may appear in multiple ADRs.

We will keep ADRs in the project repository under doc/arch/

We should use a lightweight text formatting language like Markdown or Textile.

ADRs will be numbered sequentially and monotonically. Numbers will not be reused.

If a decision is reversed, we will keep the old one around, but mark it as superseded. (It's still relevant to know that it was the decision, but is no longer the decision.)

We will use a format with just a few parts, so each document is easy to digest. The format has just a few parts.

Title These documents have names that are short noun phrases. For example, "ADR 1: Deployment on Ruby on Rails 3.0.10" or "ADR 9: LDAP for Multitenant Integration"

Context This section describes the forces at play, including technological, political, social, and project local. These forces are probably in tension, and should be called out as such. The language in this section is value-neutral. It is simply describing facts.

Decision This section describes our response to these forces. It is stated in full sentences, with active voice. "We will ..."

Status A decision may be "proposed" if the project stakeholders haven't agreed with it yet, or "accepted" once it is agreed. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or "superseded" with a reference to its replacement.

Consequences This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.

The whole document should be one or two pages long. We will write each ADR as if it is a conversation with a future developer. This requires good writing style, with full sentences organized into paragraphs. Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments. (Bullets kill people, even PowerPoint bullets.)




One ADR describes one significant decision for a specific project. It should be something that has an effect on how the rest of the project will run.

The consequences of one ADR are very likely to become the context for subsequent ADRs. This is also similar to Alexander's idea of a pattern language: the large-scale responses create spaces for the smaller scale to fit into.

Developers and project stakeholders can see the ADRs, even as the team composition changes over time.

The motivation behind previous decisions is visible for everyone, present and future. Nobody is left scratching their heads to understand, "What were they thinking?" and the time to change old decisions will be clear from changes in the project's context.

Experience Report

You may have noticed that this post is formatted like an ADR itself. We've been using this format on a few of our projects since early August. That's not a very long time in the global sense, but early feedback from both clients and developers has been quite positive. In that time, we've had six to ten developers rotate through projects using ADRs. All of them have stated that they appreciate the degree of context they received by reading them.

ADRs have been especially useful for capturing longer-term intentions. We have several clients who are stabilizing their current systems, but looking toward a larger rearchitecture in the not-too-distant future. By writing these intentions down, we don't inadvertently make those future changes harder.

One potential objection is that keeping these in version control with the code makes them less accessible for project managers, client stakeholders, and others who don't live in version control like the development team does. In practice, our projects almost all live in GitHub private repositories, so we can exchange links to the latest version in master. Since GitHub does markdown processing automatically, it looks just as friendly as any wiki page would.

So far, ADRs are proving to be a useful tool, so we'll keep using them.

More Reading

Thanks to Philipe Kruchten for discussing the importance of architecture decisions. I'm told there is more about them in Documenting Software Architectures which is near the top of my reading queue.

Popular Tags