Skip to content
ArchimaidPublic

About

ArchiMate® diagrams as code for Mermaid. Write, validate and render enterprise architecture views in plain text.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

8 stars

Watchers

1 watching

Forks

Repository files navigation

Archimaid

Mermaid diagrams for ArchiMate® 3.2. Enterprise architecture diagrams as code.

npm version MIT license Node.js 22.12 or later Mermaid 12.3 or later ArchiMate 3.2

Archimaid lets you write ArchiMate® 3.2 diagrams in plain text, validate their structure in CI, and render them as SVG. This independent Mermaid plugin includes 60 element types, 11 relationship types, nesting, notes, and element links. The archimate-beta syntax is experimental.

Try it without installing anything in Archimaid Designer, a drag-and-drop editor in the browser that writes the text for you.

Automatic relationship checks against ArchiMate 3.2 Appendix B are under development. Their release depends on permission from The Open Group to distribute the relationship lookup.

Application components and services supporting an order fulfilment process

Quick start · Examples · Host integration · Language API · Coverage · Development · Support · Sources

Quick start

Use Node.js 22.12 or later and Mermaid 12.3 or a later 12.x release.

npm install archimaid mermaid
npx archimaid validate docs/

archimaid validate accepts files, directories and - for standard input. It checks .mmd files and the archimate-beta diagrams in fenced mermaid code blocks of Markdown files, and reports Markdown line numbers. In a directory it skips Mermaid files of other diagram types. It prints every problem as file:line:column: message, suggests the closest valid keyword for a misspelt type, and prefixes warnings, such as a repeated shorthand relationship, with warning:. It exits with status 1 if there is any error, and with status 0 if there are only warnings. Use --format json for machine-readable output, or --format github for annotations in a GitHub Actions log.

To render a standalone SVG, install Playwright and its Chromium browser.

npm install --save-dev playwright
npx playwright install chromium
npx archimaid render diagram.mmd diagram.svg

archimaid render accepts --theme default|base|dark|forest|neutral and --background theme|transparent. Run npx archimaid --help for all options.

Examples

A diagram starts with archimate-beta. Give each element a stable ID, then connect elements by their IDs.

archimate-beta
  direction LR
  accTitle: Order fulfilment responsibilities
  accDescr: A fulfilment clerk is assigned to the fulfil order process.

  element businessRole clerk "Fulfilment clerk"
  element businessProcess fulfil "Fulfil order"
  clerk @==> fulfil

Add element details with description elementId "Text".

Relationships

Write source <connector> target to declare a relationship. Add : "Text" for a visible label. The left endpoint is always the model source, so manage <.. order means manage reads order. The connector mirrors the rendered markers.

Relationship Connector Long form equivalent
Composition a *-- b relationship composition id a -> b
Aggregation a o-- b relationship aggregation id a -> b
Assignment a @==> b relationship assignment id a -> b
Realization a ..|> b relationship realization id a -> b
Serving a --> b relationship serving id a -> b
Access a .. b relationship access id a -> b
Access, read a <.. b ... a -> b access read
Access, write a ..> b ... a -> b access write
Access, read/write a <..> b ... a -> b access readWrite
Influence a -.-> b relationship influence id a -> b
Association a --- b relationship association id a -> b
Association, directed a --/ b ... a -> b directed
Triggering a ==> b relationship triggering id a -> b
Flow a -.=> b relationship flow id a -> b
Specialization a --|> b relationship specialization id a -> b

.. is a dotted line and -. a dashed one. > is an open arrowhead, => a filled one, |> a hollow triangle, and / the single barb of a directed Association. Shorthand relationships receive generated IDs of the form source__type__target. Use the long form, relationship <type> <id> <source> -> <target>, when you want to choose the ID, for example to name the relationship in nest child in parent via id. In the long form, a visible label is written as label "Text" after the endpoints and options.

Example What it shows Files
Order fulfilment A Business Role assigned to a Business Process Source
Order management Assignment, Realization, Serving, and read Access Source · SVG
Cross-layer relationships Architecture layout with Business, Application, and Technology rows and nested claims processing Source · SVG
Nested components Composition shown as containment, edges crossing the boundary, and notes Source · SVG
Custom layout Pinned positions, a nested element and a relationship anchored to chosen sides Source · SVG
Notation sheet The element catalogue and examples of every relationship, including Access and Association variants SVG

Choose a layout

Architecture layout is the default when you omit both layout and direction. Use layout architecture to select it explicitly. It orders occupied layers from top to bottom as Strategy, Business, Application, Technology (including Physical), and Implementation & Migration. Relationships guide the placement of connected elements within and across layers. Motivation sits at the top, near the chains it connects to.

Use layout framework to arrange the same layers in fixed aspect columns. Passive Structure, Behavior, and Active Structure run from left to right, with Motivation on the far right. Only occupied rows and columns take up space.

In architecture and framework layout, relationships of the same type that leave or arrive at the same element share one anchor and run as one line until they branch to their other ends. Access relationships bundle only with the same access mode, and directed Associations only with directed ones. A bundle splits by direction: elements directly above or below get a straight line from that side, and the rest share a trunk from the left or right side. Each relationship type gets its own anchor, and anchors are ordered so that trunks nest without crossing. Branch points are plain line joins, not ArchiMate junctions. Self-relationships and relationships of notes are never bundled.

Architecture and framework layouts preserve nesting. A parent with its own layer determines the placement of its container. Groups without their own layer that contain elements from multiple layers are placed separately.

Use layout graph for a relationship-driven layout. Graph layout accepts direction TB, BT, LR, or RL, and defaults to TB. A direction declaration on its own selects graph layout. An explicit layout declaration takes precedence.

Pin elements with custom layout

Use layout custom to place elements yourself, for example to follow your own modelling conventions. Describe the layout in one positions block, conventionally at the end of the diagram, so readers and AI agents can skip it. Archimaid still routes every relationship.

archimate-beta
  layout custom

  element businessRole clerk "Fulfilment clerk"
  element businessProcess fulfil "Fulfil order"
  element applicationService orders "Order service"
  element applicationComponent oms "Order management" {
    element applicationComponent billing "Billing"
  }
  clerk @==> fulfil
  orders --> fulfil
  oms ..|> orders

  positions {
    clerk at 0 0
    fulfil at 10 0 size 9x3
    orders at 10 8
    oms at 8 14
    billing at 1 0
    orders --> fulfil from T to B
  }
  • id at x y pins an element or a standalone note. Coordinates are whole grid units of 20 pixels from the top-left corner of the diagram to the top-left corner of the element. A nested element is positioned relative to the content area of its parent, so moving a parent moves its children.
  • size 9x3 sets a minimum width and height in grid units. Without it, an element gets its measured size rounded up to whole grid units; the smallest element is 7x3. Elements never clip their names, and a parent always grows to enclose its children.
  • source connector target from T to B, or relationshipId from T to B, chooses the side where a relationship leaves its source and enters its target: T, R, B or L. Either side may be left out. An anchored relationship is not bundled with others.
  • Elements without a position are placed by architecture layout, below the positioned elements or inside their positioned parent, and the validator warns about each one. Without a positions block, custom layout places the whole diagram like architecture layout.
  • A position or anchor that refers to an undeclared ID is ignored with a warning, so deleting an element never breaks the diagram. Keep elements that are not nested at least 2 grid units apart; the validator warns when they are closer.
  • Other layouts ignore the positions block but still check it, so switching between layout custom and an automatic layout is a one-line change. Positions are an Archimaid extension and not part of Mermaid.

Nest elements and add notes

Declare elements inside an element's block to draw them inside it. Blocks can be nested.

archimate-beta
  element applicationComponent suite "Order management suite" {
    element applicationComponent billing "Billing"
    element applicationComponent orders "Orders"
  }
  suite *-- billing

  note review "Confirm retry behaviour" on suite

Nesting does not need a relationship. When exactly one relationship between parent and child supports nesting, as suite *-- billing does here, the enclosure represents that relationship and its line is not drawn. Without such a relationship, as for orders, the nesting only groups the child visually. With several, name the intended one: declare the child outside the block and write nest child in parent via relationshipId. nest child in parent without via works like a block.

Nesting supports Composition, Aggregation, Assignment, Realization, and Access from parent to child. For Specialization, the child specializes its parent. Each child has one visual parent, and nesting must not form a cycle. The renderer still draws the line of a nesting relationship that carries a label or an explicit read/write mode. A block holds elements, descriptions, relationships, notes, nest and click declarations; diagram settings such as direction stay at the top level. ArchiMate 3.2 specification, §§3.8, 5.1, 5.2.2, and 5.4.1

Use note id "Text" for a standalone note or note id "Text" on elementId to attach it to an element's top edge (its bottom edge in direction BT, so relationships leaving upward stay clear of it). Notes are diagram annotations and can be endpoints of the supported relationship types. Use \n for a line break.

Links and tooltips

Hovering an element shows its type and name, followed by its description. Use click to link an element to a page, with an optional tooltip that replaces the description and an optional target.

archimate-beta
  element applicationComponent billing "Billing"
  description billing "Handles invoicing."
  click billing href "https://wiki.example.com/billing" "Open the billing runbook" _blank

The link accepts http, https and mailto URLs, and relative URLs. The target is one of _blank, _self, _parent or _top. Mermaid removes the target unless securityLevel is 'loose', so with the default 'strict' level the link opens in the same tab. Links only work where the SVG is shown inline or opened directly; GitHub Markdown and <img> tags do not follow them.

Host integration

Add a <div id="diagram"></div> to your page and run this module through your JavaScript bundler.

import mermaid from 'mermaid';
import { archimate } from 'archimaid';

mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
await mermaid.registerExternalDiagrams([archimate]);

const source = `archimate-beta
  direction LR
  element businessRole clerk "Fulfilment clerk"
  element businessProcess fulfil "Fulfil order"
  relationship assignment clerk_to_fulfil clerk -> fulfil`;

const { svg } = await mermaid.render('order-fulfilment', source);
document.querySelector('#diagram').innerHTML = svg;

Without a bundler, load Mermaid's and this package's prebuilt ES modules, for example from a CDN.

<pre class="mermaid">
archimate-beta
  element businessRole clerk "Fulfilment clerk"
  element businessProcess fulfil "Fulfil order"
  clerk @==> fulfil
</pre>
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12/dist/mermaid.esm.min.mjs';
  import { archimate } from 'https://cdn.jsdelivr.net/npm/archimaid@0/dist/bundle/archimaid.esm.min.mjs';

  mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
  await mermaid.registerExternalDiagrams([archimate]);
  await mermaid.run();
</script>

The bundle is also exported as archimaid/bundle. It includes the parser and renderer, and loads ELK from a separate file only when a layout graph diagram is rendered.

Live rendering requires a host that registers the external diagram. For GitHub Markdown, commit the .mmd source alongside its exported SVG and link to the SVG with ![Diagram title](order-fulfilment.svg). This keeps the model reviewable in Git and the image visible to readers. Mermaid external diagram API

The standalone validator skips a leading YAML frontmatter block that starts and ends with a --- line, and it reports line numbers for the whole file. It does not read the frontmatter's content, so use the DSL's title:, accTitle:, and accDescr: declarations for metadata the validator should check. Use accDescr { … } for a description that spans several lines, and do not combine it with accDescr:. A %% that follows a space ends a title:, accTitle: or accDescr: value as a comment. To keep it, or to use escapes such as \u0025, write the whole value as one double-quoted string, for example title: "Load %% budget". To show a Mermaid directive as literal text in a quoted label, escape its percent signs as \u0025.

Theme, palette, and viewport

The ArchiMate palette controls element colours and is selected independently of the Mermaid theme. Modern is the default and currently available palette. Classic and New are planned as separate palettes.

Light and dark diagrams share the same element fills. Dark mode draws relationship lines and markers in white. Set theme: 'dark' when initializing Mermaid, or set config.theme in Mermaid YAML frontmatter for an individual diagram.

---
config:
  theme: dark
---
archimate-beta
  element applicationComponent billing "Billing"

With theme: 'base', the diagram reads background, lineColor, textColor, fontFamily and fontSize from themeVariables, so its canvas, font and font size follow Mermaid's base theme instead of the ArchiMate presets. The background may be any CSS colour, including named colours and colours with an alpha channel. Dark mode follows themeVariables.darkMode, or the brightness of background when darkMode is not set. A transparent, partly transparent or unrecognised background keeps the ArchiMate light or dark preset for both the canvas and the lines and text. Line and text colours that would be unreadable on the background are replaced by the preset colours. fontFamily accepts family names made of letters, digits, spaces, hyphens and underscores, separated by commas and optionally quoted. fontSize is limited to 8–32 pixels. Other themes use the ArchiMate light or dark presets.

The archimate export uses the Modern palette and 24 pixels of outer diagram padding. It fits narrow containers up to the SVG's natural width. To set palette and viewport options, register an instance from createArchiMatePlugin.

import mermaid from 'mermaid';
import { createArchiMatePlugin } from 'archimaid';

mermaid.initialize({ startOnLoad: false, securityLevel: 'strict', theme: 'dark' });
await mermaid.registerExternalDiagrams([
  createArchiMatePlugin({ palette: 'modern', diagramPadding: 32, useMaxWidth: true }),
]);

diagramPadding accepts any finite, nonnegative number. useMaxWidth defaults to true. Set it to false to render the SVG at its natural size.

maxRowWidth sets the widest row, in pixels, that architecture layout places before wrapping a row onto a second line in the same layer. It accepts any number greater than 0 and defaults to 1200. Set it to Infinity to turn wrapping off.

background is 'theme' (default), which paints the diagram canvas in the theme background, or 'transparent', which omits the canvas so the host page shows through. Relationship labels and hollow markers keep the theme background in both cases.

Element names wrap at about 200 pixels and relationship labels at about 180 pixels. ELK, which lays out layout graph diagrams, loads on demand the first time one is rendered.

Language API

Use the language entry point to validate or inspect a diagram in Node.js without a browser.

import { readFile } from 'node:fs/promises';
import { parseArchiMate } from 'archimaid/language';

const source = await readFile('diagram.mmd', 'utf8');
const model = parseArchiMate(source);
console.log(model.elements);

Validation errors throw ArchiMateError with a code, line, and column. parseArchiMate stops at the first error.

For editors and linters, validateArchiMate(source, options) returns { model, diagnostics }. It reports every semantic error, and warnings such as DUPLICATE_RELATIONSHIP, each with code, severity, message, line, column, endLine and endColumn. Lines and columns are 1-based and endColumn is exclusive. model is present only when there are no errors.

The same entry point exports elementTypes, relationshipTypes and relationshipNames for tooling that needs the catalogue. Type reference

Coverage

The renderer supports the default figures for all 60 concrete elements and all 11 relationship types in the bundled catalogue. The type reference lists every element and relationship key with its name, layer and shorthand connector. Access accepts access read, access write, access readWrite, or access unspecified. Use directed for a directed Association. Notation preview

The validator checks syntax, declared endpoints, supported element and relationship types, relationship options, and nesting. Check the specification to verify which element types a relationship can connect. ArchiMate 3.2 specification, Appendix B

Junctions, relationship-to-relationship endpoints, alternative element figures, viewpoint tooling, and model exchange are outside the current scope.

Development

npm ci
npm run lint
npm test
npx playwright install chromium
npm run test:browser
npm pack --dry-run

To try an unpublished version in another project, build an archive with npm pack in the checkout and install it there.

npm install mermaid /path/to/archimaid-0.1.0.tgz

Use npm run typecheck to check TypeScript without emitting files and npm run render:preview to regenerate the notation sheet. After changing the catalogue, run npm run reference to regenerate the type reference; a test fails while it is stale. The browser tests exercise the plugin through a real Mermaid host.

See CONTRIBUTING.md for checks, conventions and how to add an element type. Report security issues as described in SECURITY.md. To generate or edit diagrams with an agent, point it to the repository skill. It covers syntax, relationship direction, and validation commands. Foundation · Agent skill

Support

Archimaid is free and built in the maintainer's own time. If it saves you time, star the repository so other architects can find it, or sponsor the project on GitHub. One-time sponsorships are welcome.

Sources

  • The Open Group's ArchiMate 3.2 specification defines the element and relationship types. Specification C226
  • The Open Group's reference cards illustrate element figures and relationship notation. Reference cards N221
  • Mermaid provides the external diagram API, and ELK provides the graph layout. Mermaid diagram guide · ELK

The plugin code is licensed under the MIT License. The maintainer uses the ArchiMate® 3.2 Specification under an ArchiMate Specification Non-Commercial License from The Open Group. That licence covers the maintainer only and does not extend to users or contributors. Archimaid is an independent project and is not affiliated with or endorsed by The Open Group. ArchiMate is a registered trademark of The Open Group in the United States and other countries.

About

ArchiMate® diagrams as code for Mermaid. Write, validate and render enterprise architecture views in plain text.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

8 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages