The Story behind ZenUML

I have been thinking about writing about the story behind ZenUML for a long time. I am doing it now because of the inspiration of these two articles from Anthony:

2010: ZenUML was born in ThoughtWorks

Believe it or not, the journey started in November 2010. At that time, I was a loyal back-end developer and thought frontend developers' job was just to add an on-click handler to buttons and set the font color of a paragraph. Then HTML5 came. Well, maybe HTML5 before 2010, but that is when it came to me.

At that time, I was a senior consultant in ThoughtWorks China. Beijing office organized a Web App competition. The only requirement I recalled was to use one of the newly added HTML5 features. The feature that I chose was - Canvas.

I had been a fan of sequence diagrams for a while. My favorite UML tool is astah. It had a different name at that time, but it doesn’t matter. While astah is a good diagramming tool, I did not like drag-and-drop that much. I believe there needs to be a more efficient way to draw sequence diagrams. was already born at that time. But I did not like the loose syntax “A->B: message”. I will write another article to explain why I call it a “loose” syntax, but the point is I wanted a more concise syntax, a syntax that developers are most familiar with “A.method()”. If you would like to check out the current syntax, go here. The first release looked like below with a cool hand-drawn style. After the first version was released, I received some good feedback and acquired a few loyal users (hey, Jacky, Zhang Yi). But it was pretty much a personal tool or friend's tool.


In 2013, I started using Angular. I rewrote the project with AngularJs. It is published here. It was not a complete tool. For example, it does not support fragment. At this time, my friends and I were still using the first version.

You may have noticed that it was called “ColorUML”. The idea was borrowed from Peter Coad’s “Java Modeling in Color with UML”. My goal was (and is) to facilitate people applying this technique in their projects.

2017: Rewrite in VueJs

2017 is a special year. It was when I started seriously thinking about commercializing my tool. I have used AngularJs and I was not a fan of JSX at all. My choice had to be VueJs (sorry to other frameworks). I built the prototype in 7 days while learning VueJs.

A little bit about layout strategies

In the first version, everything is drawn on a canvas. For example, for a given line, we just need to calculate (x1, y1) and (x2, y2). It is very easy to understand if it goes right. It is also relatively easier to test because everything is decided before it is drawn on the canvas^1. However, there are some drawbacks.

^1. This is not 100% correct. We do not know the width of a participant label before drawn on canvas.

First, it is very difficult to debug when something goes wrong. The position and dimensions of the element are calculated from many factors: the position of the participant, whether it is inside a self-call, whether it is inside a fragment, etc. If it goes wrong, you have to check at which step the error happens. There are no visual facilities you can get from the canvas.

Second, styling the element is difficult. For the second picture above, we can easily change the color of the lines without changing JS code. If it is drawn on canvas, it is impossible.

In the Angular version, we used plain dom elements. It immediately proved to be a good choice when we layout the lifelines. There is almost no JS code required. Simply adding them to the root dom will give a perfect layout. In the current version, we pushed this strategy further. All the messages are positioned based on the position of their parents.


We used a hand-crafted parser (mostly based on regular expression) in the first two versions. In the latest version, I decided to use a formal parser. Antlr4 is the one that I chose. I am not sure if it was the best choice, but it does solve a lot of problems and enable us to extend the syntax much smoother.

Why I did not open-source

The first two versions are open source. I was hoping:

  1. It would attract more people to use it as it improves trust.

  2. The community would help me build new features for their specific use cases.

It did not happen. I do not blame the community. They were not mature enough to attract the user base that makes it happen.

In this version, we open-source all the integrations:

  • Confluence (Cloud, Server, DataCenter);

  • Web and Chrome extension

  • JetBrains Plugin

  • A Web component node module

  • VS Code Extension

  • Markdown Extension

The renderer itself is closed. We have 3 core developers working on it. I have tried to get more people involved as they offerred help. Unfortunately, it has never worked out well. I spent hours explaining how it works for some work that I can finish in 20 minutes or less. I am grateful, but it just does not work, for the moment.

What is going on with ZenUML?

The past few months have been the most fruitful period since 2017. We added a few “nice-to-have” extensions to the syntax and the editor.