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:
-
elementis the keyword -
businessRoleis the ArchiMate type (all 60 types use camelCase keys) -
clerkis 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

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.

Top comments (1)
Replacing pasted PNGs with text diagrams makes a lot of sense, since screenshots always drift. Having a CLI that validates diagrams in CI is the best part. A tip for teams adopting this: keep the diagram source next to the page that explains it, and make the CI step fail on any syntax error so a broken diagram never reaches the published site. It also helps to add a short alt text or caption sentence under each rendered diagram, so the key relationship is readable by people using screen readers or skimming search results.