Skip to content

Latest commit

 

History

History
334 lines (297 loc) · 17.1 KB

tooling.md

File metadata and controls

334 lines (297 loc) · 17.1 KB
Raw
layout title nav_order permalink
default
Tooling
6
/tooling

Tooling

For design sessions, you might find a whiteboard or flip chart paper better for collaboration, and iterating quickly. For long-lived documentation, there are a number of tools can help create software architecture diagrams based upon the C4 model. Here are some of the questions you should ask yourself when looking at tooling:

  • Who are the diagram authors, and how technical are they?
  • Who is the diagram audience, and how will they access the diagrams/documentation?
  • Diagramming vs modelling?
  • A "drag and drop" UI vs "diagrams as code"?
  • Data stored in git next to your source code vs stored in the tool/cloud service?
  • Easy to diff source to use in pull requests?
  • Closed vs open data format?
  • Interactive vs static diagrams?
  • Free vs paid?
  • Closed vs open source?
  • Cloud vs self-hosted?
  • Short-lived vs long-lived documentation?
  • Team only diagramming vs enterprise-wide modelling?

Diagramming vs modelling

A short note on diagramming vs modelling, since this is the biggest decision you'll need to make regarding tooling. The C4 model can be used irrespective of whether you use a diagramming or modelling tool, but there are some interesting opportunities when you progress from diagramming to modelling.

Diagramming

As an industry, we've tended to prefer diagramming (e.g. Visio, draw.io, Lucidchart, PlantUML, Mermaid, etc) over modelling (e.g. Sparx EA, Archi, IcePanel, Structurizr, etc), primarily because the barrier to entry is relatively low, and it's seen as a much simpler task. But there are a number of major problems with using diagramming tools for software architecture diagrams:

  1. The domain language of diagramming tools is "boxes and lines", which means:
    • They can't provide any assistance or validation of your diagrams.
    • You can't query the diagrams (e.g. "show me all dependencies of component X").
  2. Reusing diagram elements is done via copy-paste - if you rename a box, you need to rename it across every diagram where it appears.
  3. Many diagramming tools have data formats that are hard to diff, making them tricky to use in conjunction with pull requests, for example.

Modelling

With a modelling tool, you're building up a non-visual model of your software architecture (a single definition of all elements and the relationships between them), and then creating different views (that become diagrams) on top of that model. This requires a little more rigour, but the problems can be resolved - modelling tools can understand the semantics of what you're trying to do, provide additional assistance, and renaming elements/relationships is easy.

Software architecture models are essentially just directed graphs, consisting of nodes and edges, with diagrams showing a subset of the graph. Once you see the separation of the model (which is just structured data) and the views (which are rendered as diagrams), you quickly see there are a number of interesting opportunities that arise:

  • Creating alternative visualisations to help understand large and complicated architecture models - see Does the C4 model scale? for more.
  • Querying the model.
  • Exporting the model to other tools.
  • etc

A model is just data! And we, as software developers, have an endless supply of tools to visualise and manipulate that data.

Options

Here's a collection of tooling that provides some degree of specific support for the C4 model.

<script type="application/javascript" src="https://code.jquery.com/jquery-3.7.1.slim.min.js"></script> <style> .toolingOptionFilter { margin: 10px 20px 20px 10px; display: inline-block; } .toolingOption { font-size: 16px; display: inline-block; margin: 10px; border: solid 1px #1168BD; padding: 5px 10px 5px 10px; border-radius: 5px; } .toolingOption:hover { background: #1168BD; color: #ffffff; } .toolingOption:hover a { color: #ffffff; } .toolingOption a { text-decoration: none; } .toolingOption a:hover { background: #1168BD; color: #ffffff; text-decoration: none; } .centered { text-align: center; } .faded { opacity: 0.2; } .small { font-size: 13px; } .smaller { font-size: 11px; } </style>

Supported diagram types

Static diagrams
(e.g. system context, container, and component diagrams)
<div class="toolingOptionFilter">
    <label><input id="toolingDynamicDiagramsFilter" type="checkbox"> Dynamic diagrams</label>
    <div class="smaller">(e.g. collaboration or sequence diagrams)</div>
</div>

<div class="toolingOptionFilter">
    <label><input id="toolingDeploymentDiagramsFilter" type="checkbox"> Deployment diagrams</label>
    <div class="smaller">(e.g. diagrams showing deployment and infrastructure concerns)</div>
</div>

Diagramming vs modelling

Diagramming tool
(boxes and arrows are reused via copy and paste, no assistance, no validation rules, etc)
<div class="toolingOptionFilter">
    <label><input id="toolingModelBasedFilter" name="diagramVsModel" type="radio" checked="checked"> Reuse elements across multiple diagrams</label>
    <div class="smaller">(i.e. a modelling tool - to keep multiple diagrams in sync automatically when you rename elements)</div>
    <div style="margin-top: 10px">
    <span class="smaller" style="font-weight: normal; background: #02b621; color: #ffffff; padding: 5px; margin-top: 10px;">Recommended</span>
    </div>
</div>

Authoring

Graphical user interface
(drag and drop modelling UI)
<div class="toolingOptionFilter">
    <label><input id="toolingAsCodeFilter" name="authoring" type="radio" checked="checked"> Diagrams and models as code</label>
    <div class="smaller">(for easy version control and integration into build pipelines/other tools)</div>
</div>

Other

Open source
(free, fork/customize, etc)
<div class="toolingOptionFilter">
    <label><input id="toolingRenderingToolIndependentFilter" type="checkbox"> Rendering tool independent</label>
    <div class="smaller">(to render diagrams with different tools or visualisation formats such as <a href="/diagrams/notation#alternative-visualisations">diagrams, graphs, etc</a>)</div>
</div>
<script> $('#toolingOpenSourceFilter, #toolingDiagrammingFilter, #toolingModelBasedFilter, #toolingAsCodeFilter, #toolingWithUIFilter, #toolingRenderingToolIndependentFilter, #toolingStaticDiagramsFilter, #toolingDynamicDiagramsFilter, #toolingDeploymentDiagramsFilter').change(function() { filterToolingOptions(); }); function filterToolingOptions() { var classes = ''; if ($('#toolingOpenSourceFilter').is(":checked")) { classes = classes + '.toolingOpenSource'; } if ($('#toolingDiagrammingFilter').is(":checked")) { classes = classes + '.toolingDiagramming'; } if ($('#toolingModelBasedFilter').is(":checked")) { classes = classes + '.toolingModelBased'; } if ($('#toolingAsCodeFilter').is(":checked")) { classes = classes + '.toolingAsCode'; } if ($('#toolingWithUIFilter').is(":checked")) { classes = classes + '.toolingWithUI'; } if ($('#toolingRenderingToolIndependentFilter').is(":checked")) { classes = classes + '.toolingRenderingToolIndependent'; } if ($('#toolingStaticDiagramsFilter').is(":checked")) { classes = classes + '.toolingStaticDiagrams'; } if ($('#toolingDynamicDiagramsFilter').is(":checked")) { classes = classes + '.toolingDynamicDiagrams'; } if ($('#toolingDeploymentDiagramsFilter').is(":checked")) { classes = classes + '.toolingDeploymentDiagrams'; } if (classes.length === 0) { $('.toolingOption').removeClass('faded'); } else { $('.toolingOption').addClass('faded'); $('.toolingOption').filter(classes).removeClass('faded'); } } filterToolingOptions(); </script>