structurizr2csv

Presentation

This is a Python package to convert structurizr workspace (*.dsl or *.json format) to diagrams.net (*.csv format). You will get in diagrams.net, and using its built-in elements, some C4 diagrams that look similar to what structurizr generates (see here for examples).

The CSV format for importing in diagrams.net is not well documented, and it looks strange indeed, because CSV is (of course) not made to describe such things as architectural diagrams. A lot of information has to be passed in comments. Anyway, this is currently the best/easiest way to achieve the conversion. The output CSV that you will get from this program can be inserted following this.

It is always good to manually review because you might have to adjust some things, for example to add some waypoints to the connectors that are crossing some boxes (I prefer to export straight connectors, because the automatically set waypoints are not ideally placed anyway).

DSL to CSV

When passing a *.dsl file, the program will automatically use structurizr/cli in background to convert it to JSON. Since diagrams.net autolayout didn't give acceptable results, it will also apply GraphViz autolayout. The JSON will then be converted to CSV.

JSON to CSV

You can also directly pass a *.json file. In this case, structurizr/cli won't be needed, but it is expected that all the elements' positions are already fixed in your JSON. If it is not the case, no worries - just follow this (this is actually what we do in the background when processing a DSL).

Results

Those are examples of results that you will get in diagrams.net. The source workspaces come from structurizr's DSL repository, you can find them here.

TODO

It is still in beta and it doesn't support the full DSL grammar. For instance, dynamic diagrams are handled like "normal" ones, deployment diagrams are completely ignored, and all the styling information is also ignored. Instead, we use the "default" C4 styles and colors.

There are also some issues when it comes to identify what elements are internal or external, thus you will notice that the boxes' colors do not always match the diagrams that are generated by structurizr.

Feel free to report issues using the gitlab feature. Please provide as much details as possible and attach your DSL or JSON file (if the content can be publicly shared).

Installation

Option 1: Docker

Install Docker and run this to print the usage:

docker run -it -v //var/run/docker.sock:/var/run/docker.sock -v `pwd`:/structurizr2csv  souliane/structurizr2csv:latest structurizr2csv --help

Note: the docket socket needs to be exposed to the container for running a structurizr/cli container when we are inside the structurizr2dsl container. This is faking "docker in docker" (dind) and it is a recommended approach. If you pass an already existing *.json file instead of a *.dsl one, you won't need this.

Option 2: Git

Install git and Python 3.10, then proceed this way:

git clone [e-mail]:souliane/structurizr2csv.git
cd structurizr2csv
python3 -m pip install -r requirements.txt
PYTHONPATH=src ./src/structurizr2csv/convert.py --help

Option 3: Pip

Install Python 3.10 and pip, then do:

python3 -m pip install structurizr2csv
structurizr2csv --help

Usage

usage: structurizr2csv [-h] [-a FILETYPE] [-o OUTPUT_PATH] input_path

Convert structurizr DSL or JSON (for describing C4 models) to diagrams.net CSV format

positional arguments:
  input_path            input workspace file, either *.dsl or *.json. If you pass a *.json file, it is expected to define
                        the positions of each elements. If you pass a *.dsl file, it will be automatically transformed to
                        JSON and GraphViz auto layout will be applied (this is done with the official Docker image for
                        structurizr/cli, so you need a running Docker system for this to work with a *.dsl file).
                        When using the '-a {dsl,json}' option, this must be the path to a directory.

options:
  -h, --help            show this help message and exit
  -a {dsl,json}, --all {dsl,json}
                        process all the files in 'input_path' that are of the given type
  -o OUTPUT_PATH, --output OUTPUT_PATH
                        output base directory for the CSV files (workspace basename will be appended)

Testing

Current testing is minimal and it just checks that the produced *.csv files match some "golden files" - those are the output that I have "manually" checked while developing.

Tests can be run directly with pytest using make tests, or via tox with make tox (this creates in the background a dedicated environment, install the package and its dependency, and then run the tests).

Acknowledgements

Many thanks to Simon Brown (C4 model and structurizr) and Torsten Mosis (vscode C4 plugin).