MSL is a minimal language for drawing and reasoning about systemigrams.
Syntax:
{Title} — the title of the systemigramA (verb) B. — behavioral edge from A to BA (verb, color) B. — behavioral edge with colored arrowA ((verb)) B. — structural (dashed) edgeA ((verb, color)) B. — structural edge with color[Node] — highlights a node (default red)[Node, color] — highlights node with given color// — single line comment/* ... */ — multi-line commentEach statement must end with a period. Node names can include spaces. Color must be a valid Graphviz color (e.g. red, gray, blue).
Semantic conventions:
A (verb describing change) B. This is understood as:
A influences B’s change. A itself remains in this interaction relatively unchanged, while B undergoes the interesting transformation. The verb can be in active or passive voice depending on the direction of the change and the verb used. Compare "sensor (activates) alarm" to "environment (is scanned by) scanner". In the later case the scanner's state is changed, while the environment is unchanged.
A (outputs an object to) B. A (is input into) B. This is understood as:
A inputs something, that is then changed in B, probably output again. The changed object does not have to be an explicit node anywhere. It can be only tracked through stations that change it. Or the object is modeled explicitly, A is an input to B, that is then used or changed in B. A is then often produced by some upstream node.
Behavioral edges stand for classes of behavior. Instances of behavioral edges take time, and run one after the other. They can run in the background in multiple instances while you inspect one of them, or even continuously.
A ((verb describing connection)) B. This is understood as:
A is connected to B, and this connection does not change.
Examples are A is part of B, A owns B, A hosts B.
If you want to cross reference different ssg files, because you put the details in another diagram, structural links are the way to go. The filename can't be directly referenced, because of the dot, so this schema is used:
oven ((implemented by)) OvenSubsystem. This means that the oven node's details are explained in the diagram with title OvenSubsystem or file name OvenSubsystem.ssg. It's best practice that filename and title match.
OvenSubsystem ((is referenced in)) KitchenSystem. This is in turn put into OvenSubsystem.ssg to make clear that the content is referenced by a node in KitchenSystem.ssg.
Colors are used to point something out to the reader. Their semantic can be set by the modeler, or they can simply be used to highlight portions of the diagram.
These simple restrictions make structured systemigrams (SSGs) readable on their own, while retaining much of the simplicity and expressive power of the original systemigrams. Systemigrams were devised by John Boardman and Brian Sauser in the 1990s and published in 2013 in their book Systemic Thinking: Building Maps for Worlds of Systems. However, the original systemigrams do not use a formalized syntax or semantics. Instead, they rely on heuristics and a practice called the SystemiShow, in which the creator walks stakeholders through the diagram, explaining it piece by piece to make its meaning clear.
Usage:
Start with a description of the behavior of a part of the system. Change the description, until you have only behavioral relations between two nodes. Rewrite in MSL. This is the thread to unravel the system. Now methodically ask: What happens before? What happens afterwards? What happens in parallel?
If you are interested in the structure of a system as opposed to the behavior, ask "What is this node in relation to a specific other node?". It may be a part, a host, an owner.
The goal:
It is not necessary to find the true depiction of a system. We need to find an agreeable, communicatable, illuminating and actionable one.
What to look for:
Repeated or circular dependencies reveal loops. Loops can reinforce, balance and create non-obvious global behavior, especially when they interact.
Nodes can accumulate counts or measures of a certain object called the node's stock. Stocks come from outside of the system or from other nodes, they may be used by or disappear in other nodes. Predicting stock change is an interesting problem, specifically when the inflow and/or outflow is governed by feedback loops.
Attribution and Licensing:
This editor and the Minimal Systemigram Language (MSL) are developed and maintained by Stefan Kober.
Application code not covered by the projects mentioned below (c) Stefan Kober, MIT license.
MSL specification (c) Stefan Kober, Apache 2.0 license.
The diagram rendering is powered by the open-source Viz.js project, which provides a WebAssembly port of Graphviz.
Viz.js Copyright (c) Michael Daines, MIT license.
Advanced Layout and Styling:
The goal of MSL is to avoid unnecessary complexity and provide just enough syntax to model and communicate system behavior effectively.
However, if you need fine-grained control over layout, labeling, or stylistic details, you can export your diagram as Graphviz DOT format.
Then continue working directly with Graphviz, which supports powerful features such as subgraphs, clusters, styles, and advanced rendering options beyond MSL’s minimal core.