As software developers, we often struggle with trying to visualize and communicate architectural flows with fellow developers, as well as struggle with wrapping our heads around architecture of existing software systems at our workplaces, especially if they don't have a good model visualization to refer to. We have found the C4 model and Structurizr to be very helpful with these issues. We wanted to take it a step further and create a way to model architectures in a way that is easy to access, understand, and collaborate on.

What it does

Github link

This application provides and integration that reads data from a board, and uses it to create software architecture models in a Structurizr workspace. Structurizr can then use these models to generate views that show the architectural layout of your software systems with different levels of granularity. These views are interactive, animatable and embeddable. You can also further edit these views using the Structurizr web UI.

The application comes with a workspace template that is set up with all the columns that are required for this integration to work, and the 3 recipes that are core to this integration. You can define your software model according to the C4 model right inside this board using groups and items. The integration recipes will trigger whenever there is an update to the board, and immediately update the model on your Structurizr workspace.

How we built it

This integration is built in 3 parts -

  • We developer platform to create 2 recipes that are triggered whenever an item is created or updated on a board. These recipes activate a custom action, which sends an HTTP request to our backend server with the boardId of the board which triggered this event.
  • The backend server then uses the GraphQL API to fetch board data based on the received boardId. This data includes all the groups, items and columns in the board.
  • The board data is then transformed into a model that can be accepted by the Structurizr API (based on the C4 model). Structurizr API then accepts this data and uses it to generate visualizations.

Challenges we ran into

The big hurdle in the inception of the project was to understand the workflow and APIs for both and Structurizr. Testing different GraphQL queries that satisfy the need for this integration was another challenge, extracting data of subitem, tags, etc. through their pulseIds and finally grouping them according to the model was another challenge that required a great deal of data manipulation.

Then there the question of how to link different architectures and we decided to use the dependency column and use those data to show the relationship between the model elements.

Preprocessing data we got from to match Structurizr API was another challenge that involved data tweaking and using novel methods to eliminate edge cases.

Accomplishments that we're proud of

We are very proud of creating an application that solves so many issues that developers around the world (including us) face frequently. We are also very happy that we did it using multiple technologies that we have very limited experience working with (, Structurizr API, GraphQL).

What we learned

  • We learned a lot about the low-code and no-code developer platform provided by and how it can be used to customize WorkOS to suit business needs.
  • We learned a lot about Structurizr and its API that we didn't know before. We are now a lot more confident in our ability to create architecture models using Structurizr.
  • This was our first time using GraphQL for any serious project. We are a lot more comfortable working with GraphQL APIs now.

What's next for Structurizr Integration

This is currently a one-way integration, i.e., it takes data from your board and generates a Structurizr model. We would like to upgrade this to a two-way integration, such that any changes you make to your model using Structurizr's UI or API is reflected in your board. This is difficult to do since Structurizr does not provide us with webhooks (or something similar), so we have to poll it's API for changes.

Structurizr also allows for customization of shapes and colors of the individual elements of their diagrams. We would like to enable users to define the shape and color of the elements using columns in the boards. Unfortunately, since we are using a third-party Structurizr SDK instead of directly making requests against their API, we are limited by the features provided by the SDK. However, we are hopeful that element customization feature will be added to the SDK very soon, and then we will be able to provide that feature to our users.

Built With

Share this project: