Software Architecture as Code

if you've been following the blog, you will have seen a couple of posts recently about the alignment of software architecture and code. software architecture vs code talks about the typical gap between how we think about the software architecture vs the code that we write, while an architecturally-evident coding style shows an example of how to ensure that the code does reflect those architectural concepts. the basic summary of the story so far is that things get much easier to understand if your architectural ideas map simply and explicitly into the code.

regular readers will also know that i'm a big fan of using diagrams to visualise and communicate the architecture of a software system, and this "big picture" view of the world is often hard to see from the thousands of lines of code that make up our software systems. one of the things that i teach people during my sketching workshops is how to sketch out a software system using a small number of simple diagrams, each at very separate levels of abstraction. this is based upon my c4 model , which you can find an introduction to at simple sketches for diagramming your software architecture . the feedback from people using this model has been great, and many have a follow-up question of "what tooling would you recommend?". my answer has typically been "visio or omnigraffle", but it's obvious that there's an opportunity here.

representing the software architecture model in code

i've had a lot of different ideas over the past few months for how to create, what is essentially, a lightweight modelling tool and for some reason, all of these ideas came together last week while i was at the goto amsterdam conference. i'm not sure why, but i had a number of conversations that inspired me in different ways, so i skipped one of the talks to throw some code together and test out some ideas. this is basically what i came up with...

model model = new model();
 
softwaresystem techtribes = model.addsoftwaresystem(location.internal, "techtribes.je", "techtribes.je is the only way to keep up to date with the it, tech and digital sector in jersey and guernsey, channel islands");
 
person anonymoususer = model.addperson(location.external, "anonymous user", "anybody on the web.");
person aggregateduser = model.addperson(location.external, "aggregated user", "a user or business with content that is aggregated into the website.");
person adminuser = model.addperson(location.external, "administration user", "a system administration user.");
 
anonymoususer.uses(techtribes, "view people, tribes (businesses, communities and interest groups), content, events, jobs, etc from the local tech, digital and it sector.");
aggregateduser.uses(techtribes, "manage user profile and tribe membership.");
adminuser.uses(techtribes, "add people, add tribes and manage tribe membership.");
 
softwaresystem twitter = model.addsoftwaresystem(location.external, "twitter", "twitter.com");
techtribes.uses(twitter, "gets profile information and tweets from.");
 
softwaresystem github = model.addsoftwaresystem(location.external, "github", "github.com");
techtribes.uses(github, "gets information about public code repositories from.");
 
softwaresystem blogs = model.addsoftwaresystem(location.external, "blogs", "rss and atom feeds");
techtribes.uses(blogs, "gets content using rss and atom feeds from.");
 
container webapplication = techtribes.addcontainer("web application", "allows users to view people, tribes, content, events, jobs, etc from the local tech, digital and it sector.", "apache tomcat 7.x");
container contentupdater = techtribes.addcontainer("content updater", "updates profiles, tweets, github repos and content on a scheduled basis.", "standalone java 7 application");
container relationaldatabase = techtribes.addcontainer("relational database", "stores people, tribes, tribe membership, talks, events, jobs, badges, github repos, etc.", "mysql 5.5.x");
container nosqlstore = techtribes.addcontainer("nosql data store", "stores content from rss/atom feeds (blog posts) and tweets.", "mongodb 2.2.x");
container filesystem = techtribes.addcontainer("file system", "stores search indexes.", null);
 
anonymoususer.uses(webapplication, "view people, tribes (businesses, communities and interest groups), content, events, jobs, etc from the local tech, digital and it sector.");
authenticateduser.uses(webapplication, "manage user profile and tribe membership.");
adminuser.uses(webapplication, "add people, add tribes and manage tribe membership.");
 
webapplication.uses(relationaldatabase, "reads from and writes data to");
webapplication.uses(nosqlstore, "reads from");
webapplication.uses(filesystem, "reads from");
 
contentupdater.uses(relationaldatabase, "reads from and writes data to");
contentupdater.uses(nosqlstore, "reads from and writes data to");
contentupdater.uses(filesystem, "writes to");
contentupdater.uses(twitter, "gets profile information and tweets from.");
contentupdater.uses(github, "gets information about public code repositories from.");
contentupdater.uses(blogs, "gets content using rss and atom feeds from.");

it's a description of the context and container levels of my c4 model for the techtribes.je system. hopefully it doesn't need too much explanation if you're familiar with the model, although there are some ways in which the code can be made simpler and more fluent. since this is code though, we can easily constrain the model and version it. this approach works well for the high-level architectural concepts because there are very few of them, plus it's hard to extract this information from the code. but i don't want to start crafting up a large amount of code to describe the components that reside in each container, particularly as there are potentially lots of them and i'm unsure of the exact relationships between them.

scanning the codebase for components

if your code does reflect your architecture (i.e. you're using an architecturally-evident coding style), the obvious solution is to just scan the codebase for those components, and use those to automatically populate the model. how do we signify what a "component" is? in java, we can use annotations...

package je.techtribes.component.tweet;

import com.structurizr.annotation.component;
...

@component(description = "provides access to tweets.")
public interface tweetcomponent {

  /**
   * gets the most recent tweets by page number.
   */
  list<tweet> getrecenttweets(int page, int pagesize);

  ...
  
}

identifying those components is then a matter of scanning the source or the compiled bytecode. i've played around with this idea on and off for a few months, using a combination of java annotations along with annotation processors and libraries including scannotation, javassist and jdepend. the reflections library on google code makes this easy to do, and now i have simple java program that looks for my component annotation on classes in the classpath and automatically adds those to the model. as for the dependencies between components, again this is fairly straightforward to do with reflections. i have a bunch of other annotations too, for example to represent dependencies between a component and a container or software system, but the principle is still the same - the architecturally significant elements and their dependencies can mostly be embedded in the code.

creating some views

the model itself is useful, but ideally i want to look at that model from different angles, much like the diagrams that i teach people to draw when they attend my sketching workshop. after a little thought about what this means and what each view is constrained to show, i created a simple domain model to represent the context, container and component views...

model model = ...
softwaresystem techtribes = model.getsoftwaresystemwithname("techtribes.je");
container contentupdater = techtribes.getcontainerwithname("content updater");
 
// context view
contextview contextview = model.createcontextview(techtribes);
contextview.addallsoftwaresystems();
contextview.addallpeople();
 
// container view
containerview containerview = model.createcontainerview(techtribes);
containerview.addallsoftwaresystems();
containerview.addallpeople();
containerview.addallcontainers();
 
// component view for the content updater container
componentview componentview = model.createcomponentview(techtribes, contentupdater);
componentview.addallsoftwaresystems();
componentview.addallcontainers();
componentview.addallcomponents();
// let's exclude the logging component as it's used by everything
componentview.remove(contentupdater.getcomponentwithname("loggingcomponent"));
componentview.removeelementswithnorelationships();

again, this is all in code so it's quick to create, versionable and very customisable.

exporting the model

now that i have a model of my software system and a number of views that i'd like to see, i could do with drawing some pictures. i could create a diagramming tool in java that reads the model directly, but perhaps a better approach is to serialize the object model out to an external format so that other tools can use it. and that's what i did, courtesy of the jackson library . the resulting json file is over 600 lines long ( you can see it here ), but don't forget most of this has been generated automatically by java code scanning for components and their dependencies.

visualising the views

the last question is how to visualise the information contained in the model and there are a number of ways to do this. i'd really like somebody to build a google maps or prezi-style diagramming tool where you can pinch-zoom in and out to see different views of the model, but my ui skills leave something to be desired in that area. for the meantime, i've thrown together a simple diagramming tool using html 5, css and javascript that takes a json string and visualises the views contained within it. my vision here is to create a lightweight model visualisation tool rather than a visio clone where you have to draw everything yourself. i've deployed this app on pivotal web services and you can try it for yourself . you'll have to drag the boxes around to lay out the elements and it's not very pretty, but the concept works. the screenshot that follows shows the techtribes.je context diagram.

thoughts?

all of the c4 model java code is open source and sitting on github . this is only a few hours of work so far and there are no tests, so think of this as a prototype more than anything else at the moment. i really like the simplicity of capturing a software architecture model in code, and using an architecturally-evident coding style allows you to create large chunks of that model automatically. this also opens up the door to some other opportunities such automated build plugins, lightweight documentation tooling, etc. caveats apply with the applicability of this to all software systems, but i'm excited at the possibilities. thoughts?