https://gitlab.com/souliane/structurizr2csv
Convert structurizr DSL or JSON (for describing C4 models) to diagrams.net CSV format
https://gitlab.com/souliane/structurizr2csv
c4 csv diagrams.net dsl json software architecture structurizr
Last synced: 9 months ago
JSON representation
Convert structurizr DSL or JSON (for describing C4 models) to diagrams.net CSV format
- Host: gitlab.com
- URL: https://gitlab.com/souliane/structurizr2csv
- Owner: souliane
- License: bsd-3-clause
- Created: 2022-01-21T18:49:00.015Z (about 4 years ago)
- Default Branch: master
- Last Synced: 2025-04-24T08:50:30.790Z (11 months ago)
- Topics: c4, csv, diagrams.net, dsl, json, software architecture, structurizr
- Stars: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Presentation
This is a Python package to convert [structurizr](https://structurizr.com/)
workspace (\*.dsl or \*.json format) to [diagrams.net](https://www.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](https://structurizr.com/dsl?example=big-bank-plc) 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](https://www.diagrams.net/blog/insert-from-csv).
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](https://github.com/structurizr/cli/issues/62#issuecomment-999623728)
(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](https://github.com/structurizr/dsl/tree/master/examples).
## 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](https://www.docker.com/) 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](https://git-scm.com/) and Python 3.10, then proceed this way:
```
git clone git@gitlab.com: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](https://pypi.org/project/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](https://simonbrown.je/) (C4 model and structurizr) and [Torsten Mosis](https://gitlab.com/systemticks/c4-grammar)
(vscode C4 plugin).