fc4-framework

fc4-tool

A tool for reorganizing, restructuring, reformatting, and rendering FC4 diagrams.

Purpose

As explained in The Toolset section of the FC4 Methodology:

This tool was created because when one uses Structurizr Express (SE) to position the elements of a diagram, SE regenerates the diagram source YAML in such a way that the YAML becomes noisy and the sorting can change. 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.

So fc4-tool processes the YAML: cleans it up, applies a stable sort to all properties, removes empty properties, etc — so as to ensure that the changes applied in each revision are very small and specific and all extraneous changes are filtered out. This will hopefully enable effective peer review of revisions to the diagrams.

fc4-tool also:

Features

The tool has two main features:

Formatting

Rewrites Structurizr Express diagram YAML files:

Rendering

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

Setup

Requirements

  1. A Java Runtime Environment (JRE) or Java Development Kit (JDK)
    1. On MacOS if you have Homebrew you can run brew cask install adoptopenjdk
  2. An installation of Chrome or Chromium 70–72 (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

MacOS quick-start for Homebrew users: brew cask install adoptopenjdk chromium

Download and Install

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

Commands

The fc4 program supports multiple commands:

edit

fc4 edit file-or-dir ...

Launches the tool in a persistent mode to effect the authoring workflow described above.

format

fc4 format file ...

Reformats each specified Structurizr Express YAML file as described above.

render

fc4 render file ...

Renders each specified Structurizr Express YAML file as described above

process

fc4 process file ...

Reformats and renders each specified Structurizr Express YAML file.

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.