¿Qué hace archimaid?
Archimaid añade ArchiMate 3.2 a Mermaid como el tipo de diagrama archimate-beta. Escribe diagramas como texto plano, verifícalos con el CLI archimaid y renderízalos a SVG.
Flujo de trabajo
- Decide qué elementos y relaciones de ArchiMate necesita la vista. Modela el significado con tipos de elemento y relaciones, no con notas.
- Escribe el diagrama en un archivo
.mmd, o en un bloquemermaiddelimitado en Markdown. - Valídalo y corrige cada error, luego vuelve a validar:
Usanpx --yes archimaid validate ruta/al/diagrama.mmd-para validar la entrada estándar. Los problemas se muestran comoarchivo:línea:columna: mensaje. Las advertencias comienzan conwarning:y no detienen la ejecución. - Comprueba que ArchiMate 3.2 permite cada relación entre sus tipos de origen y destino (Apéndice B). El validador aún no verifica esto.
- Renderiza un SVG cuando el host destino no pueda cargar el plugin, como en GitHub Markdown (ver Renderizado).
Sintaxis
Empieza con archimate-beta y pon una declaración en cada línea.
archimate-beta
direction LR
accTitle: Gestión de pedidos
accDescr: El sistema de gestión de pedidos contiene un componente de facturación.
element applicationComponent suite "Suite de gestión de pedidos" {
element applicationComponent billing "Facturación"
}
description billing "Maneja la facturación."
click billing href "https://wiki.ejemplo.com/facturacion" "Abrir el manual de facturación"
suite *-- billing
note review "Confirmar comportamiento de reintentos" on suite
- Elementos:
element <tipo> <id> "Nombre". Las 60 claves de tipo (businessProcess,applicationComponent,node, …) se listan en references/reference.md. Consúltalo siempre que no estés seguro de una clave. - IDs: únicos, comienzan con una letra o guión bajo, y contienen letras, dígitos, guiones bajos y guiones.
- Cadenas: comillas dobles al estilo JSON, nunca vacías. Usa
\npara un salto de línea. Los nombres largos se ajustan automáticamente. - Accesibilidad: añade siempre
accTitle:. AñadeaccDescr:, oaccDescr { … }para varias líneas. - Frontmatter: se permite un bloque YAML inicial entre líneas
---, por ejemploconfig: { theme: dark }.
Relaciones
Taquigrafía: <fuente> <conector> <destino>, con un opcional : "Etiqueta". El extremo izquierdo es siempre la fuente del modelo.
| Conector | Relación |
|---|---|
*-- | composición |
o-- | agregación |
@==> | asignación |
..|> | realización |
--> | servicio |
.. / <.. / ..> / <..> | acceso: no especificado / lectura / escritura / lecturaEscritura |
-.-> | influencia |
--- / --/ | asociación: no dirigida / dirigida |
==> | disparo |
-.=> | flujo |
--|> | especialización |
manage <.. ordersignifica manage lee order: el accesor está a la izquierda.- Un ID al inicio de una sentencia nunca se interpreta como el glifo
o--. Escribeo o-- b, noo--b. - No repitas una línea taquigráfica idéntica.
- Forma larga:
relationship <tipo> <id> <fuente> -> <destino>, seguido opcionalmente deaccess read|write|readWrite|unspecifiedodirected, luegolabel "Texto". Usa la forma larga cuando otra declaración deba referenciar el ID de la relación.
Anidamiento
- Declara hijos dentro de
element … {y}, cada uno en su propia línea. Los bloques se anidan y pueden contener elementos, descripciones, relaciones, notas,nestyclick, pero no configuraciones del diagrama. - El anidamiento no necesita relación. Cuando exactamente una relación padre-hijo soporta el anidamiento, el contenedor la representa y su línea se oculta. Composición, agregación, asignación, realización y acceso apuntan del padre al hijo. Especialización apunta del hijo al padre.
nest <hijo> in <padre> [via <idRelacion>]es la forma de línea. Usaviacuando varias relaciones puedan soportar el anidamiento. Cada hijo tiene un padre visual, y el anidamiento no debe formar un ciclo.
Notas y enlaces
note <id> "Texto"declara una nota independiente. Añadeon <idElemento>para adjuntarla a un elemento. Las notas pueden ser extremos de relaciones.click <id> href "<url>" ["Tooltip"] [_blank|_self|_parent|_top]enlaza un elemento. Las URL deben ser http, https, mailto o relativas. Sin tooltip, al pasar el ratón se muestra ladescription.
Diseño
- Por defecto, o
layout architecture: capas de arriba a abajo (Estrategia, Negocio, Aplicación, Tecnología y Física, Implementación y Migración), con Motivación en la parte superior cerca de lo que conecta. Prefiérelo para vistas entre capas. layout framework: las mismas capas, con columnas fijas de Estructura Pasiva, Comportamiento y Estructura Activa, y Motivación a la derecha.layout graph, odirection TB|BT|LR|RLpor sí solo: colocación basada en relaciones. Prefiérelo para vistas pequeñas de una sola capa y cadenas.
Fuera del alcance
Uniones, relaciones como extremos, figuras alternativas, puntos de vista e intercambio de modelos no están soportados. No inventes sintaxis para ellos. Dilo y usa la construcción soportada más cercana.
Renderizado
El renderizado necesita Playwright Chromium en el proyecto:
npm install --save-dev archimaid mermaid playwright
npx playwright install chromium
npx archimaid render diagrama.mmd diagrama.svg --theme default --background theme
Para hosts que no registran el plugin (GitHub, GitLab), confirma el código fuente .mmd junto al SVG e incrusta el SVG: .
Para una página web, registra el plugin con Mermaid 12.3 o posterior:
import mermaid from 'mermaid';
import { archimate } from 'archimaid';
mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
await mermaid.registerExternalDiagrams([archimate]);
Para verificar la sintaxis rápidamente con el usuario, dirígelo al playground del navegador: https://try.archimaid.org
Ejemplos
references/examples.md tiene tres diagramas completos y válidos:
- Gestión de pedidos: asignación, realización, servicio y acceso de lectura
- Relaciones entre capas: diseño de arquitectura con procesamiento de reclamaciones anidado
- Componentes anidados: composición, notas adjuntas e independientes, flujos entre límites