Showing Software Architectures in 2+1 Views with UML

  • How can I show & explain an application or service architecture?
  • How can I draw “correct” (and what does that mean?) UML diagrams?

Let me show you how I document smallish software systems with, typically, no more than four UML diagrams. We’ll cover the questions, what is worth diagramming? and what can I do with these diagrams anyway? and we’ll cover enough UML to be useful.

I will use the example of developing a “lead generation” website, which should be simple enough to not get bogged down, but complex enough to answer some of the but how do I …? questions that more complex systems raise.

Why Diagrams?

Use diagrams as starting point to discuss, describe and explain your system. A diagram can give an instant overview of some aspect of the system. It can show important relationships on a single sheet of paper. It can raise important questions and show design decisions.

Why UML?

The UML is a visual modelling language. It has a vocabulary and grammar for diagramming software such that the diagram is a precise statement. So it can be used to show and explain software architecture.

The UML is the only diagramming standard left standing (with, perhaps, one exception that we’ll see later). You may be tempted to compete in this uncrowded field of standards for software diagrams. I comment only that the UML contains several decades of work by several thoughtful people and if you can produce a usable standard that is simpler, quicker to learn, and not unhelpfully imprecise, then I shall be impressed.

You may also be tempted — as many, many of your colleagues have been — to just do without a standard. I hope these few examples will persuade you that learning a standard is less work than you fear and more useful than you expect.

Why 2+1 views?

The UML tells you how to diagram once you’ve decided what to diagram. “2+1” is a minimal decision about what to diagram. It suggests a couple of diagrams for the logical view of your software and one for the physical view (we’ll explain what those words mean, too). That’s the 2. But it starts with the 1, which is the context.

The System Context: Shown with a UML Use Case Diagram

Always start with context. Always start with simple.

The context diagram should make sense to your non-technical customer and can be so simple you wouldn’t even give it a second glance. It shows:

  • Who and what will use the system
  • What the system will do
  • Who and what the system will rely on

In the UML, anyone or anything who uses the system, or is relied on by the system to do its thing, is an Actor. What the system will do is a UseCase. A UseCase is a instance of the system being used to do something. It is shown on a diagram just by its name, which is a single descriptive phrase, in an ellipse.

  • Anything inside the box is what the system does.
  • Anything outside the box is the context of the system.

How to Use a Context / Use Case Diagram?

Use the diagram to discuss scope, expectations and dependencies with the system’s customers and with the development team who will build it. Its simplicity and brevity should also clarify what is not (or not yet) expected of the system. Like user stories, the brevity calls for conversation to clarify. Complex Use Cases call for detailed careful business analysis too, but that is done with words, not pictures.

For your developers, this diagram is the high level overview of what they’re delivering — everything inside the box — and what the system will need for it to work — everything outside the box.

I really like having a “hand drawn” look when first showing diagrams, because it says “work in progress” and invites participation. A precisely drawn diagram risks the impression of being a final decision.

I try to draw diagrams to be read from top left to bottom right. So I put “active” Actors—the users—on the left, and “dependency” actors on the right. That’s not a part of UML, but it’s part of how I will talk through the diagram.

Here’s the same diagram later on on the project. In phase two, we’re giving visitors SMS feedback, and adding a whole new bit of functionality to read events from the customer service team and integrate then with web analytics.

Use Case diagram with several use cases, 2 user actors and 5 machine actors.


What if you have lots of use cases? Don’t put more on one diagram than you can usefully discuss in a single session. Pick out the main use cases & those that show the main external dependencies (which probably means, the ones that pose the highest risk to your project). Optionally, have a second diagram for all use cases, but only if you have an audience for it.

UML Definitions

There are 3 things you need to know for this diagram:

Actor, UseCase, and Subject aka System Boundary

Here are their definitions, which I’ve abbreviated from the UML 2.5 spec, section 18 Use Cases.

UseCases are a means to capture the requirements of systems, i.e., what systems are supposed to do. The key concepts specified in this clause are Actors, UseCases, and subjects. Each UseCase’s subject represents a system under consideration to which the UseCase applies. Users and any other systems that may interact with a subject are represented as Actors.

A UseCase is a specification of behavior. An instance of a UseCase refers to an occurrence of the emergent behavior that conforms to the corresponding UseCase. Such instances are often described by Interactions.

An Actor models a type of role played by an entity that interacts with the subjects of its associated UseCases (e.g., by exchanging signals and data). Actors may represent roles played by human users, external hardware, or other systems.

NOTE. An Actor does not necessarily represent a specific physical entity but instead a particular role of some entity that is relevant to the specification of its associated UseCases. Thus, a single physical instance may play the role of several different Actors and, conversely, a given Actor may be played by multiple different instances.

NOTE. The term “role” is used informally here and does not imply any technical definition of that term found elsewhere in this specification.

A UseCase is shown as an ellipse, either containing the name of the UseCase or with the name of the UseCase placed below the ellipse. An optional stereotype keyword may be placed above the name.

A subject for a set of UseCases (sometimes called a system boundary) may be shown as a rectangle with its name in the top-left corner, with the UseCase ellipses visually located inside this rectangle.

An Actor is represented by a “stick man” icon with the name of the Actor in the vicinity (usually above or below) the icon. An Actor may also be shown as a Classifier rectangle with the keyword «actor»

Other icons that convey the kind of Actor may also be used to denote an Actor, such as using a separate icon for non- human Actors.


The spec: https://www.omg.org/spec/UML

I have used 3 more UML features to add explanations:

  • A Comment is “a textual annotation that can be attached to a set of Elements”. A Comment is shown as a rectangle with the upper right corner bent (this is also known as a “note symbol”). The rectangle contains the body of the Comment. The connection to each annotatedElement is shown by a separate dashed line. The dashed line connecting the note symbol to the annotatedElement(s) may be suppressed if it is clear from the context, or not important in this diagram.
  • A Dependency “implies that the semantics of the clients are not complete without the suppliers”. A Dependency is shown as a dashed arrow between two model Elements. The model Element at the tail of the arrow (the client) depends on the model Element at the arrowhead (the supplier) .
  • InformationFlows “describe circulation of information through a system in a general manner. They do not specify the nature of the information, mechanisms by which it is conveyed, sequences of exchange or any control conditions”. An InformationFlow is represented using the same notation as Dependency , with the keyword «flow» adorning its dashed line.

Conway’s Law & Distributed Working. Some Comments & Experience

The eye-opener in my personal experience of Conway’s law was this:

A company with an IT department on the 1st floor, and a marketing department on the 2nd floor, where the web servers were managed by the marketing department (really), and the back end by the IT department.

I was a developer in the marketing department. I could discuss and change web tier code in minutes. To get a change made to the back end would take me days of negotiation, explanation and release co-ordination.

Guess where I put most of my code?

Inevitably the architecture of the system became Webtier vs Backend. And inevitably, I put code on the webserver which, had we been organised differently, I would have put in a different place.

This is Conway’s law: That the communication structure – the low cost of working within my department vs the much higher cost of working across a department boundary – constrained my arrangement of code, and hence the structure of the system. The team “just downstairs” was just too far.  What was that gap made of? Even that small physical gap raised the cost of communication; but also the gaps & differences in priorities, release schedules, code ownership, and—perhaps most of all—personal acquaintance; I just didn’t know the people, or know who to ask.

Conway’s Law vs Distributed Working

Mark Seemann has recently argued that successful, globally distributed, OSS projects demonstrate that co-location isn’t all it’s claimed to be. Which set me thinking about communication in OSS projects.

In my example above, I had no ownership (for instance, no commit rights) to back end code and I didn’t know, and hence didn’t communicate with, the people who did. The tools of OSS—a shared visible repository, the ability to ‘see’ who is working on what, public visibility of discussion threads, being able to get in touch, to to raise pull requests—all serve to reduce the cost of communication.

In other words, the technology helps to re-create, at a distance, the benefits enjoyed by co-located workers.

When thinking of communication & co-location, I naturally think of talking. But @ploeh‘s comments have prodded me into thinking that code ownership is just as big a deal as talking. It’s just something that we take for granted in a co-located team. I mean, if your co-located team didn’t have access to each other’s code, what would be the point of co-locating?

Another big deal with co-location is “tacit” knowledge, facilitated by, as Alistair Cockburn put it, osmotic communication. When two of my colleagues discuss something, I can overhear it and be aware of what’s going on without having to be explicitly invited. What’s more, I can quickly filter out what isn’t relevant to me, or I can spontaneously join conversations & decisions that do concern me. Without even trying, everyone is involved when they need to be in a way that someone working in a separate room–even one that’s right next door–can’t achieve.

But a distributed project can achieve this too. By forcing most communication through shared public channels—mailing lists, chatrooms, pull request conversations—a distributed team can achieve better osmotic communication than a team which has two adjacent rooms in a building.

The cost, I guess, is that typing & reading is more expensive (in time) than talking & listening. Then again, the time-cost of talking can be quite high too (though not nearly as a high as the cost of failing to communicate).

I still suspect that twenty people in a room can work faster than twenty people across the globe. But the communication pathways of a distributed team can be less constrained than those same people in one building but separated even by a flimsy partition wall.

References

The Known Unknowns Matrix

I.T. is not the only industry to have happily latched onto the the former Secretary of State’s famous phrase, “the unknown unknowns”. It’s a good phrase if you must plan or estimate anything because planning & estimating always involve risk.

But we should really consider the full matrix. There are pitfalls in at least two of the quadrants:

  Known Not Known
Knowns Things we know, and we know we know them Things we know but don’t realise we know them. Tacit knowledge that we take for granted. Becomes a problem if we are responsible, and fail, to communicate them to people who don’t know. Also a problem when we start work in a new context and do not realise that what we ‘know’ is no longer valid here, so they become unknown unknowns.
Unknowns Things we know that we don’t know. We can record the risk, and estimate a cost for investigation & discovery Things we don’t know that we don’t know. This is the quadrant most likely to shipwreck plans.

Concerning the unknown unknowns, my experience with doing novel software is that when budgeting for development you should estimate for development, plus learning time, plus developing the things you learned about, plus solving problems you didn’t know you’d have. A rule of thumb for novel systems might be, multiply your estimate by ten to cope with the unknowns. And/Or, have clear “abandon the project” criteria, even months into the project. Don’t be a dupe for the sunk-cost fallacy.

Less dramatically, my takeaway from this is to use this quadrant when listing risks and assumptions. Just having a space for the possibility of unknown knowns & unknowns can be an impetus to discuss, “risk-storm” & consult, to help your team discover the as-yet-unknowns.

P.S.

I’ve just read the brief and brilliant mcfunley.com/choose-boring-technology which points out that you can’t afford too much novelty. He suggests that for any new project you should grant yourself a limit of 3 novelty chips. When you’ve spent them, you get no more.

Well, not unless you really can overshoot your budget and timescales by over 1,000%.

Kudos

A slideshare by Danni Mannes on Agile Architecture pointed out to me all quadrants are worth some of our time.

Coplien & Bjørnvig : Lean Architecture For Agile Developers. A Review

Four years after this book came out, Agile Architecture has at last become a Thing. But as the nuance of its title hints, this book is not fad-driven. It is a carefully-thought out exposition of what architects can learn from lean and agile ideas, and what they can do better as a result.

Well. It’s partly that. If you are a practising architect, it is actually four must-read books in one.

If you are not, you might dismiss this book for two reasons. The first, that judging by other reviews & my own experience, the homespun style of the first half does not suit a bullet-pointed gimme-the-headlines-now generation. The second is that if you have not experienced the pitfalls of architecting and doing software in a real organisation with actual people in it, then Coplien & Bjørnvig’s pearls of wisdom may impress you much as the agile manifesto might impress a cattle rancher.

It is not a beginner’s book. It is the mature distillation of the sweat-soaked notebooks of a fellow-traveller who has stumbled over rocky terrain, been through the tarpits and has some hard-bloody-earned (and, academically researched) wisdom to share as a result.

I said four must-reads in one. They are:

1) The (literally) decades of experience of a leading practitioner & thinker in the field.

2) A thought-through answer to the questions, what can we learn from lean & agile. Whilst value-chains and some technique feature, the authors’ secret conviction is surely that Technology Is All About Human Beings. “Everybody, all together, from early on” is their Lean Secret. “Deferring interaction with stakeholders [users, the business, customers, domain experts, developers], or deferring decisions beyond the responsible moment slows progress, raises cost and increases frustration. A team acts like a team from the start.”

3) Which leads to that which for me, as a more techy-focused reader, was the marvel of the book. Clements et al in “Software Architecture in Practise” offered attribute-driven design, a partitioning of the system based on a priority ordering of, primarily, technical quality requirements. Coplien & Bjørnvig all but deduce a partitioning based on the priority ordering of people: Users first, Development team next.

“The end-users’ mental model” is the refrain on which they start early and never stop hammering. From this they suggest that the first partitioning is What the System Is from What the System Does. I am tempted to paraphrase as, Domain Model from Use Cases. But their point is partly that this also neatly matches the primary partition by rate of change, because the last thing to change in a business is, the business of the business. If you’re in retail, you might change what and how and where you sell, but your business is still Selling Stuff. And at lower levels inside the organisation too: an accounting department, though there has been five thousand years of technology change, still does accounting. The users know this. They understand their domain and if the fundamental form of your software system matches the end user mental model then it can survive–nay, enable!–change and stay fundamentally fit for purpose.

Second, don’t fight Conway’s law. “Organizations which design systems … are constrained to produce designs which are copies of the communication structures of these organizations”. The deduction for agile teams is, partition so as to maximise the long-term autonomy of your self-organising teams. Even when the team divisions are imposed for non-technical reasons–geography, politics, whatever–still allow that fact to trump more ‘technical’ considerations. This may not match your vision of technical perfection, but it will still be the best way. Ruth Malan recently paraphrased Conway’s law as, “if the architecture of the system and the architecture of the organization are at odds, the architecture of the organization wins”. Don’t be a loser.

These points seem to me obvious in hindsight, yet they turn traditional approaches to high-level designs on their head. After considering People, yes we can considering rates of change, quality attributes, technology areas. But it’s always People First.

4) And finally. This is the first book-sized exposition of DCI architecture, which I would describe as an architectural pattern for systems that have users. Having separated What the System Is from What the System Does, DCI provides the design pattern for how What the System Does (the Use Cases) marshals the elements of the What the System Is. There are at least three notable outcomes.

Firstly that use cases are mapped closely to specific pieces of code; in the best case each use case can be encapsulated in its own component.

Secondly, that the relationship between Domain elements and Use Cases are expressed as “In Use Case X Domain element Y plays the Role of Z”. This brings significant clarity to both, and is part of the key to ‘componentising’ use cases; the Roles needed for a use case become, in the code, its public dependencies. In UML-speak, the Required Interfaces for such a UseCaseComponent are the roles needed to ‘play’ the use case, and those roles are Interfaces which are implemented by Classes in the Domain Model. Coupling is reduced, cohesion is gained, clarity is achieved.

Thirdly, the simpleness of the mapping from business architecture to code is greatly increased. Suddenly one can draw simple straight lines between corresponding elements of architecture and code.

The authors say of their work, “This book is about a Lean approach to domain architecture that lays a foundation for agile software change”. To my mind, this hits the agile architecture nail on the head. Agile software development always only ever succeeded at scale because the people doing it either knew, or had given to them, enough architecture to make it work. Software Agility, just like every other software -ility, must either be supported by the architecture or it ain’t gonna happen.

But the best thing I got from this book was the proof, before my very eyes, that correct technical design flows from knowing how to put the human beings central.

Where to Buy

UK



ebay (UK): Lean Architecture for Agile Software Development


Amazon (UK): Lean Architecture for Agile Software Development

USA



Amazon (USA): Lean Architecture for Agile Software Development