Mike MacDonagh's Blog

Somewhere in the overlap between software development, process improvement and psychology

Lightweight architecture sketch in a single diagram

This blog is based on Architecture in Holistic Software Engineering.

I’ve been doing architecture for a while, in fact it’s what I used to do as my main job. I’ve taught UML, Object Orientated design and coding and various bits of various processes for years. One thing that’s stuck me over the years is that most of the descriptions of how to capture and communicate architecture aren’t simple enough.

I quite like UML, it’s useful to be able to draw a symbol and others know what it is without me having to explain to everyone what I mean, but I don’t like the way it has so many restrictive rules that stop me from making a nice sketch to explain what I mean, also everyone else doesn’t seem to know the language to the same degree, I need something a bit lighter.

I don’t want:

  • to be limited to the symbology of UML
  • a lot of model structure with interconnected diagrams
  • endless detail
  • every class on the diagram
  • to follow all of the rules
 I do want:

  • the symbology of UML
  • the important elements
  • to give a feel of the important structural, logical and physical stuff
  • just one diagram

I’ve always done a high level diagram that shows the overall pattern for my architecture, something like layers or pipes and filters or whatever. I’ve also always done a breakdown of the important stuff within each layer but I’ve had the best success (in terms of communicating with others) when I’ve mixed both, with elements of the target deployment and actor interaction.

Being terrible at naming things I call this marvellous diagram the “Architectural Overview Sketch”. Here’s an example:

It  expresses all of the structural things that I care about. It expresses the:

  • the shape and feel of the system
  • high level layers
  • primary interfaces between subsystems
  • target client platforms
  • User – GUI interaction paradigm
  • important classes in each layer and major layer package structure
  • critical data schema
  • interaction with external APIs
  • the middleware and database hosting and distribution

I might have more diagrams to explain more structure in part of this if it’s really important, but I don’t want to have every class in my system on a diagram somewhere. I’m using my diagrams to communicate, not specify. I’m broken a bunch of UML rules of course, and there’s a lot of implied stuff but adding those details makes it harder to explain what I really want. One thing I really like about it is how it shows the important detailed parts of a design in the context of the bigger architecture.

Architecture, like any design, is best expressed in terms of both structure and behaviour. So far this is just structure, there’s some hints at behaviours but nothing terribly useful. My next post will be about how I minimally specify the important bits of an architectures behaviour – the mechanisms.


4 responses to “Lightweight architecture sketch in a single diagram

  1. Todd Meinershagen May 20, 2014 at 12:27 am

    I noticed that in your diagram you are using the symbols that Ivar Jacobson uses in “Object Oriented Software Engineering: A Use Case Driven Approach”. Do you happen to have a Visio stencil that you could share with those shapes?

    • mikemacd May 20, 2014 at 1:18 am

      Hi Todd, thanks for your question. I actually got so fed up with the lack of a decent (cheap) modelling tool that could use the UML symbology and also give total freedom that I decided to write one myself. All of these graphics are made with my own modelling tool which I hope to make public later this year, it’s only at alpha release at the moment.

  2. Shalin January 13, 2015 at 11:55 am

    What is the tool you used to create this use case. The use case looks neat. I’m wondering if it is a free or at least free to try version so i could use everyday. thanks for sharing!

    • mikemacd January 19, 2015 at 12:17 pm

      Hi Shalin, the graphics were done with a modelling tool I’m currently developing – it’s a bit of a side project at the moment due to other work but I’m still cracking on with it. I’ll announce it on this blog when it’s ready for beta.

What do you think?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: