Structurizr: System Context Diagram as Code

as i said in resolving the conflict between software architecture and code , my focus for this year is representing a software architecture model as code. in simple sketches for diagramming your software architecture , i showed an example system context diagram for my techtribes.je website.

it's a simple diagram that shows techtribes.je in the middle, surrounded by the key types of users and system dependencies. it's your typical "big picture" view. this diagram was created using omnigraffle (think microsoft visio for mac os x) and it's exactly that - a static diagram that needs to be manually kept up to date. instead, wouldn't it be great if this diagram was based upon a model that we could better version control, collaborate on and visualize? if you're not sure what i mean by a "model", take a look at models, sketches and everything in between .

this is basically what the aim of structurizr is. it's a way to describe a software architecture model as code, and then visualize it in a simple way. the structurizr java library is available on github and you can download a prebuilt binary . just as a warning, this is very much a work in progress and so don't be surprised if things change! here's some java code to recreate the techtribes.je system context diagram.

package com.structurizr.example;
 
import com.structurizr.io.json.jsonwriter;
import com.structurizr.model.location;
import com.structurizr.model.model;
import com.structurizr.model.person;
import com.structurizr.model.softwaresystem;
import com.structurizr.view.systemcontextview;
import com.structurizr.view.viewset;
 
import java.io.stringwriter;
 
/**
* this is a model of the system context for the techtribes.je system,
* the code for which can be found at https://github.com/techtribesje/techtribesje
*/
public class techtribessystemcontext {
 
public static void main(string[] args) throws exception {
// create a model and the software system we want to describe
model model = new model("techtribes.je", "this is a model of the system context for the techtribes.je system, the code for which can be found at https://github.com/techtribesje/techtribesje");
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");
 
// create the various types of people (roles) that use the software system
person anonymoususer = model.addperson(location.external, "anonymous user", "anybody on the web.");
anonymoususer.uses(techtribes, "view people, tribes (businesses, communities and interest groups), content, events, jobs, etc from the local tech, digital and it sector.");
 
person authenticateduser = model.addperson(location.external, "aggregated user", "a user or business with content that is aggregated into the website.");
authenticateduser.uses(techtribes, "manage user profile and tribe membership.");
 
person adminuser = model.addperson(location.external, "administration user", "a system administration user.");
adminuser.uses(techtribes, "add people, add tribes and manage tribe membership.");
 
// create the various software systems that techtribes.je has a dependency on
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.");
 
// now create the system context view based upon the model
viewset viewset = new viewset(model);
systemcontextview contextview = viewset.createcontextview(techtribes);
contextview.addallsoftwaresystems();
contextview.addallpeople();
 
// and output the model and view to json (so that we can render it using structurizr.com)
jsonwriter jsonwriter = new jsonwriter(true);
stringwriter stringwriter = new stringwriter();
jsonwriter.write(viewset, stringwriter);
system.out.println(stringwriter.tostring());
}
 
} 

executing this code creates this json , which you can then copy and paste into the try it page of structurizr. the result (if you move the boxes around) is something like this.

don't worry, there will eventually be an api for uploading software architecture models and the diagrams will get some styling, but it proves the concept. what we have then is an api that implements the various levels in my c4 software architecture model, with a simple browser-based rendering tool. hopefully that's a nice simple introduction of how to represent a software architecture model as code, and gives you a flavour for the sort of direction i'm taking it. having the software architecture as code provides some interesting opportunities that you don't get with static diagrams from visio, etc and the ability to keep the models up to date automatically by scanning the codebase is what i find particularly exciting. if you have any thoughts on this, please do drop me a note.