While it was initially created to clean up the formatting of diagram source YAML files, its feature set has expanded over time; it now also “snaps” the elements and vertices in a diagram to a virtual grid and renders diagrams.
For the backstory of the creation of the framework and tool, see this blog post.
The tool has three main features:
When used to create or edit a diagram, Structurizr Express (re)generates the diagram source YAML in such a way that the YAML becomes noisy and the sorting can change unpredictably. This makes the source harder to work with in a text editor and impossible to usefully diff from revision to revision — and without useful diffing it’s very difficult to do effective peer review. And peer review is a crucial element of the Docs as Code philosophy.
So this feature rewrites diagram YAML files:
…thereby facilitating the authoring, editing, and reviewing of revisions to the diagrams.
Improves the layout of Structurizr Express diagrams:
Peopleelements so they’ll align properly with other kinds of elements (working around a rendering quirk of Structurizr Express)
Given Structurizr Express diagram YAML files, creates PNG image files that contain the visualization of the diagram.
If you already use Homebrew, one or both of these commands might be all you need to get started:
# If you’re using MacOS and you don’t already have Chromium or Chrome installed: brew cask install chromium # If you’re using a different OS and you don’t already have Chromium or Chrome installed # then install Chromium or Chrome however you generally install such software on your system. # The main event (should work on any OS that supports Homebrew) brew install fundingcircle/floss/fc4
brew cask install adoptopenjdk11-jre
brew cask install chromium
If you don’t already use Homebrew, we recommend you install it and then see Quick start for Homebrew users above.
If you cannot use Homebrew, or would prefer not to, you can manually download and install the tool:
mv ~/Downloads/fc4/fc4* ~/bin/
fc4 -fsrw path/to/diagram.yaml/or/dir
git statusand you should see that the YAML file has been created/changed and its corresponding PNG file has also been created/changed
fc4 OPTIONS PATH [PATH...]
-f | --format,
-s | --snap, and
-r | --rendermay be specified (at least one is required)
When invoked with the
-w | --watch option, instead of immediately processing the diagrams and
exiting, the tool will start up in a persistent mode, watching the YAML files and processing them
when they’re changed. To exit, press ctrl-c on your keyboard.
fc4 -r my-diagram.yamlor
fc4 --render my-diagram.yamlwould render the specified diagram
-f | --format
Reformats each specified Structurizr Express YAML file as described above.
-r | --render
Renders each specified Structurizr Express YAML file as described above.
-s | --snap
If specified, elements in diagrams will be snapped to a virtual grid.
-w | --watch
If specified, the tool will start up in a persistent mode and watch the YAML files in/under the specified paths for changes. When a file is changed, the tool will process it according to the feature options, at least one of which is required. In this mode, the tool does not process any files when first invoked.
fc4 -fsrw . would watch the current directory and all sub-directories, recursively, for
changes to diagram files; when a change is observed the diagrams, would be formatted,
snapped, and rendered.
-h | --help
Prints out usage information and exits.
-d | --debug
Enables a debug mode of dubious utility.