FC4

7. The Authoring Workflow « FC4 User Manual

Summarized Workflow

  1. Start Structurizr (docs)
  2. Run fc4 -fsrw path/to/repo to start fc4 watching for changes
  3. Create and/or edit diagram YAML files
  4. fc4 will automatically format, snap, and render the diagrams
  5. Run git commit to commit the new/changed files

Full Workflow

  1. Create a new git branch in your local instance of the diagram repository
  2. In your text editor: either create a new diagram source file or open an existing diagram source file
  3. Start Structurizr (docs)
  4. In your terminal, run fc4 -fsrw path/to/repo
    1. This starts FC4 watching your repository for changes to any diagram source YAML file (or new files)
    2. Each file will be formatted, snapped, and rendered when it changes or is created
      1. A future release of the tool will enable users to specify which actions should be performed
  5. In your text editor, open a diagram YAML file in one pane and its rendered PNG file in an adjacent pane
    1. If the diagram is new then the PNG file won’t exist until you’ve saved the YAML file and fc4 has successfully rendered the diagram
  6. Edit the diagram YAML by adding/changing elements, relationships, etc, then save the file
    1. This will cause fc4 to format, snap, and render the diagram
    2. Ideally your editor will see the changes the open files and automatically refresh your open buffers/windows/tabs so you can immediately see the changes
    3. Continue to edit the YAML, save the file, and observe the changes to the PNG until you’re happy with the changes
  7. In your terminal, hit ctrl-c to stop fc4
  8. Use your git UI of choice to commit your changes
  9. Push your local changes to the remote repository regularly
  10. When you’re ready to submit your changes for review, open a Merge Request or Pull Request to get your changes reviewed and then merged into the default branch (e.g. main)

Here’s a screenshot of an editor with a diagram open in two panes:

Screenshot of an editor with a diagram open in two panes

Optional: Using Structurizr Express for Graphical Editing

This is optional, but can be very helpful when you need to make broad layout changes, or experiment quickly with various changes to a layout.

During an editing session as described above, when you have both files of a diagram open in your editor, you can use Structurizr Express (SE) like so:

  1. Select the entire contents of the YAML file in your text editor and cut it into your clipboard
  2. Switch to your Web browser and open SE, using your local URL (e.g. http://localhost:8080/express)
  3. Once SE has loaded, click the YAML tab on the left-hand side of the UI
  4. Paste the diagram source into the YAML textarea
  5. Press tab to blur the textarea
  6. SE will either render the diagram, or display a red error indicator in its toolbar
    1. If SE shows its red error indicator, click the indicator button to bring up a dialog listing the errors
  7. Use the right-hand side of SE to arrange the elements and edges as desired
    1. Don’t worry about aligning elements precisely; fc4 will take care of this for you
  8. Cut the diagram source from the SE YAML textarea into your clipboard
  9. Switch back to your editor, paste the diagram source into the YAML file buffer, and save the file
  10. fc4 will see that the YAML file has changed, and will process it as described above
    1. NB: the processing includes snapping the elements and vertices of a diagram to a virtual grid, which has the effect of precisely aligning elements that had been only roughly aligned

Here’s a screenshot of Structurizr Express:

Screenshot of Structurizr Express

Please continue to Publishing or go back to the top page of the manual.

This site is open source. Improve this page.