[Tool] Tools for Architecture Diagrams

[chenchen1987]

The Spiders team have been exploring ways to make ever green architectural diagrams of the data catalog. As a result, Lucidchart has been put on the table.

Why is maintaining an ever green architectural diagram important

• Per description in #42, the team is investing time effort into adopting DDD pattern into SQL Data Catalog, one of the foreseen difficulties that we need to overcome is adopting its Ubiquitous language
• DDD is something the team hasn't had previous experience with in the past
• There is a strong emphasis on carefully designing the domain layer, namely the aggregate's consistency boundaries

The belief is that having visualised architectural diagrams would relief us the above pains we will be experiencing.

Benefits of using Lucidchart

Some of the functionalities we could take advantages of:

• Individuals in the team are able to create/edit the diagrams, which can be shared across the team
• Make responsive comments on individual components on the diagrams for better communication
• Ability to zoom into lower level architectural diagrams, by adding hot spots on particular components on the higher level ones

[fffej]

Excellent - I guess @fredjeronimo might chime in here with whatever tool the Prompt team used to produce the C4 diagrams for Prompt?

[adrianbanks]

There's also Strucurizr (made by Simon Brown who came up with the C4 model) which enables you to create architecture diagrams from code with some hope of keeping them up to date more easily.

[nyctef]

I think in an ideal solution, the source of truth for the diagrams would be source-controlled next to the relevant code so we have a chance of enforcing that they change together.

I don't know if lucidchart lets us do something like that - it might just need to export PNGs out to the repo (which can be replaced with PNGs from another tool if necessary). The code definitions from Structurizr look promising, but the syntax isn't the simplest thing in the world - it's not too complicated but it might turn off people from editing diagrams.

I think an ideal solution would look something a bit like https://www.websequencediagrams.com/ , but for any diagram type :/

[fredjeronimo]

We are currently using draw.io for generating our C4 models in Prompt. This was mostly picked as an easy to use and setup solution for what is mostly at present a digital representation of a low tech (post-its and whiteboard) team brainstorm exercise from our new mob architecture sessions (we only just started the process this week).

To be perfectly honest, I'm not too worried about which tool we end up picking to achieve architectural diagrams (as long as we can create custom shapes and it's low maintenance) as I'm more concerned about integrations with other environments, most notably Confluence. At my previous job, we used Gliffy and one of its main attractives is that it had a Confluence plugin that hooked directly in the webpages. Each diagram had a full history and you could even edit them separately from the page contents themselves.

Apparently draw.io also has a Confluence plugin but I've never tried it. Currently we have a painful (and error prone process) of doing in draw.io, exporting to png/xml and then importing it in Confluence that I want to move away from...

[fredjeronimo]

I would also like a solution that can be used for both architectural purposes and otherwise. In that regard, I'm a bit wary of a solution that only attaches to source code as a lot of diagrams we do are not coupled with code at all (e.g. diagram with flow for the support process).

Even for architectural diagrams, code's relevance depends on the scope of the diagram being done. For example, C4's level 1 (and one could argue even level 2) are high level overviews that are unlikely to change alongside the code.

And we should think of our target audience as well. Some diagrams will be aimed at non-technical users and they should be easily accessible and discoverable.

[fffej]

I'd like to make sure the Radar captures the status quo and things we are trialling now (or will commit to) and things we should adopt.

Seems that in Explore we've got both draw.io and LucidChart. These both look like drawing tools (rather than architecture <-> code things). @fredjeronimo and @chenchen1987 Do you think we can get opinionated enough to choose one now?

@adrianbanks and @nyctef have highlighted some code -> diagram tools. Are these interesting enough to commit to exploring, or something of interest for some future time?

[chenchen1987]

Speaking on behalf of the spiders team, we are opinionated enough to choose one now yet. And I've personally not explored extensively of the other tools mentioned in this thread.

[fffej]

In that case, I'd suggest

Explore

• draw.io (and some reasons why)
• LucidChart (and some reasons why)

Next iteration we'll try to understand the pros/cons of both and make a decision about whether converging on a single tool is a good thing (or not!).

Anyone fancy making a PR? 🙏

[tugberkugurlu]

There's also Strucurizr (made by Simon Brown who came up with the C4 model) which enables you to create architecture diagrams from code with some hope of keeping them up to date more easily.

I have tried this several times but I find this very lacking to express the thoughts and collaborate on these. Lucidchart seems to tick all the collabration boxes for us, for example. We looked whether Visio was on OneDrive but it doesn't seem to be there and Lucidchart seemed to be the closest to having Visio on OneDrive :)

[fredjeronimo]

I'm happy to trial out any for our work in Prompt (happy to discuss with other teams -- perhaps a joint test session might be worthwhile to conduct?). My only true request is that we package a Confluence plugin with whatever choice we pick in the end. Like Gliffy, it seems both draw.io (here) and LucidChart (here) have at least one integration with Confluence (more may exist).