Getting started
umlimator draws layered architecture maps and 28 diagram types from one JSON model. You can use it three ways:
- as an ES module that any page embeds (
render(), or the<umlimator-map>element); - as a CLI that writes a self-contained HTML page, still pictures (SVG, PNG) and a PDF;
- as a GitHub Action that posts what a pull request changes in your maps.
This page takes you from nothing to a map in a page.
Install
npm install umlimatorOr from GitHub, at a tag or any commit: "umlimator": "github:zintaen/umlimator#v0.44.0". npm 12 refuses git dependencies unless the project opts in, so that also needs allow-git=root in the .npmrc next to package.json.
Without a bundler, load the module from a CDN, pinned to a version:
<script type="module">
import { render } from 'https://cdn.jsdelivr.net/npm/umlimator@0.44.0/lib/umlimator.js';
</script>The CLI is umlimator.py in the repository. It needs Python 3.9+ (standard library only), Google Chrome or Chromium for pictures and checks, and Node 18+ for diff, drift, trace and mcp (Command line):
git clone --depth 1 --branch v0.44.0 https://github.com/zintaen/umlimator.git
python3 umlimator/umlimator.py render model.json --out page.htmlA first model
A model has cards (nodes), lines (edges) and views, each of which shows some of them. Save this as model.json:
{
"title": "Bookshop",
"nodes": [
{ "id": "web", "label": "Web shop", "kind": "frontend" },
{ "id": "api", "label": "Orders API", "kind": "backend" },
{ "id": "db", "label": "Orders", "kind": "database" }
],
"edges": [
{ "id": "e1", "from": "web", "to": "api", "label": "places orders" },
{ "id": "e2", "from": "api", "to": "db", "label": "writes", "kind": "state" }
],
"views": [
{ "id": "overview", "parent": null, "title": "Bookshop", "nodeIds": ["web", "api", "db"] }
]
}The layout is automatic: you name what is connected, umlimator places the cards and routes the lines. The same model always gives the same picture. The model lists every field.
Draw it
In a page, with a script
import { render } from 'umlimator';
import 'umlimator/theme.css';
const model = await (await fetch('model.json')).json();
render(document.getElementById('map'), model); // give #map a heightIn a page, with no script of your own
<link rel="stylesheet" href="node_modules/umlimator/lib/umlimator-theme.css">
<script type="module" src="node_modules/umlimator/lib/umlimator-element.js"></script>
<umlimator-map src="model.json" height="480"></umlimator-map>As a file to open or share
python3 umlimator.py render model.json --out page.html # the interactive page, then its layout check
python3 umlimator.py stills page.html --out stills/ # every view as SVG and PNGThe page works offline from a single file.
Next steps
| To | Read |
|---|---|
| give the map layers, boxes and drill-down | Views and layers |
| embed it in React, or in a docs site | Embedding |
| draw a UML, C4, BPMN, SysML or cloud diagram | The model, and the conformance notes |
| let people edit the map | Editing |
| tell a story, add lenses, show live traffic | Stories, lenses and live data |
| see what a pull request changes | GitHub Action and diff |
| bring in a diagram you already have | Import and export |
The examples show every diagram type, and the Atlas, in working models; In an app shows the module in host pages.