ArchiMate® diagrams as code with Mermaid

Berny0x — Sat, 14 Nov 2026 11:22:45 +0000

Developers already have text formats for nearly every diagram: flowcharts, sequence diagrams, ER diagrams, C4. They write them in Markdown, review them in pull requests, and the docs site renders them.

Enterprise architects mostly don't have that. ArchiMate®, the standard modelling language for enterprise architecture, lives in desktop tools. The diagrams leave those tools as PNG screenshots, which drift out of date the day after they're pasted into a wiki.

Archimaid brings ArchiMate 3.2 to Mermaid. You write a diagram as text, a Mermaid plugin draws it in standard ArchiMate notation, and a CLI checks it in CI.

This post covers:

A 60-second ArchiMate primer
Your first diagram
Relationships and the connector shorthand
Layouts, nesting, notes and links
Integrating it into a site, a docs pipeline and CI
Letting an AI assistant write the diagrams

Try every snippet as you read: try.archimaid.org is a browser playground with live rendering and inline errors. You don't need to install anything.

ArchiMate in 60 seconds

ArchiMate describes an organisation in layers:

Strategy: capabilities, value streams, resources
Business: actors, roles, processes, services, business objects
Application: components, services, data objects
Technology: nodes, devices, system software, networks
Physical: equipment, facilities, materials
Implementation & Migration: work packages, plateaus, gaps
Motivation sits alongside all of these: stakeholders, goals, requirements, principles

Every element has an exact type, and every type has a standard symbol. A business process is a rounded yellow box with an arrow icon. An application component is a blue box with the component icon. Typed relationships connect the elements: serving, realization, assignment, access, triggering, flow and a few more. Each has its own line style.

That precision is what makes ArchiMate useful. "The order service serves the fulfilment process" means something different from "the order service realizes it". It's also why a generic box-and-arrow tool falls short.

Your first diagram

Install the package:

npm install archimaid mermaid

A diagram starts with the archimate-beta header. Each line declares one element or relationship:

archimate-beta
  direction LR
  accTitle: Order fulfilment responsibilities

  element businessRole clerk "Fulfilment clerk"
  element businessProcess fulfil "Fulfil order"
  relationship assignment clerk_to_fulfil clerk -> fulfil

The parts of an element declaration are:

element is the keyword
businessRole is the ArchiMate type (all 60 types use camelCase keys)
clerk is a stable ID that you reference later
"Fulfilment clerk" is the label shown in the diagram

The relationship line reads as the clerk is assigned to the fulfil process. accTitle gives the SVG an accessible name. Use it.

Misspell a type and the validator suggests the closest match:

npx archimaid validate diagram.mmd
# diagram.mmd:5:11: Unknown element type "businesProcess". Did you mean "businessProcess"?

Relationships: long form and shorthand

The long form, relationship <type> <id> <source> -> <target>, is explicit and gives the relationship an ID you can reference. Most of the time you'll want the shorthand instead. It's modelled on Mermaid's own connectors:

archimate-beta
  direction LR
  element businessProcess fulfil "Fulfil order"
  element applicationComponent oms "Order management system"
  element applicationFunction manage "Manage orders"
  element applicationService orders "Order management"
  element dataObject order "Order record"

  oms @==> manage
  manage ..|> orders
  orders --> fulfil
  manage <.. order

Read it left to right. The left endpoint is always the source in the model:

Relationship	Shorthand	Reads as
Composition	`a *-- b`	a is composed of b
Aggregation	`a o-- b`	a aggregates b
Assignment	`a @==> b`	a is assigned to b
Realization	`a ..\	> b`
Serving	`a --> b`	a serves b
Access (read / write / both)	`a <.. b` / `a ..> b` / `a <..> b`	a reads / writes / reads and writes b
Influence	`a -.-> b`	a influences b
Association	`a --- b` (or `a --/ b` when directed)	a is associated with b
Triggering	`a ==> b`	a triggers b
Flow	`a -.=> b`	a flows to b
Specialization	`a --\	> b`

The glyphs mirror what gets drawn. .. is dotted, -. is dashed, |> is a hollow triangle and => is a filled arrowhead. Add a visible label with : "Text":

archimate-beta
  element applicationComponent shop "Web shop"
  element applicationComponent oms "Order management"
  shop -.=> oms : "Placed orders"

manage <.. order needs a second look. The arrow points at manage, because that's how ArchiMate draws a read access, but the model still says manage reads order. The shorthand follows the picture and the model stays correct.

Layouts

Archimaid has three layouts.

layout architecture is the default. It stacks the occupied layers top to bottom (Strategy, Business, Application, Technology, Implementation & Migration), with Motivation at the top. Relationships pull connected elements towards each other. This is the layered view that architects expect.

layout framework puts the same layers in fixed columns: passive structure, behaviour and active structure from left to right, with Motivation on the right. It's useful for teaching and for full-framework overviews.

layout graph drops the layers and places elements purely by their relationships, using ELK. Writing direction TB, BT, LR or RL on its own selects it. The examples above use direction LR, so they're graph layouts.

In architecture and framework layout, relationships of the same type that leave the same element share one anchor and run as one trunk before branching. That keeps busy diagrams readable without manual routing.

Nesting, notes and links

Nest elements by declaring them inside a block:

archimate-beta
  accTitle: Order management components

  element applicationComponent storefront "Storefront"
  element applicationComponent suite "Order management suite" {
    element applicationComponent orders "Order processing"
    element applicationComponent billing "Billing"
  }

  suite *-- orders
  suite *-- billing
  storefront -.=> orders
  orders -.=> billing

  note review "Confirm retry behaviour\nwith the billing team" on suite

ArchiMate lets nesting stand in for a relationship. Because suite *-- orders is a composition from parent to child, the enclosure represents it and no line is drawn. Without such a relationship, nesting is purely visual grouping. Both are valid, and Archimaid handles both.

note ... on suite attaches a note to the top edge of the element. Leave out on for a standalone note, which can then be connected like an element.

Elements can also link to a runbook, an ADR or a wiki page:

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

Hovering shows the type, the name and the description, or the tooltip if you set one.

Putting it all together

Here's a cross-layer view of an online shop:

archimate-beta
  accTitle: Online order fulfilment
  accDescr: A fulfilment clerk runs the fulfil order process, supported by the order management system on the shop platform.

  element businessActor customer "Customer"
  element businessRole clerk "Fulfilment clerk"
  element businessProcess fulfil "Fulfil order"
  element businessService delivery "Order delivery"

  element applicationComponent oms "Order management system" {
    element applicationComponent billing "Billing"
  }
  element applicationFunction manage "Manage orders"
  element applicationService orders "Order management"
  element dataObject order "Order record"

  element node platform "Shop platform"
  element technologyService hosting "Container hosting"

  clerk @==> fulfil
  fulfil ..|> delivery
  delivery --> customer

  oms *-- billing
  oms @==> manage
  manage ..|> orders
  orders --> fulfil
  manage ..> order

  platform ..|> hosting
  hosting --> oms

Without layout or direction, this uses architecture layout. Business is on top, application in the middle and technology at the bottom. Paste it into the playground to see it, then try layout framework and layout graph on the same source.

Integrating it

In a web page with a bundler

Archimaid uses Mermaid's public registerExternalDiagrams API, so registration is two lines:

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

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

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

Without a bundler

Load both prebuilt ES modules from a CDN, and every <pre class="mermaid"> on the page renders:

<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 same approach works in any docs site where you control Mermaid's initialisation, such as a custom VitePress or Docusaurus theme, or a plain static site.

Theming

Mermaid's dark theme is supported. With theme: 'base', the diagram takes its background, line colour, text colour and font from themeVariables, so it blends in with the rest of your site. For padding, palette and row-wrapping options, register an instance from createArchiMatePlugin:

import { createArchiMatePlugin } from 'archimaid';

await mermaid.registerExternalDiagrams([
  createArchiMatePlugin({ diagramPadding: 32, background: 'transparent' }),
]);

On GitHub

GitHub ships a fixed Mermaid build and can't load external diagrams, so an archimate-beta block won't render there. The workaround: commit the .mmd source next to an exported SVG and embed the SVG.

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

![Online order fulfilment](fulfilment.svg)

Reviewers see the readable text diff, and readers see the picture.

In CI

The validator needs no browser. It reads .mmd files and the archimate-beta blocks inside Markdown, and reports Markdown line numbers:

# .github/workflows/diagrams.yml
name: Diagrams
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx --yes archimaid validate --format github docs/

--format github turns each problem into an inline annotation on the pull request. --format json is there for other tooling.

In your own tooling

archimaid/language runs anywhere Node runs, with no DOM needed:

import { validateArchiMate } from 'archimaid/language';

const { model, diagnostics } = validateArchiMate(source);
for (const d of diagnostics) {
  console.log(`${d.line}:${d.column} ${d.severity} ${d.code}: ${d.message}`);
}

Every diagnostic has a code, a severity and a start and end range, so an editor can underline the exact token. The browser playground uses this to show inline errors.

Letting an AI write it

A plain-text format with a strict validator suits language models well. They write a draft, the validator points at the line that's wrong, and they fix it.

The package includes a skill file (skills/archimaid/SKILL.md) that teaches an assistant the syntax, the 60 type keys, the connectors and the layout rules. Point Claude Code, Codex, Cursor or another skill-aware agent at it, and ask for "an ArchiMate view of how our checkout service supports the order process". You get a diagram you can validate, review and commit.

What it doesn't do (yet)

Archimaid is for authoring diagrams, not managing models. It isn't trying to replace Archi or a commercial repository. Currently out of scope:

Checking relationships against ArchiMate's Appendix B. The validator checks syntax, types, endpoints and nesting. It doesn't yet check that, say, a data object may serve a business role. This is under development and depends on permission from The Open Group to distribute the relationship table.
Junctions, relationships on relationships, alternative figures, viewpoints and model exchange.

The syntax is called archimate-beta for a reason, and feedback will shape it.

Try it

Playground: try.archimaid.org
Docs: archimaid.org
Source: github.com/Archimaid/archimaid (MIT)
npm: archimaid

If you work with ArchiMate, I'd especially like to hear where the syntax feels wrong. Open an issue or leave a comment below.

ArchiMate® is a registered trademark of The Open Group. Archimaid is an independent project, not affiliated with or endorsed by The Open Group.

DEV Community: Berny0x