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.
While sequence diagrams are great as detailed reference documentation, they often immerse the reader in low level details, which can obscure the overall architecture.
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
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’ve now open sourced the code for this project! 🎉
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. :-)
