Diagramming vs modelling

As an industry, we've tended to prefer diagramming over modelling, primarily because the barrier to entry is relatively low, and it's seen as a much simpler task. When diagramming, you're typically creating one or more separate diagrams, often with an ad hoc notation, using tools (e.g. Microsoft Visio or a whiteboard) that don't understand anything about the semantics of your diagrams. The domain language of diagramming tools is really just "boxes and lines", so you can't ask them questions such as "what dependencies does component X have?". Additionally, reusing diagram elements across diagrams is usually done by duplication (i.e. copying and pasting), thereby putting the responsibility on you to keep diagrams in sync when you rename such elements.

With modelling, you're building up a non-visual model of something (e.g. the software architecture of a software system), and then creating different views (e.g. diagrams) on top of that model. This requires a little more rigour, but the result is a single definition of all elements and the relationships between them. This, in turn, allows modelling tools to understand the semantics of what you're trying to do, and provide additional intelligence on top of the model. It also allows modelling tools to provide alternative visualisations, often automatically.

Diagramming Modelling
Consistency across diagrams?

With diagramming tools, every diagram is typically a separate disconnected artifact, mixing the content (the definition of elements/relationships) and the presentation (the layout information). Any reuse of elements (boxes) and relationships (lines) is usually done with copy-paste. Because of this, changes to a diagram typically only affect a single diagram. If you rename an element in one diagram definition, you need to ensure that it's also renamed in other diagram definitions too. In other words, if not managed properly, these diagrams can become inconsistent and get out of sync.

A Structurizr workspace allows you to create multiple views (diagrams) based upon a single definition of elements and relationships (a model). These views use references to model elements and relationships, so changes to an element or relationship definition will be automatically reflected on all diagrams where they appear. Although a Structurizr workspace contains both the content (model) and presentation (views), these are kept separate. This means the same styles are used across all diagrams in a workspace. Structurizr also supports the concept of themes, for consistent diagram notation across workspaces between teams.

Multiple input formats?

Most diagramming tools only support a single format and/or input method/

Structurizr has a web API, based upon a JSON schema, which can be created using a number of authoring tools.

Automatic, alternative visualisations?

The domain-specific language of most diagramming tools is just "boxes and lines", and they don't really know what the boxes and lines represent. For this reason, these tools can't offer any additional intelligence.

Structurizr can use the information in the model (elements and relationships) to create a number of alternative visualisations. These allow you to explore the model, and answer questions related to aspects such as dependencies and the impact of change when restructuring.


The more diagrams you need, the more separate diagram definitions you have, which in turn increases the maintenance effort and complexity of keeping them in sync.

Having a single definition of elements and relationships reduces maintenance effort and complexity.


While it might seem easier to create a quick diagram with a diagramming tool, we recommend using a modelling tool for long-lived documentation where you have more than a couple of related diagrams.