PlantUML: Turn Text into Professional UML Diagrams

PlantUML is a software that transforms text descriptions, which are easy for humans to read, into UML diagrams (Unified Modeling Language).. Under the hood, PlantUML involves:

PlantUML Architecture (Design View)

Here’s a high-level component diagram of how PlantUML works:

source

@startuml

actor User

boundary Editor as "JSP + JS (UI)"

control Compiler as "PlantUML Compiler"

entity Diagram as "Generated Diagram (PNG/SVG)"

User --> Editor : Write UML Code

Editor --> Compiler : POST UML Source

Compiler --> Diagram : Generate PNG/SVG

Editor <-- Diagram : Display Output

@enduml

PlantUML: Turn Text into Professional UML Diagrams

You can render this in your editor too.

Behind the Scenes (How PlantUML Works)

Input: Text DSL

plantuml

@startuml

Alice -> Bob: Hello

@enduml

Steps:

Lexical Analysis (Tokenizer)
Breaks source into tokens:
@startuml, Alice, ->, Bob, :, Hello, @enduml
Parsing (Grammar-based)

Converts tokens to an AST (Abstract Syntax Tree)
Example:

yaml

Diagram {

Participants: [Alice, Bob]

Arrows: [Alice -> Bob: Hello]

}

Semantic Validation

Ensures elements like Alice, Bob are valid actors
Checks for missing @enduml, cycles, lifelines

Layout Engine

Positioning of elements (boxes, arrows, etc.)
Uses:

GraphViz (Dot) for complex layouts
Custom heuristics for sequence diagrams

Rendering Engine

Renders to:

PNG, SVG, EPS, or ASCII art

Fonts, sizes, arrow heads, spacing controlled via style

Math Behind PlantUML

Understanding the math behind PlantUML means diving into the graph theory, layout algorithms, and geometry that allow it to convert text into diagrams. While PlantUML itself is a high-level tool, it relies heavily on formal mathematical principles—especially when rendering complex diagrams.

1. Lexical & Syntax Analysis (Formal Language Theory)

Input: A text description of a diagram using a Domain-Specific Language (DSL)
Step: Parsed into tokens using finite automata and context-free grammars(CFG)
Tools: Uses a recursive-descent parser to form an Abstract Syntax Tree (AST)

Mathematical Concepts:

Regular expressions and BNF (Backus-Naur Form) for syntax rules
Parse Trees represent hierarchical structure

2. Graph Theory for Layout

PlantUML transforms parsed entities into nodes and edges in a graph, then computes their positions using layout algorithms.

A. Graph Layout Algorithms

PlantUML integrates Graphviz, which uses several layout strategies:

Layout	Algorithm	Purpose
dot	Sugiyama Layout Algorithm	Directed graphs, layered (used in class/activity diagrams)
neato	Spring-force / Force-directed	Natural-looking layout (undirected)
circo	Circular Layout	Circular dependencies
twopi	Radial Layout	Hierarchical, from a center node

Example:

For a simple graph:

text

A --> B

B --> C

A --> C

Graph:

Vertices V = {A, B, C}
Edges E = {(A,B), (B,C), (A,C)}

PlantUML:

Constructs a Directed Acyclic Graph (DAG)
Applies topological sorting
Assigns layer numbers (Y-axis) and spacing (X-axis)

3. Force-Directed Layout (Spring Algorithm)

This is often used for network-style diagrams.

Force Calculations:

Each node repels others with a Coulomb force:

$$F_{repel} = \frac{k^2}{d}$$

Each edge acts like a spring:

$$F_{spring} = k \cdot (d - L)$$

Where:

k = spring constant
L = ideal length
d = current distance between nodes

Iterative optimization continues until forces stabilize (equilibrium).

4. Geometry for Drawing

A. Coordinate Computation:

For sequence diagrams, actors are laid out at constant intervals along X-axis.
Messages are arrows at increasing Y-axis positions.

B. Bounding Box Math:

Each element has:

width, height → derived from font size & content
x, y → relative coordinates
Collisions avoided by solving spacing constraints

C. Arrow Drawing:

If drawing an arrow from (x1, y1) to (x2, y2), use:

Vector math
Label positioning = midpoint + offset
Arrowhead geometry = triangle of fixed angle

5. Timing Logic Diagram

Every digital signal or timeline signifies a step function in the context of discrete time.

plantuml

@startuml

robust "Sensor KCM A" as A

A is High

@1 A is Low

@2 A is High

@enduml

Mathematically:

Discrete time values → t ∈ ℕ
Value function V(t) = {High, Low}
Drawn as stepwise lines using interval mapping

6. Constraint Solving for Layout

Internally, layout is often treated as a constraint satisfaction problem (CSP):

Constraints like:

"No overlap"
"Arrows should not cross unnecessarily"
"Minimum spacing"

Solved with:

Linear programming
Constraint propagation
Greedy heuristics

Summary of Mathematical Foundations

Area	Math Involved	Example in PlantUML
Syntax Parsing	Formal grammar and automata	DSL → AST
Graph Layout	Graph theory and directed acyclic graphs (DAGs)	Class and activity diagrams
Force-directed methods	Physics simulation and optimization	Network layouts
Geometry	Euclidean geometry or Pythagorean theorem and vectors (a measurement or a quantity that has both size and direction)	Positioning and arrows(Arrows generally indicate direction or position, while positioning refers to how something is placed or situated)
Timing Diagrams (a graphical representation that depicts the changes in signal states or values over time)	Discrete math and step functions or flip flop (SR, JK, D, T)	State over time
Constraint Solving	Linear algebra and heuristics	Collision-free layouts

Diagram Types Supported

Type	Math/Engine
Class Diagram	Inheritance trees → graph theory
Sequence Diagram	Lifeline + time axis (Y-axis increment)
Activity Diagram	Flowchart logic → graph layout
Component Diagram	Box-based layout
State Diagram	FSM → nodes + transitions
Timing Diagram	Time axis + discrete state transitions

To build a PlantUML editor in local using JavaScript and html, follow this design:

✅ Features:

Local UI with a code editor (using CodeMirror or a <textarea>)
Real-time or manual rendering of PlantUML diagrams
Local server-side JSP that uses PlantUML jar to generate image from .puml source
Download/export rendered diagram as PNG