A Better Way to View Sequence Diagrams

With Capital One’s Open Source Architecture-Viewer


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.

table with red and grey boreders with black text and yellow callout squares with red borders along the top and middle

This SVG and the raw .adoc PlantUML used to generate it can be found here: https://github.com/capitalone/architecture-viewer/tree/master/sample_plantuml_data

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):

GIF showing relationship between a push notification enrollment menu screen on right and green, blue, and red flowchart on left. as black mouse clicks on menu items and scrolls through the menu, the different parts of the flowchart light up in dark blue.

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’ve now open sourced the code for this project! 🎉

Check out Architecture-Viewer on GitHub

 

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://capitalone.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. :-)


Dan Jarvis
Dan Jarvis, Sr. Mgr, Mobile Software Engineering, Capital One

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

Related Content

Software Engineering

Putting the “Tech” in “Technically, it’s a Bank”

We sat down with 3 of our engineering experts to show you what’s technically possible at Capital One

Software Engineering

Nuts & Bolts of Launching an Open Source Project

Software Engineering

Adopting an Enterprise Open Source Mindset