{"id":29206393,"url":"https://gitlab.com/souliane/structurizr2csv","last_synced_at":"2025-07-02T18:02:19.343Z","repository":{"id":57471959,"uuid":"33031074","full_name":"souliane/structurizr2csv","owner":"souliane","description":"Convert structurizr DSL or JSON (for describing C4 models) to diagrams.net CSV format","archived":false,"fork":false,"pushed_at":null,"size":null,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":null,"default_branch":"master","last_synced_at":"2025-04-24T08:50:30.790Z","etag":null,"topics":["c4","csv","diagrams.net","dsl","json","software architecture","structurizr"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":null,"metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-21T18:49:00.015Z","updated_at":"2022-02-09T09:15:15.077Z","dependencies_parsed_at":"2022-08-30T13:52:17.062Z","dependency_job_id":null,"html_url":"https://gitlab.com/souliane/structurizr2csv","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:gitlab/souliane/structurizr2csv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/souliane%2Fstructurizr2csv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/souliane%2Fstructurizr2csv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/souliane%2Fstructurizr2csv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/souliane%2Fstructurizr2csv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners/souliane","download_url":"https://gitlab.com/souliane/structurizr2csv/-/archive/master/structurizr2csv-master.zip","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories/souliane%2Fstructurizr2csv/sbom","host":{"name":"gitlab.com","url":"https://gitlab.com","kind":"gitlab","repositories_count":4518950,"owners_count":6979,"icon_url":"https://github.com/gitlab.png","version":null,"created_at":"2022-05-30T11:31:42.605Z","updated_at":"2024-07-18T11:24:13.055Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.com/owners"}},"keywords":["c4","csv","diagrams.net","dsl","json","software architecture","structurizr"],"created_at":"2025-07-02T18:01:14.937Z","updated_at":"2025-07-02T18:02:19.312Z","avatar_url":null,"language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"## Presentation\n\nThis is a Python package to convert [structurizr](https://structurizr.com/)\nworkspace (\\*.dsl or \\*.json format) to [diagrams.net](https://www.diagrams.net/)\n(\\*.csv format). You will get in diagrams.net, and using its built-in elements,\nsome C4 diagrams that look similar to what structurizr generates (see\n[here](https://structurizr.com/dsl?example=big-bank-plc) for examples).\n\nThe CSV format for importing in diagrams.net is not well documented, and it looks\nstrange indeed, because CSV is (of course) not made to describe such things as\narchitectural diagrams. A lot of information has to be passed in comments.\nAnyway, this is currently the best/easiest way to achieve the conversion.\nThe output CSV that you will get from this program can be inserted following\n[this](https://www.diagrams.net/blog/insert-from-csv).\n\nIt is always good to manually review because you might have to adjust some\nthings, for example to add some waypoints to the connectors that are crossing\nsome boxes (I prefer to export straight connectors, because the automatically set\nwaypoints are not ideally placed anyway).\n\n### DSL to CSV\n\nWhen passing a \\*.dsl file, the program will automatically use structurizr/cli\nin background to convert it to JSON. Since diagrams.net autolayout didn't give\nacceptable results, it will also apply GraphViz autolayout. The JSON will then\nbe converted to CSV.\n\n### JSON to CSV\n\nYou can also directly pass a \\*.json file. In this case, structurizr/cli won't\nbe needed, but it is expected that all the elements' positions are already fixed\nin your JSON. If it is not the case, no worries - just follow\n [this](https://github.com/structurizr/cli/issues/62#issuecomment-999623728)\n (this is actually what we do in the background when processing a DSL).\n\n## Results\n\nThose are examples of results that you will get in diagrams.net.\nThe source workspaces come from structurizr's DSL repository, you can find them\n[here](https://github.com/structurizr/dsl/tree/master/examples).\n\n\n![](screenshots/big-bank-plc.component.png)\n![](screenshots/big-bank-plc.system-landscape.png)\n![](screenshots/groups.container.png)\n\n## TODO\n\nIt is still in beta and it doesn't support the full DSL grammar. For instance,\ndynamic diagrams are handled like \"normal\" ones, deployment diagrams are\ncompletely ignored, and all the styling information is also ignored.\nInstead, we use the \"default\" C4 styles and colors.\n\nThere are also some issues when it comes to identify what elements are internal\nor external, thus you will notice that the boxes' colors do not always match\nthe diagrams that are generated by structurizr.\n\nFeel free to report issues using the gitlab feature. Please provide as much\ndetails as possible and attach your DSL or JSON file (if the content can be\npublicly shared).\n\n## Installation\n\n### Option 1: Docker\nInstall [Docker](https://www.docker.com/) and run this to print the usage:\n```\ndocker run -it -v //var/run/docker.sock:/var/run/docker.sock -v `pwd`:/structurizr2csv  souliane/structurizr2csv:latest structurizr2csv --help\n```\nNote: the docket socket needs to be exposed to the container for running a\nstructurizr/cli container when we are inside the structurizr2dsl container.\nThis is faking \"docker in docker\" (dind) and it is a recommended approach.\nIf you pass an already existing *.json file instead of a *.dsl one, you won't need this.\n\n### Option 2: Git\nInstall [git](https://git-scm.com/) and Python 3.10, then proceed this way:\n```\ngit clone git@gitlab.com:souliane/structurizr2csv.git\ncd structurizr2csv\npython3 -m pip install -r requirements.txt\nPYTHONPATH=src ./src/structurizr2csv/convert.py --help\n```\n\n### Option 3: Pip\nInstall Python 3.10 and [pip](https://pypi.org/project/pip/), then do:\n```\npython3 -m pip install structurizr2csv\nstructurizr2csv --help\n```\n\n## Usage\n\n```\nusage: structurizr2csv [-h] [-a FILETYPE] [-o OUTPUT_PATH] input_path\n\nConvert structurizr DSL or JSON (for describing C4 models) to diagrams.net CSV format\n\npositional arguments:\n  input_path            input workspace file, either *.dsl or *.json. If you pass a *.json file, it is expected to define\n                        the positions of each elements. If you pass a *.dsl file, it will be automatically transformed to\n                        JSON and GraphViz auto layout will be applied (this is done with the official Docker image for\n                        structurizr/cli, so you need a running Docker system for this to work with a *.dsl file).\n                        When using the '-a {dsl,json}' option, this must be the path to a directory.\n\noptions:\n  -h, --help            show this help message and exit\n  -a {dsl,json}, --all {dsl,json}\n                        process all the files in 'input_path' that are of the given type\n  -o OUTPUT_PATH, --output OUTPUT_PATH\n                        output base directory for the CSV files (workspace basename will be appended)\n```\n\n## Testing\n\nCurrent testing is minimal and it just checks that the produced *.csv files match some\n\"golden files\" - those are the output that I have \"manually\" checked while developing.\n\nTests can be run directly with pytest using `make tests`, or via tox with `make tox`\n(this creates in the background a dedicated environment, install the package and\nits dependency, and then run the tests).\n\n## Acknowledgements\n\nMany thanks to [Simon Brown](https://simonbrown.je/) (C4 model and structurizr) and [Torsten Mosis](https://gitlab.com/systemticks/c4-grammar)\n(vscode C4 plugin).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2Fsouliane%2Fstructurizr2csv","html_url":"https://awesome.ecosyste.ms/projects/gitlab.com%2Fsouliane%2Fstructurizr2csv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/gitlab.com%2Fsouliane%2Fstructurizr2csv/lists"}