kUML

Architecture that compiles.
One source. Any diagram. Readable for humans and AI.

Website: https://kuml.dev · Handbook: https://docs.kuml.dev · Releases: https://github.com/kuml-dev/kUML/releases

kUML is a modelling tool that expresses UML 2.x, SysML 2, C4, BPMN 2.0 and ERM as a type-safe Kotlin DSL — the first UML tool deliberately designed for the LLM era.

Table of Contents

• Why kUML?
  • The two empty spaces nobody is filling
• Quick Start
• Animated Diagrams
  • UML Sequence — message-dot animation
  • UML State Machine — state-highlighting animation
  • BPMN Process — token animation
• Installation
• What is in the box
• Supported notations
• Essential commands
• Documentation
• Contributing
• License

Why kUML?

Modeling deserves a compiler.

Every feature in kUML exists in some tool on the market. The specific combination does not exist anywhere else: type-safe Kotlin DSL · UML 2.x + SysML 2 + C4 + BPMN 2.0 + ERM as first-class peers · executable behaviour runtime · LLM-first design · Apache 2.0.

Existing UML tools fall into two categories:

• Graphical CASE tools (Enterprise Architect, MagicDraw) — proper modelling, but expensive and not Git-friendly.

• Text-based diagram tools (PlantUML, Mermaid) — versionable, but drawing tools only with weak UML support.

kUML closes this gap: a real modelling tool, expressed as Kotlin source code, fully versionable in Git, and built from the ground up for LLM-assisted workflows.

The two empty spaces nobody is filling

There are dozens of UML, SysML and architecture tools. None of them fill these two quadrants:

1. No serious modelling tool runs on a typed host language. There are Python diagram libraries, Java APIs around EMF, custom text grammars by the dozen. There is no mature tool that treats the model as ordinary code in a modern, statically-typed language with IDE refactoring, compile-time checking, and natural build-system integration. kUML uses Kotlin’s type-safe builders because they are the cleanest fit available — the principle, not the language choice, is the point.

2. No tool is designed for the LLM era. PlantUML and Mermaid happen to be LLM-friendly because they have enormous training footprints. That is luck, not design. kUML is built for AI-assisted modelling on purpose: type-safe output that compiles or fails fast, consistent named parameters, an MCP server for agent introspection, a kuml ai subcommand, and a benchmark that measures how often LLM-generated models actually validate.

Quick Start

// order-domain.kuml.kts — no imports needed, kUML scripting host provides them
classDiagram(name = "Order Domain") {
    val status = enumOf(name = "OrderStatus") {
        literal(name = "DRAFT")
        literal(name = "CONFIRMED")
        literal(name = "SHIPPED")
        literal(name = "CANCELLED")
    }

    val order = classOf(name = "Order") {
        attribute(name = "id", type = "UUID")
        attribute(name = "status", type = status)        // enum val used as attribute type
        operation(name = "confirm")
        operation(name = "cancel")
    }

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

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

kuml render order-domain.kuml.kts --format svg

That command produces the diagram below — rendered straight from the script above with ELK Sugiyama layout and the kUML theme:

Animated Diagrams

kUML renders pure SMIL SVG animations directly from execution traces — no JavaScript, no GIF conversion. Pass --animated on the CLI (or use a kuml-animated code block in Obsidian) and supply a kuml.trace.v1 JSON trace. Any browser that supports SVG SMIL plays them inline.

For sharing outside the browser, animated SVGs can also be exported to Animated PNG (--format=apng, no external dependency), Animated WebP (--format=webp, requires img2webp or ffmpeg on PATH), or MP4 (--format=mp4, requires ffmpeg on PATH, encoded as H.264/yuv420p). MP4 does not support a transparent background — use APNG or WebP instead when transparency is required.

UML Sequence — message-dot animation

An animated sequenceDiagram (Place Order happy path). A blue dot glides along each arrow in declaration order: submitOrder() → POST /orders → INSERT order → ok → 201 Created → confirmation. Rendered by SequenceSmilRenderer.

UML State Machine — state-highlighting animation

An animated stateDiagram (Traffic Light, two full cycles). The active state highlights in amber; all others remain passive. Rendered by StmSmilRenderer.

BPMN Process — token animation

An animated bpmnModel (PdV membership application). A token travels along BPMN sequence flows and a stroke-width pulse highlights each active task. Rendered by BpmnSmilRenderer.

Installation

Method	Command / Link
Homebrew (macOS/Linux)	brew install kuml-dev/kuml/kuml
Homebrew Cask (macOS desktop app)	brew install --cask kuml-dev/kuml/kuml-desktop
Chocolatey (Windows)	choco install kuml — bundles a Java 21 runtime, no JDK needed.
Docker	docker pull ghcr.io/kuml-dev/kuml-cli:<version> — minimal CLI image.
Native installers and runtime bundles	DMG, MSI, DEB, RPM and self-contained ZIPs on the GitHub Releases page.
Maven Central (library modules)	implementation("dev.kuml:kuml-core-dsl:<version>") — use the version shown in the badge above.

SDKMAN! is built but not live yet (vendor onboarding is pending). The full guide, including the Gradle plugin, the JetBrains plugin, the VS Code extension and building from source, is in Installation.

What is in the box

• One DSL, five notations. UML 2.x, SysML 2, C4, BPMN 2.0 and ERM are first-class peers, plus user journey maps and service blueprints.

• Real metamodel. A pure-Kotlin sealed hierarchy, no EMF in the core; XMI interop is an optional module.

• OCL and typed expressions. Constraints are evaluated directly on the model, kuml validate --strict type-checks guards and effects.

• Executable behaviour. Simulate and run state machines, activities and BPMN processes (kuml simulate, kuml run), with snapshot/restore and OTLP trace export.

• Model-driven architecture. M2M transformers and code generators for Kotlin, Java/JPA, SQL, Exposed, OpenAPI, Kubernetes and Docker; reverse engineering from Java, Kotlin and SQL.

• Built for the LLM era. Named parameters, a canonical formatter, structured diagnostics, an MCP server and a kuml ai toolbox with a benchmark.

• Where you work. CLI, Gradle plugin, JetBrains plugin, VS Code extension, a Compose Desktop app, a browser editor (kuml serve), Markdown (also via a Pandoc filter), AsciiDoc/Antora and Obsidian (obsidian-kuml).

• Chain-backed models. Connect behaviour models to EVM, CosmWasm, ink! and Move contracts (see Chain Adapters).

• Interop. Structurizr DSL, XMI, AUTOSAR ARXML and BPMN XML in and out; five built-in UML profiles (AUTOSAR, JavaEE, Spring, OpenAPI, SoaML).

• Extensible. A signed plugin system for themes, renderers, layout engines, generators and reverse engines.

Supported notations

Notation	Diagram types	Reference
UML 2.x	14	UML DSL
SysML 2	8	SysML 2 DSL
C4	6	C4 DSL
BPMN 2.0	process, collaboration, choreography, conversation	BPMN DSL
ERM	4 notations (Martin, Bachman, Chen, IDEF1X)	ERM DSL
Service blueprint	user journey maps	User Journey Maps

How kUML compares with PlantUML, Mermaid, D2, Structurizr and the big CASE tools, including where those tools are the better choice, is in How kUML compares. A shorter table is on kuml.dev/comparison.

Essential commands

kuml render model.kuml.kts            # SVG (also --format png|latex)
kuml watch model.kuml.kts             # re-render on every save
kuml validate model.kuml.kts          # OCL constraints (add --strict for typed expressions)
kuml fmt model.kuml.kts               # canonical formatting (--check for CI)
kuml generate --plugin kotlin ...     # code generation (kotlin, java, sql, exposed)
kuml simulate model.kuml.kts          # execute a state machine, activity or BPMN process
kuml reverse --lang kotlin ./src      # recover a class diagram from source
kuml serve                            # browser editor with live preview

All commands, options and exit codes: CLI reference.

Documentation

• Handbook — DSL reference, CLI, Gradle plugin, MDA, plugin API, and the module overview. Built with Antora from docs/handbook/ on every push to master.

• Website — playground, release notes, feature overview, comparison.

• Changelog and Roadmap.

• Quick Start, UML DSL and C4 DSL in the handbook.

• LLM Benchmark Guide.

• Release & Distribution.

Contributing

Issues and pull requests are welcome on GitHub. Building from source needs JDK 21 and, for the kuml-web frontend, Node.js ^20.19 or >=22.12 with npm (./gradlew clean check). Release binaries, Homebrew, Chocolatey and the Maven artifacts do not need Node.

License

Apache 2.0 — see LICENSE