In this short tutorial we'll look at how to create a simple software architecture model using the Structurizr for Java library, including:

  • Cloning the java-starter GitHub repository.
  • Uploading a workspace.
  • Making some changes to the workspace.

10 minutes


  • You have a Structurizr account (see the Getting started with Structurizr tutorial).
  • You have a working Java 8 development environment.
  • You have the Git command line tools installed.

1. Clone the java-starter repository from GitHub

The java-starter GitHub repository provides a simple starting point for your Structurizr programs. It also includes a Gradle build file and the required dependencies to build and run the program. Open a command prompt on your computer and clone the repository using the following command:

git clone

Change into the java-starter directory just created and run the Gradle build. For example:

cd java-starter
./gradlew build

If everything works, you should see BUILD SUCCESSFUL.

2. Upload a workspace

The java-starter repository includes a simple Java program in a class named Structurizr. It creates a local workspace containing:

  • A software architecture model describing a person and a software system.
  • A System Context diagram with some element styling.

The idea is that we create a local workspace using Java code and upload it to Structurizr via the web API. In order to do this, we need to change the program to tell it which of our online workspaces will be used to store the workspace. If you sign in to Structurizr, you'll be presented with the workspaces that you have access to.

Your dashboard

At the bottom of the summary for every workspace is the following information:

  • The workspace ID.
  • The workspace API key.
  • The workspace API secret.

Workspace metadata

This information needs to be specified in the Java program. Open the src/main/java/com/mycompany/mysystem/ file and modify the constants at the top of the class definition to match the values on your dashboard. For example:

private static final String API_KEY = "21da568a-c283-45dd-b366-a4d26012684b";
private static final String API_SECRET = "8768f611-0c5c-4d81-b0fa-5e4191e91a6c";
private static final long WORKSPACE_ID = 13641;

After saving the file, build and run the program at the command prompt. For example:

./gradlew run

If everything works, you should see output like the following:

Jun 18, 2016 3:41:09 PM com.structurizr.api.StructurizrClient mergeWorkspace
INFO: Merging workspace with ID 13641
Jun 18, 2016 3:41:09 PM com.structurizr.api.StructurizrClient getWorkspace
INFO: Getting workspace with ID 13641
Jun 18, 2016 3:41:12 PM com.structurizr.api.StructurizrClient putWorkspace
INFO: Putting workspace with ID 13641
Jun 18, 2016 3:41:13 PM com.structurizr.api.StructurizrClient putWorkspace
INFO: {"message":"OK"}


If you refresh your dashboard, you should notice that the name of the workspace has changed to "My model", which is the value specified in the Java program.

Your dashboard

If you click "My model" to open the workspace in the diagram editor, there should be a single System Context diagram containing two elements (a person and a software system). As the Java program didn't specify any information about the layout of the elements on the diagram, the elements will be placed randomly on the diagram canvas.

Opening a workspace

As we saw in the Getting started with Structurizr tutorial, you can move the boxes around and save the diagram layout by clicking the button.

Opening a workspace

3. Make some changes

Let's make a small change to the Java program and upload the workspace again. For example, let's change the colour of people to a bright red.


And re-run the Java program.

./gradlew run

If you open the workspace in the diagram editor, you will notice that the diagram layout has been retained. This is because the putWorkspace() method on the StructurizrClient Java class will try to copy diagram layout information from the online workspace into the local workspace, before uploading it to Structurizr. See API client for more information.

Opening a workspace

4. Next steps

With the Structurizr program working, you can now make more modifications such as:

  • Modify the details of the existing elements and relationships in the software architecture model.
  • Add more people and software systems to the model.
  • Change the styling of the diagram.
  • Add containers and components to the model.
  • Add more diagrams.

See the documentation and examples in the Structurizr for Java repository on GitHub for more information.