El problema de 'Nadie actualizó el diagrama de arquitectura'

Ese Familiar Momento de Pavor

“Oye, ¿no habíamos añadido una instancia de RabbitMQ delante de este servidor de API?”

Cuando un ingeniero junior señaló esto casualmente durante una reunión, se me heló la sangre. El diagrama de infraestructura que flotaba en nuestra Wiki interna me devolvía la mirada, mostrando con orgullo una marca de tiempo de ‘Última actualización’ de hace seis meses.

Seamos sinceros, la infraestructura evoluciona constantemente. Añadimos una caché Redis aquí, un proxy inverso allá. Pero pasar por el enorme dolor de abrir una pesada herramienta de dibujo gráfico, arrastrar pequeños iconos cuadrados, alinear flechas dolorosamente, exportar el PNG y subirlo a la Wiki… Es demasiada fricción. Todo el mundo piensa: “Definitivamente actualizaré el diagrama más tarde”, y por supuesto, nadie lo hace nunca.

Anhelando ‘Diagrama como Código’

Para matar este problema del “diagrama siempre desactualizado”, recurrí a Mermaid.js. La idea de ‘Diagrama como Código’ (Diagram as Code) es un sueño para los desarrolladores: escribes un poco de texto, lo envías a git y aparece mágicamente un hermoso diagrama.

Pero hacer esto localmente tenía sus peculiaridades. Tratar de escribir gráficos anidados complejos (como una instancia EC2 dentro de una VPC dentro de una región de AWS Cloud) requería aprender una sintaxis que no era exactamente intuitiva. Escribía el código, esperaba a que se construyera una vista previa de PR, solo para descubrir que mis flechas apuntaban hacia atrás.

Viéndolo Construirse Mientras Escribes

“Solo quiero escribir el texto y ver cómo el diagrama se construye suavemente al otro lado de mi pantalla en tiempo real”.

Ese deseo completamente egoísta es lo que dio a luz a este “Constructor de Diagramas de Infraestructura” (Infra Diagram Builder).

Mi regla más estricta mientras lo construía fue cero comunicación con el servidor. Los diseños de infraestructura son básicamente los planos de la bóveda de la empresa. No hay absolutamente ninguna manera de que quisiera que pegaras eso en una herramienta que envía datos a un servidor aleatorio (incluso si es mi servidor aleatorio). Así que, forcé toda la tubería de renderizado a JavaScript local del lado del navegador.

Si actualmente temes a una actualización de la documentación de tu infraestructura, intenta escribir algo de código en esta herramienta. Ver encajar el diagrama en su lugar te da esta sensación extraña pero satisfactoria de poder arquitectónico supremo.

Al final, lo que perdura es la “ligereza”

Construir esto me confirmó algo que sospechaba: los diagramas quedan desactualizados no porque la sintaxis sea difícil, sino porque actualizar da pereza. En cuanto se interpone un solo ritual —abrir una herramienta pesada, reordenar iconos, exportar, volver a subir—, la gente elige el “más tarde”. Y ese “más tarde” no llega nunca.

Por eso la prioridad pasó a ser “abrirlo en el instante en que se te ocurre y corregirlo en cinco segundos”. Nombres de nodo cortos, dibujar solo los flujos principales y dividir en varios diagramas al pasar de diez nodos. Ese nivel de ligereza es lo que de verdad perdura. Un diagrama imperfecto pero actualizado vale más que uno perfecto de hace seis meses: el actualizado es el que salva a tu yo del futuro.

Preguntas frecuentes

¿Necesito saber la sintaxis de Mermaid para usarlo?

No. Vas añadiendo nodos y conexiones uno a uno y el código Mermaid se genera por debajo. Puedes crear un diagrama sin conocer la sintaxis y copiar el código generado directamente en un README de GitHub.

¿La infraestructura que introduzco se envía a algún sitio?

No. El renderizado ocurre íntegramente en tu navegador local. Como enviar el diseño de infraestructura de una empresa a un servidor externo resultaba demasiado arriesgado, se diseñó desde el principio para que nunca salga de tu equipo.

¿El diagrama se muestra en un README de GitHub?

Sí. GitHub renderiza los diagramas de flujo de Mermaid de forma nativa, así que puedes gestionar tu diagrama de arquitectura como texto en lugar de como imagen, y seguir los cambios en los pull requests igual que con el código.

¿Cómo dibujo un diagrama grande con muchos nodos?

En lugar de meterlo todo en uno, divide por rol (red / aplicación / datos / monitorización). Diez nodos es un buen umbral para dividir. No sobrecargarlo es lo que mantiene el diagrama mantenible con el tiempo.