Visualising ADRs
Tags: architecture, productivity
Published: 2021-07-09 12:14:52

---
title: Visualising ADRs
published: true
description: 
tags: #architecture #productivity
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7j4rrd8hynp9w8mv7ydt.png
---

I'm a big fan of [architecture decision records](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions) (ADRs) - a collection of short text files, stored in version control, that provides a way to document the significant decisions made before/during the development of a software product. I highly recommend that all teams adopt this lightweight practice, and they are a core part of my [minimal approach to software architecture documentation](https://dev.to/simonbrown/a-minimal-approach-to-software-architecture-documentation-4k6k). For tooling, I really like Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools) command line utility for managing ADRs. 

Do team members ever look at that folder of ADRs though? And how easy is it to search for information related to a single decision, or perhaps even a chain of decisions? Something we could really do a better job of is visualising those decisions, making them easy to find and read.

Structurizr has supported publishing ADRs for a while now, and I've just added (an initial version of) a feature that visualises ADRs as a force-directed graph, showing the decisions and the connections between those decisions where they've been superseded. Here's a screenshot showing the decisions related to how the Structurizr cloud service has moved from Rackspace to Pivotal Web Services, and then onwards to Amazon Web Services.

![A force-directed graph of decisions](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/aw2pdn44ct6l38iu7ih6.png)

If you have a folder of ADRs created using Nat's tool, you can get this visualisation for free with [Structurizr Lite](https://structurizr.com/help/lite) in under 5 minutes.

## 1. Create a workspace.dsl file

Create a file named `workspace.dsl` next to your folder of ADRs.

![File structure](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vsgesop7solrhw1ssf53.png)

Add the following content to that file.

```
workspace {

  !adrs decisions

}
```

This says, "create a workspace, and load the ADRs from the `decisions` sub-directory".

## 2. Start Structurizr Lite

Assuming that you have Docker installed, you can now start Structurizr Lite with the following commands:

```
docker pull structurizr/lite
docker run -it --rm -p 8080:8080 -v PATH:/usr/local/structurizr structurizr/lite
```

Be sure to replace `PATH` with the full path to the directory containing your `workspace.dsl` file.

### 3. Open Structurizr Lite

Open the workspace in a web browser by heading to [http://localhost:8080](http://localhost:8080) and you should see your decisions.

![A summary of decisions](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lupkwk8fl8dptkrg7wc8.png)

You can now click through the decisions, and press the `Space` key to open the quick navigation feature. Click the little graph button underneath the heading, and the visualisation will open.

![A force-directed graph of decisions](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3fcdmmx21s5d4c3mgkea.png)

Over time, the graph will start to change to reflect how decisions have been superseded, deprecated, etc.

## Summary

As I said at the start, I'm a big fan of ADRs. Whether you're using Structurizr or building your own tooling, we can do better than keeping them hidden away in a folder.