Coding the Documentation with Structurizr

Regardless of whether we like it or not, software documentation is needed, useful, and often even required. I don’t know about you, but I hate going to the company’s Wiki and updating documentation pages every time we change something in the code, database, or the like. Structurizr is one of the tools that I’ve heard about for a long time, and somehow, I’ve been slacking in checking it out. I finally decided to give it a try, and here I am, writing a short introduction so you guys can take advantage of it as well.

About Structurizr

As the tool’s page nicely informs us, “Structurizr is a collection of cloud (software as a service) and on-premises tooling to visualize, document, and explore your software architecture.”

Yes, I know. That’s Marketish and we don’t speak that. Translating it into Programmish, Structurizr is a tool which allows you to document your software architecture using regular Java code and a bit of Markdown/AsciiDoc. (Actually, not only Java, but we don’t care.) Once you do so, you upload this documentation to a web application that renders a nice architecture diagram for you.

Hello, World!

To get yourself started with Structurizr, you will need a free account. You can create one here.

Once you’re logged in, you need to locate the “Create a new workspace button” and click that. When the page reloads, you should see your brand new workspace just below the buttons:

We can finally get into the promised code part. Create a new Maven project and add the following lines to the pom.xml:

    <dependencies>
        <dependency>
            <groupId>com.structurizr</groupId>
            <artifactId>structurizr-core</artifactId>
            <version>1.0.0-RC3</version>
        </dependency>
        <dependency>
            <groupId>com.structurizr</groupId>
            <artifactId>structurizr-annotations</artifactId>
            <version>1.0.0-RC3</version>
        </dependency>
    </dependencies>

    <repositories>
        <repository>
            <id>jcenter</id>
            <url>http://jcenter.bintray.com</url>
        </repository>
    </repositories>

The first dependency contains the core functionality of Structurizr. The second one drags in the annotations that we will later use to automatically generate a components diagram of our “system”. We also need to add the jCenter/Bintray repository, as Structurizr is not available in Maven Central.

Once we have that, let’s create a HelloWorld class like this:

public class HelloWorld {
    private static final String API_KEY = "your-api-key";
    private static final String API_SECRET = "your-api-secret";
    private static final int WORKSPACE_ID = 0; // your workspace ID

    public static void main(String[] args) throws Exception {
        Workspace workspace = new Workspace("My First Workspace", "I'm using this to learn about Structurizr");
        Model model = workspace.getModel();
        ViewSet viewSet = workspace.getViews();

        Person me = model.addPerson("Me", "Myself.");
        SoftwareSystem world = model.addSoftwareSystem("World", "Earth, to be precise.");

        me.uses(world, "Hello, World!");

        viewSet.createSystemContextView(world, "My First View", "Just me and the world.").addAllElements();

        StructurizrClient structurizrClient = new StructurizrClient(API_KEY, API_SECRET);
        structurizrClient.putWorkspace(WORKSPACE_ID, workspace);
    }
}

That may seem like a lot of code but it should be pretty straightforward to understand. We’re creating an object representing the workspace that we’ve just set up online. After that, we’re filling the workspace’s model with a single person (“me”) and a single software system (“world”). Next, we’re specifying that the person uses the system with a description “Hello, World!” and creating a context view. As the last step, we’re uploading the whole workspace using a provided API client.

Remember to replace the constants on the top of the class with your own API key, secret, and workspace ID. You can find this information by clicking the “More details…” button on your newly created workspace. After that, you can run the program.

Once it finishes, you can click on your workspace in the web interface and you should see a diagram like this:

Hello, Annotations!

We’re by no means trying to compete here with the great Structurizr documentation prepared by Simon Brown, but for the sake of getting you interested in the tool, let’s generate another diagram. This time, we’ll use annotation scanning to automate the process a bit. Add the following three classes to our project:

@Component
@UsesSoftwareSystem(name = "Mail Server", description = "Send emails.")
public class MailComponent {
}

@Component
public class TwitterComponent {
    @UsesComponent(description = "Send an email about a Twitter update")
    private MailComponent mailComponent;
}

@Component
public class FacebookComponent {
    @UsesComponent(description = "Send an email about a Facebook update")
    private MailComponent mailComponent;
}

These classes are not the most useful, but that’s not the point. We’re using Structurizr annotations to denote components present in our system and their interdependencies. We can also specify dependencies to external systems as in the MailComponent example.

With this in place, we can configure Structurizr to scan for the annotations. It’s just a minor change of the code we used for the “Hello, World!” example.

public class HelloAnnotations {
    private static final String API_KEY = "your-api-key";
    private static final String API_SECRET = "your-api-secret";
    private static final int WORKSPACE_ID = 0; // your workspace ID

    public static void main(String[] args) throws Exception {
        Workspace workspace = new Workspace("My First Workspace", "I'm using this to learn about Structurizr");
        Model model = workspace.getModel();
        ViewSet viewSet = workspace.getViews();

        model.addSoftwareSystem("Mail Server", "Allows sending emails.");
        SoftwareSystem spammingSystem = model.addSoftwareSystem("Spamming Software System", "Sends you a ton of useless emails.");
        Container spammingApp = spammingSystem.addContainer("Spamming Container", "Sends you a ton of useless emails.", "Java");

        ComponentFinder componentFinder = new ComponentFinder(spammingApp, "com.tidyjava.examples", new StructurizrAnnotationsComponentFinderStrategy());
        componentFinder.findComponents();

        viewSet.createComponentView(spammingApp, "Spamming View", "All the spam in the world.").addAllElements();

        Styles styles = viewSet.getConfiguration().getStyles();
        styles.addElementStyle(Tags.COMPONENT).background("#1168bd").color("#ffffff");

        StructurizrClient structurizrClient = new StructurizrClient(API_KEY, API_SECRET);
        structurizrClient.putWorkspace(WORKSPACE_ID, workspace);
    }
}

This time, we created two software systems in our model – a mail server and a spamming system. The spamming system consists of a single container, being just our Java application. Next, we set up a component finder that does the job of identifying the components and their relationships for us. After that, we create a view and add a bit of style, so that our diagram is less dull than the previous one. And as the last step, we upload the workspace using the client.

Again, remember to replace the constants on the top of the page. This time, you also need to replace “com.tidyjava.examples” with whatever package you’re keeping your components in. After running the program and refreshing the workspace, you should see something like this:

Summary

Structurizr is a really nice tool and I’m glad I finally gave it a try. The idea of generating the documentation straight from the code seems very compelling to me, and I’d be glad to see more tools like this available for developers. If you’re willing to learn more about Structurizr, as I certainly do, you can visit its page and its Java-ish documentation. Happy documenting coding!