A Better Way to View Sequence Diagrams

Sequence diagrams are an excellent way to document the interactions between components. They are often used to document the flow of HTTP requests and responses across multiple services.

Below is an example that I built using a standard called PlantUML. It shows an Android and iOS push notification registration flow for an application.

Source: raw PlantUML .adoc file, which produces the SVG shown above

While sequence diagrams are great as detailed reference documentation, they often immerse the reader in low level details, which can obscure the overall architecture.

Since we use PlantUML quite widely at Capital One, I asked one of our interns Swaraj to find a way to render PlantUML as an interactive webpage to make it easier to see the big picture, and progressively reveal the detail.

Here is what he came up with for the above example (you can try it yourself here):

Hopefully you’ll agree that the architecture-viewer version is more easily digestible than the sequence diagram.

  • High level relationships between the participants are more obvious.
  • Contextual highlights make it easier to review each step in the sequence.

We open sourced the code for this project! 🎉

(Forked from the original capitalone/architecture-viewer repo.)

Here’s a summary of how it works:

  • PlantUML is converted to a JSON format that can be used as input for a data visualization using the Cytoscape.js library.
  • The architecture-viewer is deployed as a static website inside GitHub Pages. You can use ours at https://daj.github.io/architecture-viewer/, or fork our repo and run it from your own repo.

Here are some of its features:

  • Responsive web UI automatically renders sequences as architectural box diagrams.
  • Open a PlantUML .adoc file to view it, or load it directly using a URL parameter.
  • Move through the sequence steps using either your mouse or keyboard arrows.
  • Sequence steps are listed as clickable links in the sidebar on the right.
  • PlantUML stereotypes are used to color and group participants.
  • Notes are hidden by default. Click on a participant box or the info icon ⓘ next to a step to display.
  • Architecture diagrams can be embedded in other webpages as an <iframe>.
  • Automated build and deploy to GitHub Pages using npm.

The architecture-viewer currently only supports the most common PlantUML sequence diagram syntax, but it shouldn’t be hard for you to add support for more. :-)

--

--

--

Machine Learning & Android — https://stackoverflow.com/cv/dj

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Dan Jarvis

Dan Jarvis

Machine Learning & Android — https://stackoverflow.com/cv/dj

More from Medium

Transformation

HOW TO RATE A SHELTER.

SCCM Application migration with better content handling

What on earth is Ethereum? A Beginner’s explanation in Simple terms.