fc4-framework

fc4-tool

fc4-tool is a command-line tool that supports and facilitates working with FC4 diagrams.

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.

Features

The tool has three main features:

Formatting

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.

Snapping

Improves the layout of Structurizr Express diagrams:

Rendering

Given Structurizr Express diagram YAML files, creates image files that contain the visualization of the diagram.

Setup

Quick start for Homebrew users

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

Requirements

  1. A Java Runtime Environment (JRE) or Java Development Kit (JDK)
  2. On MacOS if you have Homebrew you can run brew cask install adoptopenjdk11-jre
  3. An installation of Chrome or Chromium 70–77 (inclusive)
    1. On MacOS:
      1. If you have Homebrew you can run brew cask install chromium
      2. Chromium/Chrome must be at either /Applications/Chromium.app or /Applications/Google Chrome.app

Download and Install

With Homebrew

Homebrew is the recommended installation method for anyone using Linux, MacOS, or Windows Subsystem for Linux. Please see Quick start for Homebrew users above.

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:

Manually

  1. Download the archive for your platform from the latest release
  2. Expand the archive
  3. Optional: move the extracted files to somewhere on your $PATH
    1. e.g. mv ~/Downloads/fc4/fc4* ~/bin/

Authoring Diagrams

Abridged Workflow

  1. Run in your terminal: fc4 -fsrw path/to/diagram.yaml/or/dir
  2. Open a YAML file in your text editor and edit it
    1. Either a YAML file specified directly or one in or under a specified directory
  3. Whenever you save the file, fc4-tool will see the change, clean up the file (overwriting it) and render the diagram to a PNG file (overwriting that file, if it already existed)
  4. When you’d like to wrap up your session:
    1. Save the file one last time and wait for fc4-tool to format, snap, and render it
    2. Hit ctrl-c to exit fc4-tool
    3. Run git status and you should see that the YAML file has been created/changed and its corresponding PNG file has also been created/changed
    4. Commit both files

Full Workflow

Please see The Authoring Workflow section of the FC4 Methodology.

Command Line Interface Reference

Basic usage: fc4 OPTIONS PATH [PATH...]

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.

Options

Feature Options

-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.

Output Formats

-o FORMATS | --output-formats FORMATS

Specifies the output format(s) for rendering diagrams.

Here are some examples of valid ways to use this option:

Watching

-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.

E.g. 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.

Other Options

-h | --help

Prints out usage information and exits.

-d | --debug

Enables a debug mode of dubious utility.

Source Code

Like the entire framework, the tool is Free and Libre Open Source Software (FLOSS) so its source code is readily available for review or modification via its GitHub repository.