Irakli Betchvaia

Posted on Jun 21

Why I'm building yet another UML tool in 2026

#kuml #kotlin #uml #modeling

Let me get the obvious objection out of the way.

PlantUML exists. Mermaid renders natively on GitHub. draw.io is free and works. Enterprise Architect, MagicDraw, Rhapsody and Papyrus cover the heavy end. By any reasonable count, the world has somewhere north of forty UML tools, and most teams complain about exactly one of them: the one they have to use.

So why build another?

The honest answer has three parts. I'll walk through each — including the parts where my reasoning is shaky, and the one structural gap I think the whole category has been ignoring for a decade.

What's actually broken

I've spent twenty years writing UML and SysML in automotive R&D — Car2x, autonomous driving, safety-critical embedded systems at Keysight. The diagrams aren't decoration. They drive code generation, ISO 26262 evidence, and reviews with hardware engineers who don't read Kotlin.

Here is the workflow that every automotive team I know actually runs, regardless of which tool sits in the middle:

Draw the diagram in EA, MagicDraw, or Papyrus.
Export PNG.
Paste into Confluence or a Word deliverable.
Change the class in the code six weeks later.
Forget the diagram exists.
Eight months on, the safety auditor asks which version is binding. Nobody knows.

This is not a tooling failure of any one product. It's a property of treating the model and the code as two separate artifacts that happen to describe the same thing. The gap between them grows by default, every sprint, forever. No amount of "discipline" closes it — I've watched senior people try.

PlantUML and Mermaid tried to fix this by making the diagram text. That was the right move and the wrong implementation. Both are bespoke text formats, parsed by bespoke engines, with no connection whatsoever to the code they're supposed to describe. You can write User <|-- Admin in PlantUML on Monday and rename Admin to Administrator in Kotlin on Tuesday, and nothing — not the IDE, not the compiler, not CI — will tell you the diagram is now lying.

The enterprise tools (EA, MagicDraw, Rhapsody) do understand types and constraints. They're genuine modeling tools. They also cost five figures per seat, need administrators, and ship a UI that was state of the art around the time Windows XP launched.

Every one of these tools treats UML as a separate artifact from the code. That is the structural flaw. Everything else is decoration.

Two empty quadrants

I spent a weekend mapping the modeling-tool landscape — text DSLs, classic CASE tools, executable-UML attempts, code-as-diagram libraries. The detailed breakdown lives on kuml.dev/comparison for anyone who wants the full matrix.

Two findings refused to leave me alone.

Nobody has built a modeling tool on a typed host language. Plenty of Python libraries draw diagrams. Plenty of Java APIs sit on top of EMF. There are dozens of custom text grammars. There is no serious modeling tool that treats the model as ordinary code in a modern, statically-typed language, with first-class IDE refactoring across model and code. That's a structural gap, not a language-preference argument — it happens that Kotlin's type-safe builders are the cleanest fit available today, but the point would stand for any equivalent host.

Nobody designs for the LLM era. PlantUML and Mermaid are LLM-friendly by accident — they have enormous training footprints. "Common in training data" is a fragile moat that erodes the day a typed, verifiable alternative appears. None of the major tools have asked the obvious question: what does a modeling language look like if you assume an LLM writes half the diagrams? Named parameters everywhere. Compile-checkable output. An MCP server so the agent can introspect the model. A benchmark that measures how often the generated model actually type-checks.

These aren't wishlist features. They're empty quadrants on the market map. Building kUML is partly a bet that those quadrants are empty because they're hard, not because nobody wants them.

The idea I couldn't shake

What if the UML diagram and the code were written in the same language?

Not "next to" the code. Not "generated from" the code. The same artifact. Same compiler. Same IDE. Same refactoring engine. Same review tooling.

Kotlin has a feature called type-safe builders — DSLs implemented as ordinary function calls. If you've used Gradle's Kotlin DSL, you've already seen it: dependencies { implementation("…") } looks like configuration but is in fact a Kotlin function call that the IDE understands, the refactorer can rename, and the compiler can check.

A class diagram in kUML looks like this:

@file:Suppress("unused")

import dev.kuml.core.dsl.classDiagram
import dev.kuml.uml.dsl.association
import dev.kuml.uml.dsl.attribute
import dev.kuml.uml.dsl.classOf
import dev.kuml.uml.dsl.constraint
import dev.kuml.uml.dsl.operation
import dev.kuml.uml.dsl.returns

classDiagram("E-Commerce Domain") {

    val order = classOf("Order") {
        attribute(name = "id",        type = "UUID")
        attribute(name = "createdAt", type = "Instant")
        attribute(name = "status",    type = "OrderStatus")
        operation(name = "confirm")   { returns("Boolean") }
        constraint("hasItems", "self.items->size() >= 1")
    }

    val orderItem = classOf("OrderItem") {
        attribute(name = "quantity",  type = "Int")
        attribute(name = "unitPrice", type = "BigDecimal")
    }

    association(source = order, target = orderItem) {
        target { multiplicity("1..*"); role = "items" }
    }
}

This is a .kuml.kts file — a Kotlin script — sitting inside your Gradle project. The JetBrains plugin's rename action propagates across all classOf references in the diagram. Elements show up in IntelliJ's Find Usages. The diagram lives in source control, in code review, in the same diff as the classes it describes.

The multiplicity("1..*") on the orderItem end is not a label — it's part of the model. The M2M transformers read it: kuml transform --transformer uml-to-jpa uses it to decide whether the JPA relationship becomes @OneToMany or @ManyToOne.

That constraint("hasItems", "self.items->size() >= 1") line is not a comment — it's an OCL invariant attached to the model. kuml validate parses and evaluates it: the moment an Order can have zero items, validation exits non-zero and your CI build fails. The same command also catches duplicate IDs, circular inheritance, and dangling references. Embedding OCL constraints in the model and enforcing them in CI is something I framed as "still coming" in earlier drafts — it ships today.

What kUML is today

Let me be specific about what exists right now, because the "early-stage, class diagrams only" framing I had in earlier drafts is no longer accurate.

Diagram types — all shipped: all 14 UML 2 types (class, sequence, activity, state machine, component, deployment, use case, and more), all 8 SysML 2 types (BDD, IBD, UC, REQ, STM, ACT, SEQ, PAR), and C4 architecture diagrams.

IDE integration: the JetBrains plugin gives you a live SVG preview pane (300 ms debounce), 38 DSL autocomplete items grouped by diagram type, rename refactoring that works across model and code, code folding, and inline error squiggles — all in .kuml.kts files that IntelliJ already understands as Kotlin.

Interfaces: kuml serve launches a browser-based editor with live preview and SVG/PNG/LaTeX download. kuml-desktop is a standalone Compose desktop app — edit and preview with no server, no browser required.

Reverse engineering: kuml reverse <source-dir> reads existing Java (JavaParser) or Kotlin (PSI K2) code and emits a clean .kuml.kts model. --lang auto detects the dominant language. Smoke test: 10 production Kotlin files → 267-line model in ~550 ms.

Interoperability: kuml import --format xmi / kuml export --format xmi round-trip UML models with Enterprise Architect and Papyrus (tool-specific artefacts get stripped on the way in). kuml import --format structurizr ingests Structurizr C4 workspaces — the full Big Bank Plc reference architecture is a committed fixture.

Validation: kuml validate evaluates OCL invariants declared in the model (constraint("hasItems", "self.items->size() >= 1")) and fails the build on violation, alongside structural checks for duplicate IDs, circular inheritance, and dangling references.

Extensibility: a plugin SPI + loader (kuml plugin install/list/remove) lets third parties ship themes, renderers, layout engines, codegen targets, and reverse engines without forking the core — with Ed25519 signature verification and a permission model.

Code generation — five M2M transformers: Kotlin JPA @Entity classes, OpenAPI 3.0 YAML, Kubernetes Deployment + Service manifests, Dockerfiles, C4→UML. The transformer registry is ServiceLoader-based — custom transformers plug in without forking the CLI.

Runtime: kuml run drives state machines interactively (REPL), via REST (MCP adapter), or from batch events. kuml simulate produces deterministic JSON traces with OpenTelemetry OTLP export for Jaeger or Grafana Tempo.

Distribution: sdk install kuml via SDKMAN! on five platforms. Native installers: .deb, .rpm, .dmg, .msi. Docker: ghcr.io/kuml-dev/kuml-cli. JVM library on Maven Central. Homebrew tap.

What's genuinely still in progress — because honesty matters more than marketing: a full PIM → PSM → deployment pipeline that chains the M2M transformers with automatic dependency resolution, and the LLM benchmark that measures how often a generated model actually type-checks. The two features I flagged as "coming" in earlier drafts — OCL constraint evaluation in CI and XMI round-trip with EA and Papyrus — have both shipped since then.

The "roughly eighteen months to v1.0" estimate I had in an earlier draft aged badly. We're at v0.14.0. The core idea works. The question now is how far to take it.

If you've ever had a code review where someone pointed out that the sequence diagram in the wiki no longer matches reality: there is a working tool for you today.

Why not just extend PlantUML?

I considered it. PlantUML is Java, open source, actively maintained — extending it would have been the path of least resistance.

The problem is that the gap I care about can't be patched. PlantUML's parser is a bespoke text format. There is no Kotlin type system to lean on. There is no typed metamodel. Adding genuine type-safety to PlantUML isn't a feature; it's a rewrite. And a rewrite constrained by fifteen years of backwards-compatible .puml files inherits every design choice that produced the original problem.

kUML's single design constraint is the diagram is Kotlin code. Everything else falls out for free. IDE support is already there because it's a .kt file. Refactoring works because IntelliJ doesn't know it's a "diagram". Type-checking works because it's the same compiler that checks the rest of your codebase. Build integration is just Gradle. There is no new language server to write, no new parser to maintain, no new plugin ecosystem to bootstrap.

That only works if you start over.

The MDA angle

There's a deeper bet here that I'll write about in future issues.

kUML is built around Model Driven Architecture — the OMG standard that defines a workflow from Platform-Independent Models through Platform-Specific Models to deployment artifacts. The idea is that you write the domain model once and transform it, automatically, into JPA entities, REST contracts, Kubernetes manifests, Docker Compose files.

MDA isn't a new idea. It was proposed in the early 2000s and mostly failed in practice, because the tooling was too heavy, too expensive, and too far from how developers actually work.

kUML's bet is that a Kotlin-native MDA toolchain — one that lives inside Gradle, renders inside your IDE, validates inside CI — is the version that actually works. Lightweight enough to adopt incrementally. Native enough not to fight the rest of your stack.

The early evidence says yes. Five M2M transformers already generate JPA entities, OpenAPI contracts, Kubernetes manifests, and Dockerfiles from a kUML model — code that downstream tooling accepts directly. The transformer registry is pluggable via ServiceLoader.

What's still ahead: a full PIM → PSM → deployment pipeline that chains these transformers with automatic dependency resolution. The pieces around it already landed — kuml validate enforces OCL model consistency before transformation, and kuml import/export --format xmi round-trips with EA and Papyrus. The bet isn't settled — but it's no longer just a hypothesis.

What this newsletter will be

Every week I'll publish one piece here, and ship a short version to subscribers. Not a changelog. Not a release announcement. The actual decisions:

Why a hand-written Kotlin metamodel — sealed interface plus data class plus kotlinx.serialization — beats EMF/Ecore for this problem.
How OCL constraint validation slots into a Gradle build.
What the JetBrains plugin platform requires for a custom DSL.
Where Kuiver's rendering model breaks first under complex sequence diagrams.
What the LLM benchmark actually measures, and what I had to throw away on the third attempt.

Sometimes I'll be wrong, and I'll say so on the same page where I said the original thing.

If you work with UML, SysML, or domain modeling — particularly if you've felt the gap between your models and your code — I think you'll find this useful. If you build developer tools, the architecture choices may be interesting regardless of whether you care about UML.

Subscribe if that's you. One email a week. No sponsored content, no affiliate links, unsubscribe in one click.

Further reading: the full competitive analysis maps kUML against twelve existing tools across seven market segments, with a feature matrix and an honest section on where the competition is genuinely strong.

Irakli Betchvaia — Senior Software Architect at Keysight Technologies, building kUML in the evenings and weekends. GitHub: kuml-dev/kUML. Questions, criticism, and "you missed tool X" emails welcome at irakli@kuml.dev.