Sometimes I need to see a problem before I can explain it.
Who calls this service? What happens if the request fails? Is this actually one feature, or three separate problems hiding under the same name?
A few boxes and arrows can make those questions easier to answer. So can a mind map that starts messy and gradually becomes a plan.
That's why I still like UML—and why I rebuilt Codiva PlantUML, my browser-based editor for text-based diagrams.
Yes, UML. The thing you may remember from university assignments, enormous class diagrams, and arguments about which arrowhead to use.
I think there's still a lot to like once you bring it back to everyday development.
A little history: why all those boxes existed
Before UML, there were several competing approaches to modeling object-oriented systems. Grady Booch, James Rumbaugh, and Ivar Jacobson brought their methods together, helping create the Unified Modeling Language. It became an OMG standard in 1997.
The idea was useful: give people a shared visual vocabulary for describing software. A relationship or interaction shouldn't need an entirely new notation every time you change teams.
Then came the baggage many developers associate with it: elaborate modeling tools, diagrams produced as deliverables, and designs that took longer to maintain than the code they described.
If your introduction to UML involved modeling every getter and setter before writing a working program, I understand the lack of enthusiasm.
But I still find value in the smaller habit underneath it: put a model of the problem somewhere you can inspect it.
A sequence diagram can reveal a round trip nobody noticed. A state diagram can expose a transition nobody defined. Even an unfinished sketch can show that two people have been imagining different systems throughout the same meeting.
Those are useful discoveries before implementation.
A diagram can help you think before it helps you document
We often talk about diagrams as something you make after understanding a system, so someone else can understand it too.
I like the earlier stage just as much: making a diagram to find out what I understand.
Say you're planning an asynchronous report feature. In prose, it sounds simple:
The user requests a report, a worker generates it, and we notify them when it's ready.
Start drawing it, and the questions appear:
- Who owns the report's status?
- What happens when the worker retries?
- Can the user request the same report twice?
- What does “ready” mean if notification fails?
The picture gives those questions somewhere to live. You can change the model while the change is still cheap.
The diagram doesn't have to represent the entire system. Often the most useful one answers a single question.
Mind maps are a great place to start
Before I know the sequence of events, I may only know the pieces of the problem.
That's where mind maps help: take a vague feature, give it a few branches, and keep splitting until the unknowns become visible.
PlantUML supports mind maps too. They aren't part of the UML standard; PlantUML extends beyond UML into other useful diagram types.
Here's a small example you can paste into the editor:
@startmindmap
* Asynchronous reports
** User experience
*** Request a report
*** Check progress
*** Download the result
** Processing
*** Queue the job
*** Generate the file
*** Retry failures
** Questions
*** Duplicate requests?
*** File expiration?
*** Notification failure?
@endmindmap
The asterisks define the hierarchy. Add another level when an idea needs breaking down; move a branch when you realize it belongs elsewhere.
I find this useful for feature planning, exploring an unfamiliar domain, or organizing the questions I want to take into a technical discussion.
An outline works too. Seeing its branches together can make gaps and uneven complexity easier to notice.
Then, when one branch needs a closer look, you can turn it into a more specific diagram.
A few UML diagrams still earn their place
You don't need to learn the whole notation to get something useful from it.
| When I want to understand… | I reach for… |
|---|---|
| Who talks to whom, and in what order | A sequence diagram |
| Which states exist and what changes them | A state diagram |
| How a workflow branches | An activity diagram |
| How domain concepts relate | A class diagram |
| How the system's parts connect | A component diagram |
A class diagram, for example, can show the relationships between an order, its items, and a payment without listing every method in the codebase.
A sequence diagram can make the difference between “request accepted” and “work completed” explicit:
@startuml
actor User
participant API
queue Jobs
participant Worker
User -> API: Request report
API -> Jobs: Enqueue job
API --> User: Accepted + report ID
Jobs -> Worker: Deliver job
Worker -> Worker: Generate report
alt generation succeeds
Worker -> API: Mark report ready
else generation fails
Worker -> API: Record failure
end
@enduml
This sketch also leaves things unresolved. How does the user learn that the report is ready? What happens after a failure?
That's a useful next conversation. The diagram has already helped identify it.
Why I like writing diagrams as text
Visual editors are great for sketching freely. With PlantUML, I like being able to describe the relationships and let the renderer handle their arrangement.
That gives me a few practical advantages:
- Reviewable changes. A pull request can show a new participant, message, or state transition.
-
Source beside the code. A
.pumlfile can follow the same branches and review process as the feature it explains. - Easy reuse. Copy a flow, adjust a few lines, and explore an alternative.
- Less time arranging boxes. I can focus on the interaction before worrying about presentation.
There are trade-offs. Automatic layout won't always look the way you want, and a large diagram can become difficult to read regardless of how you generate it. Text also doesn't keep documentation accurate by itself; someone still has to maintain it.
For me, the sweet spot is a small, editable diagram with a clear purpose.
If you already use Mermaid and it fits your workflow, great. I see the habit of keeping useful diagrams as text as the bigger win. PlantUML happens to be the tool I wanted to build around.
Meet Codiva PlantUML
I had an older editor built with CodeMirror 5, Bootstrap, and CDN dependencies. It rendered through the public PlantUML server and had been sitting there for a while.
I rebuilt it with Astro, React islands, CodeMirror 6, and my own containerized PlantUML engine.
The goal was a convenient place to open an example, work through an idea, and export a diagram without setting up a local environment.
The editor includes:
- Syntax highlighting and autocomplete for participants you've declared.
- Syntax diagnostics with line highlighting.
- Formatting from the context menu.
- Dark mode.
- SVG and PNG export.
- Six examples to start from.
- No account required.
Rendering happens on my backend, so diagram source is sent to that server when you use the hosted editor.
It's free to use. There's an optional coffee link in the footer to help with the server bill.
A couple of things I learned rebuilding it
Running the engine myself gave me more control over responsiveness and diagnostics. It also gave me a few bugs worth remembering.
Keep the JVM warm
Launching a new JVM for each render took around 1,115 ms in my setup. Keeping PlantUML running brought the warm local engine measurement down to around 14 ms, averaged over 10 requests.
Over HTTPS, I observed roughly 180 ms, compared with around 560 ms for the public endpoint in my comparison. Those are observations from my deployment, rather than a general benchmark; network location, diagram complexity, and server load all matter.
PlantUML's built-in PicoWeb server provides a simple way to keep the engine running:
java -jar plantuml.jar -picoweb:8777
A successful response can contain an unsuccessful diagram
My sequence-diagram test passed. A class diagram then failed because the container was missing Graphviz.
The surprising part: the response was HTTP 200 with a valid SVG containing the error message. My status-code check was happy. The person trying to render the diagram wasn't.
I used Smetana, PlantUML's Java port of Graphviz, to handle layout in my setup. The editor also needed useful diagnostics rather than leaving users to read an error drawn inside an image.
That's the improvement I care about most: if you make a syntax mistake while thinking through a flow, the editor should help you get back to the flow.
PlantUML supports selecting Smetana in diagram source: Its documentation also lists the CLI option In my server integration, the proxy injects the pragma into the rendering copy, leaving the editor contents and exported source as written. That added line means diagnostic positions need mapping back to the original source. My application layer uses PlantUML diagnostics to return a 422 response with a line number for syntax errors. That response contract is part of the editor's backend; starting PicoWeb alone doesn't provide it.Implementation detail: selecting Smetana and mapping error lines
!pragma layout smetana
-Playout=smetana.
Give one of your ideas a diagram
If you've been carrying a feature around in your head, try putting its main branches into a mind map. If a flow keeps getting lost in paragraphs, try a sequence diagram.
That's the kind of everyday use I built this editor for.
Try Codiva PlantUML — no account needed
I'd love feedback on the editor, especially anything that gets in the way of turning an idea into a readable diagram.
Do you still use UML—or did diagrams find their way back into your workflow through mind maps, Mermaid, or something else?
Top comments (0)