panfu/arch-diagram

¿Qué hace arch-diagram?

Dos métodos, se pueden usar por separado o encadenados (lenguaje natural → Mermaid → HTML).

• nl2mmd: lenguaje natural → dialecto Mermaid
• mmd2html: dialecto Mermaid → HTML interactivo (plantilla: directorio de esta skill assets/template.html)

Convenio común: dialecto Mermaid

Estructura (tres niveles, correspondientes a servidor→servicio→subservicio en HTML):

• subgraph de nivel superior = servidor, con direction TB dentro
• subgraph de segundo nivel = servicio (solo se crea subgrafo si tiene subservicios; los servicios sin subservicios se escriben directamente como nodos)
• Nodos dentro del subgrafo de servicio = subservicios
• Todos los títulos entre comillas: subgraph X["título"], N["título"]

Notas (meta): dentro del título, separar nombre y nota con |. En el HTML generado, la nota se muestra en texto pequeño claro al lado del nombre (especificaciones del servidor, puertos, volumen de tareas, parámetros, etc.). Si no hay nota, no se escribe |:

• subgraph WEB["Web edge | dual · LAN"] → nombre del servidor "Web edge", nota "dual · LAN"
• WEB_GW["API gateway | QPS 3k"] → nombre del servicio + nota
• Regla de parseo: tomar el último |, a la izquierda el nombre, a la derecha la nota

Los tipos de arista se expresan mediante el estilo de línea, fijo e inmutable:

Tipo	Estilo de línea	Semántica
sync	==>	Sincronización / escritura
call	-->	API / RPC / WS
job	-.->	cron / tarea programada / push
data	-.-	Lectura de solo consulta

• Etiqueta de arista: ==>|"tipo · momento o frecuencia"|, p. ej. ==>|"sync · 07:10 4×/día"|; -->|call| se puede omitir
• Los IDs de nodo usan mayúsculas snake_case: <servidor>_<servicio>_<subservicio>, p. ej. NAS_SCHED_FLAT
• Las aristas pueden anclarse en subgrafos (nivel servicio/servidor), lo que indica granularidad
• Comienza con flowchart LR; las aristas internas del mismo host se escriben normalmente (al generar HTML se dibujarán como bucles que salen y entran por la derecha)

Método 1: nl2mmd (lenguaje natural → Mermaid)

1. Extraer entidades: máquina/host/entorno → servidor; software instalado o en ejecución → servicio; componentes/funciones/tareas/bibliotecas dentro del software → subservicio.
2. Extraer relaciones: mapear verbos al tipo: sincronizar/escribir/espejo → sync; invocar/solicitar/enviar/recibir → call; diario/programado/cron/xx:xx/empujar → job; leer/consultar/caja blanca → data. Hora y frecuencia van en la etiqueta de la arista.
3. Si hay duda sobre el nivel, colocar a nivel servicio, no inventar subservicios.
4. Los números y especificaciones (puertos, recursos, volumen de tareas, rangos IP, etc.) van en la nota del nodo: ["nombre | nota"]; hora y frecuencia van en la etiqueta de la arista. No perderlos.
5. Devolver un bloque flowchart LR completo, sin explicación.

Método 2: mmd2html (Mermaid → HTML interactivo)

Pasos

1. Leer assets/template.html completo (~38 KB, archivo único autocontenido, por defecto con datos de examples/sample.mmd).
2. Parsear el Mermaid (según el dialecto anterior), construir un mapeo id Mermaid → ruta jerárquica: ruta con puntos separando servidor.servicio.subservicio (truncada según la profundidad de anidamiento). Cuando una arista está anclada en un subgrafo, la ruta se detiene en ese nivel.
3. Reemplazar todo el bloque comprendido entre /*==DATA==*/ y /*==DATA-END==*/ en la plantilla por el nuevo bloque de datos, sin tocar el resto del código:

/*==DATA==*/
var ARCH_TITLE='Título del diagrama (barra de título del terminal y <title> independiente)';
var ARCH_LSKEY='arch-<slug>';   // clave de localStorage, única por diagrama
var TYPE={sync:{c:'#3ecf8e',dash:'10 4',dur:'1.5s',label:'Sincronización'},
 call:{c:'#58a6ff',dash:'6 5',dur:'1.1s',label:'Llamada'},
 job :{c:'#f0a942',dash:'2 4',dur:'0.85s',label:'Programada'},
 data:{c:'#b18cff',dash:'14 5',dur:'1.9s',label:'Lectura'}};
var COLS=[['srvA','srvB'],['srvC']];   // diseño por columnas por defecto: cada columna del array = grupo de IDs de servidor
var SERVERS=[
 {id:'srvA',short:'A',name:'A · nombre visible',meta:'nota',ac:'#b18cff',svc:[
   {id:'svc1',short:'svc1',name:'Servicio1',meta:'',subs:[
     {id:'sub1',short:'sub1',name:'Subservicio1',meta:''}]},
   {id:'svc2',short:'svc2',name:'Servicio2'}]},
];
var EDGES=[
 {from:'srvA.svc1.sub1',to:'srvC.svc2',type:'sync',sched:'07:10 4×/día'},
];
/*==DATA-END==*/

Reglas de campos:

• id en ASCII (la ruta se compone a partir de estos); name puede ser en chino; short es el nombre corto usado en conexiones/logs
• meta proviene de la parte después del último | en el título del nodo/subgrafo; si no existe, se omite
• ac se rota de la paleta: #b18cff #3ecf8e #39d0c4 #58a6ff #f0a942
• type ∈ sync|call|job|data (corresponde al estilo de línea Mermaid); sched proviene de la parte después del tipo en la etiqueta de la arista; si no existe, se escribe en tiempo real
• COLS: ordenar aproximadamente por flujo de aristas (origen a la izquierda, destino a la derecha); el generador de columnas para un solo servidor centrará verticalmente automáticamente

4. Escribir el resultado en la ruta de destino (versión fragmento). Para que funcione al hacer doble clic, envolver con:

<!doctype html><html lang="es"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{ARCH_TITLE}</title>
<style>html,body{margin:0;padding:0;background:#080b12}#svcarch{min-height:100vh}</style></head><body>
{fragment}</body></html>

QA

1. Obligatorio: extraer <script> y ejecutar node --check; verificar datos: el número de servidores/servicios/subservicios debe coincidir con Mermaid, el número de aristas = número de aristas en Mermaid, el número de conexiones en la vista por defecto = número de pares (from,to,type) después de deduplicar.
2. Si hay navegador: al iniciar un servidor local debe incluir cabecera charset (python3 -m http.server no incluye charset, puede mostrar caracteres chinos incorrectos; se necesita un handler personalizado que añada Content-Type: text/html; charset=utf-8 a .html). Abrir y verificar título, conteo, cambio de granularidad ▾ servers, clic para plegar.
3. La plantilla solo modifica el bloque DATA; el resto del código (arrastre/plegado/persistencia) no debe reimplementarse.

Ejemplos

• examples/sample.mmd — ejemplo completo del dialecto (4 servidores, 9 aristas, cubre los 4 tipos de línea y aristas del mismo host)
• examples/sample.html — producto terminado generado a partir de la plantilla (funciona al hacer doble clic)

Capacidades incorporadas en el HTML generado (no reimplementar fuera de la plantilla)

Arrastrar (mango en la parte superior; manteniendo Alt se muestran todos), ajustar ancho por el borde derecho, plegar/expandir, tres presets de granularidad (servidores/servicios/hojas), registro de aristas/inspector, estado de diseño y plegado guardado en localStorage (clave = ARCH_LSKEY). El texto de la interfaz está en inglés.

• Zoom y desplazamiento del lienzo: Ctrl+rueda para hacer zoom centrado en el cursor (0.4–2.5×); manteniendo Ctrl, el ratón se convierte en mano y arrastra el lienzo; chip de porcentaje en la esquina inferior derecha, al hacer clic restablece. Zoom/desplazamiento se persisten con localStorage.
• Edición incorporada: manteniendo Alt y haciendo clic en cualquier cabeza de nodo (los tres niveles) se puede cambiar nombre/nota/color de marco del servidor, añadir subordinados, eliminar (doble confirmación, cascada sobre subárbol y aristas); Alt+clic en una arista permite cambiar tipo/momento o eliminar arista. Mientras se mantiene Alt, aparece ⇱ export en la esquina superior derecha, que muestra un modal con el Mermaid del estado actual (resaltado de sintaxis + copiar), que contiene ⟲ relayout y ↺ restaurar datos por defecto. Los resultados de la edición se persisten con localStorage.