What does archimaid do?
Archimaid adds ArchiMate 3.2 to Mermaid as the archimate-beta diagram type. Write diagrams as plain text, check them with the archimaid CLI, and render them to SVG.
Workflow
- Decide which ArchiMate elements and relationships the view needs. Model meaning with element types and relationships, not with notes.
- Write the diagram in a
.mmdfile, or in a fencedmermaidblock in Markdown. - Validate it and fix every error, then validate again:
Usenpx --yes archimaid validate path/to/diagram.mmd-to validate standard input. Problems print asfile:line:column: message. Warnings start withwarning:and don't fail the run. - Check that ArchiMate 3.2 permits each relationship between its source and target types (Appendix B). The validator doesn't check this yet.
- Render an SVG when the target host can't load the plugin, such as GitHub Markdown (see Rendering).
Syntax
Start with archimate-beta and put one declaration on each line.
archimate-beta
direction LR
accTitle: Order management
accDescr: The order management suite contains a billing component.
element applicationComponent suite "Order management suite" {
element applicationComponent billing "Billing"
}
description billing "Handles invoicing."
click billing href "https://wiki.example.com/billing" "Open the billing runbook"
suite *-- billing
note review "Confirm retry behaviour" on suite
- Elements:
element <type> <id> "Name". The 60 type keys (businessProcess,applicationComponent,node, …) are listed in references/reference.md. Read it whenever you're unsure of a key. - IDs: unique, start with a letter or underscore, and contain letters, digits, underscores and hyphens.
- Strings: JSON-style double quotes, never empty. Use
\nfor a line break. Long names wrap automatically. - Accessibility: always add
accTitle:. AddaccDescr:, oraccDescr { … }for several lines. - Frontmatter: a leading YAML block between
---lines is allowed, for exampleconfig: { theme: dark }.
Relationships
Shorthand: <source> <connector> <target>, with an optional : "Label". The left endpoint is always the model source.
| Connector | Relationship |
|---|---|
*-- | composition |
o-- | aggregation |
@==> | assignment |
..|> | realization |
--> | serving |
.. / <.. / ..> / <..> | access: unspecified / read / write / readWrite |
-.-> | influence |
--- / --/ | association: undirected / directed |
==> | triggering |
-.=> | flow |
--|> | specialization |
manage <.. ordermeans manage reads order: the accessor is on the left.- An ID at the start of a statement is never read as the
o--glyph. Writeo o-- b, noto--b. - Don't repeat an identical shorthand line.
- Long form:
relationship <type> <id> <source> -> <target>, optionally followed byaccess read|write|readWrite|unspecifiedordirected, thenlabel "Text". Use the long form when another declaration must reference the relationship's ID.
Nesting
- Declare children inside
element … {and}, each on its own line. Blocks nest and can hold elements, descriptions, relationships, notes,nestandclick, but not diagram settings. - Nesting needs no relationship. When exactly one parent-child relationship supports nesting, the enclosure represents it and its line is hidden. Composition, aggregation, assignment, realization and access point from parent to child. Specialization points from child to parent.
nest <child> in <parent> [via <relationshipId>]is the line form. Useviawhen several relationships could support the nesting. Each child has one visual parent, and nesting must not form a cycle.
Notes and links
note <id> "Text"declares a standalone note. Appendon <elementId>to attach it to an element. Notes can be relationship endpoints.click <id> href "<url>" ["Tooltip"] [_blank|_self|_parent|_top]links an element. URLs must be http, https, mailto or relative. Without a tooltip, hovering shows thedescription.
Layout
- Default, or
layout architecture: layers top to bottom (Strategy, Business, Application, Technology and Physical, Implementation & Migration), with Motivation at the top near what it connects to. Prefer this for cross-layer views. layout framework: the same layers, with fixed Passive Structure, Behavior and Active Structure columns and Motivation on the right.layout graph, ordirection TB|BT|LR|RLon its own: relationship-driven placement. Prefer this for small single-layer views and chains.
Out of scope
Junctions, relationships as endpoints, alternative figures, viewpoints and model exchange aren't supported. Don't invent syntax for them. Say so and use the closest supported construct.
Rendering
Rendering needs Playwright Chromium in the project:
npm install --save-dev archimaid mermaid playwright
npx playwright install chromium
npx archimaid render diagram.mmd diagram.svg --theme default --background theme
For hosts that don't register the plugin (GitHub, GitLab), commit the .mmd source next to the SVG and embed the SVG: .
For a web page, register the plugin with Mermaid 12.3 or later:
import mermaid from 'mermaid';
import { archimate } from 'archimaid';
mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
await mermaid.registerExternalDiagrams([archimate]);
To check syntax quickly with the user, point them at the browser playground: https://try.archimaid.org
Examples
references/examples.md has three complete, valid diagrams:
- Order management: assignment, realization, serving and read access
- Cross-layer relationships: architecture layout with nested claims processing
- Nested components: composition, attached and standalone notes, cross-boundary flows