Preserve custom element positioning in rendered SVG/PNG

[susliko]

Thanks for the project!

EDIT 06.07.23

Problem

Automatic layout in diagrams of complex architectures can result in suboptimal schemas, which are hard to perceive.
Structurizr Lite allows to adjust all the rectangles and links positions by hand. Changes made by hand are reflected in workspace.json file by paths views.<diagram>Views.[i].elements[j].{x,y}

It would be great to respect these schema adjustments when generating diagrams for a site
(At the moment SVG/PNG images are produced from PlantUML definitions, and PlantUML has no means to support custom positioning of elements)

Solution

I see a few ways to make this possible:

• include structurizr-ui into the site and use it to render diagrams. There are examples on its standalone usage
• implement SVG/PNG rendering in this repository, similarly to structurizr-diagrams.js from structturizr-ui

[susliko]

@dirkgroot I'd be grateful if you shared your thoughts on this 🙏🏻

[susliko]

Hm, looks like this issue duplicates #119

[UBessle]

That's correct. We had the same idea in mind, when we've opened #119 .

@qtzar even started working on such a feature based on the integration of structurizr-ui. You'll find his work in his fork of structurizr-site-generatr on github
https://github.com/qtzar/structurizr-site-generatr/tree/structurizerUI

Unfortunately it looks, like he's abandoned this promising work 3 month ago and now his fork is already 175 commits behind the main trunk of structurizr-site-generatr.

[dirkgroot]

Hi @susliko, thanks for bringing this up. I'm happy to share my thoughts on this. My apologies in advance that this is quite a lengthy response, I hope you bear with me 😄.

Let me start with some background. From the very beginning, the basic premise of this tool has been and still is very simple: As a software architect, I need a way of making my architecture models easily accessible for development teams and other stakeholders. This simple premise, and the lack of tooling available at the time motivated me to create this tool.

Because my available time for maintaining this tool is limited, I needed this tool to be as simple as possible. That's why I designed this tool to heavily depend on the Structurizr libraries that Simon Brown has made available. I was, and still am, fully aware that there's a trade-off to be made. This design decision is a trade-off between the flexibility and the maintainability of this tool. The tool is not flexible when it comes to how diagrams are generated from Structurizr views. It is, however, easy to maintain with a minimal time investment.

The downside of this is that there's no way of customizing the layout of diagrams, except for some options available in structurizr-export. I'm happy to deal with this downside by following Simon Brown's advice of creating "multiple smaller diagrams showing a subset of the overall picture".

For the systems and system landscapes I'm responsible for and the stakeholders I'm doing this for, this approach works really well. The largest model I'm maintaining is for a system landscape consisting of 30-40 software systems, not including the systems outside the enterprise boundary.

We're using multiple ways of partitioning larger diagrams into smaller ones. I think that similar techniques could be used to partition large models into smaller ones. Some examples include:

• Based on relationship type. For example: REST, SOAP, message queue, etc.
• Based on functionality. For example: Boarding, screening, self service, etc.
• Relationships with "internal" systems versus relationships with "external" systems.

If you have a limited number of complex diagrams that need customization of the layout, you could also use the Structurizr UI to create those diagrams, export them to SVG and include them in the generated site as a static asset. See the example site for an example.

So, the conclusion here is that, while I've never been really explicit about this, this tool is in fact an opinionated take on publishing C4 architecture models. The opinions reflected in this tool are in short:

• Architecture models should be limited in scale and scope to be comprehensible
• Diagrams should be small and focused to be understandable

I fully respect and acknowledge that architects who work in different environments than mine might have a different opinion on this. However, this tool was never meant to be a one-size-fits-all for every possible situation. It is designed to work well for models that are small-ish in scope and scale.

While this may not be the answer you're looking for, I hope this lengthy response helps you understand why I'm very reluctant in making changes to the tool that are meant to make it scale beyond the scale it was designed for.

[susliko]

@dirkgroot Thank you for such a detailed answer!
I'm totally with you on the criteria of good diagrams, especially on

Diagrams should be small and focused to be understandable

This very point made me seek for a way to adjust those stretched auto-generated diagrams while retaining a crucial, imo, feature of having links between diagrams (that c4 "map-like" concept, which is always presented by Simon) 😄

To clarify, if embedding the Structurizr-UI viewer only requires updating its version occasionally and does not significantly increase the maintenance burden, would you be open to considering it?

[qtzar]

While I did do a POC of adding structurizr-ui to render the diagrams instead of PUML it was exactly that, just a POC. I decided not to continue with it for a couple of reasons.

1. The structurizr-ui javascript components had to be manually copied in making it impossible to have automated processes that would keep them updated when their source project was updated.

2. the structure-ui needs a workspace.json file which I was generating on the fly from the dsl file. You still need to use auto layout because the dsl does not have options for x/y positioning. So you issue with overlapping lines would not be resolved immediately.

3. The SVGs that are generated by the structurizr-ui were hard to position and size correctly on screen, It looked messy.

4. I couldn't figure out a way to generate links so that when you clicked a software system it would bring to to that systems contact diagram or deeper in to the container or component diagrams the way the site-generatr does it today.

You are totally welcome to take up the work and dedicate some time to resolving the main blockers that I had but I feel that site-generatr as it works today is the better and easier option.

[dirkgroot]

I'm converting this to a discussion, because I think that is better suited for this particular subject.

[maciejbanakiewicz93]

We would also appreciate this option, our architecture consists of 20+ software systems and auto-layout simply doesn't work, the outcome is completely unreadable. I know that our architecture should be simpler but it is what it is and we would like to use the full power of the tool, especially that for most of the diagrams we already spent some effort rearranging them.

@dries007

[simonbrowndotje]

If you don't need docs and adrs, take a look at Structurizr Mini ... it's another static site generator, but uses the Structurizr diagram renderer instead of PlantUML.