¿Estás manteniendo tus diagramas de infraestructura?

“¿Dónde está la última versión del diagrama de arquitectura?”.

Cree diagramas de infraestructura solo en su navegador: generación automática de diagramas a partir de código

Cuando un nuevo miembro se une a tu equipo y hace esa pregunta, ¿cuántos sitios de desarrollo pueden presentar un archivo con confianza? En muchos proyectos, los diagramas de draw.io o PowerPoint creados durante la fase de diseño inicial se dejan abandonados y desactualizados.

La razón es simple: “Es una molestia arreglarlo”.
Volver a conectar líneas manualmente, ajustar diseños y exportar como una imagen en un navegador: el coste es simplemente demasiado alto en el desarrollo moderno, donde la infraestructura cambia con frecuencia.

Crear diagramas “como si escribieras código”

Si podemos gestionar los diagramas como recursos basados en texto, al igual que gestionamos el código con Git, la frescura de nuestra documentación mejorará drásticamente. Por eso deberíamos fijarnos en Mermaid.js.

Simplemente defines las conexiones en texto y el navegador representa automáticamente el diagrama con un diseño óptimo. No hay razón para no usar este sistema “mágico”.

graph TD
    Internet["Internet"] --> LB["Load Balancer"]
    LB --> WebServer["Web Server"]
    WebServer --> DB[("Database")]

Un “editor visual” para evitar pelear con las herramientas

Dicho esto, memorizar y escribir a mano toda la sintaxis de Mermaid también es una tarea ardua. Quieres concentrarte en “pensar en la configuración de la infraestructura”, no quedarte atascado en “errores de sintaxis de Mermaid”.

El Constructor de diagramas de infraestructura de DevToolKits fue diseñado para ofrecerte lo mejor de ambos mundos.

Construye de forma intuitiva, exporta de forma inteligente

  1. Colocar nodos: añade componentes como servidores o bases de datos desde la interfaz de usuario.
  2. Conectar líneas: simplemente elige qué nodo se comunica con cuál.
  3. Copiar Mermaid: el diagrama terminado se puede copiar directamente como código.

Pega el código Mermaid resultante en un README de GitHub o en Notion, y se convertirá en tu “diagrama siempre actualizado”. Cuando sea necesario un arreglo, simplemente cambia una línea de código. Esta agilidad es como debería ser la verdadera “documentación”.

Consejos para diagramas de arquitectura legibles

Cuantos más nodos y líneas añades, más complejo se vuelve un diagrama. Tener presentes estos puntos da un diagrama fácil de entender cuando vuelves a mirarlo más adelante.

  • Agrupa por capas: usa el subgraph de Mermaid para agrupar en “capa de red”, “capa de aplicación” y “capa de datos”, o por VPC y zona de disponibilidad, de modo que los límites de responsabilidad se vean con claridad.
  • Mantén coherente el sentido del tráfico: que el flujo vaya de arriba abajo (o de izquierda a derecha), como en exterior → balanceador de carga → aplicación → BD, hace intuitivo seguir el flujo de datos.
  • Añade etiquetas en lugar de una leyenda: poner nombres concretos como WebServer["Web Server (ECS)"] permite que el diagrama por sí solo transmita la arquitectura.
graph TD
    subgraph Public
        Internet["Internet"] --> LB["Load Balancer"]
    end
    subgraph Private
        LB --> App["App Server"]
        App --> DB[("RDS")]
    end

En lugar de aspirar a un diagrama perfecto desde el principio, dibujar primero solo las rutas de tráfico principales y actualizar el código con cada cambio mantiene tu diagrama “siempre al día” a la larga.

Agrupar y colorear para leer mejor

En el Constructor de diagramas de infraestructura, cada nodo tiene un tipo y un grupo.

  • Grupo: los nodos con el mismo nombre se reúnen en un subgraph de Mermaid y se dibujan dentro de un marco (por ejemplo, Private subnet o VPC). Primero van los nodos sin grupo y después los grupos, en el orden en que los introdujo. Las conexiones se escriben fuera de los grupos, así que las líneas que cruzan grupos funcionan tal cual.
  • Tipo: elija entre user, gateway, server, database, storage, network y cloud.
  • Colorear por tipo: al marcarlo, solo los tipos en uso reciben color (default queda sin color). Por ejemplo, server es azul, database verde, user amarillo y gateway morado. El área del diagrama conserva un fondo claro incluso en modo oscuro, por lo que los colores son un relleno pálido con texto oscuro.
subgraph grp_1["Private subnet"]
    n3["App Server 1"]
    n5[("Database")]
end
classDef infra_server fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
class n3 infra_server

Conclusión

Los diagramas de infraestructura no son una “obra de arte” que se termina una vez. Son “seres vivos” que siguen cambiando de forma a medida que tu sistema crece.

Gradúate del “trabajo de apuntar y hacer clic” y muévete de forma más ligera y precisa.
Visualiza tus diseños con el poder del texto y mantén actualizada constantemente la comprensión común de tu equipo.

💡 Un caso de uso práctico: cuando envíes una solicitud de extracción (Pull Request) en GitHub, intenta actualizar el código Mermaid junto con los cambios en tu infraestructura. De esta manera, los cambios de configuración se pueden revisar junto con el código, evitando que la documentación quede obsoleta.

La vista SVG avanzada: ordenar a mano y continuar donde lo dejaste

Además del código Mermaid, puedes ver el diagrama como un «SVG avanzado» propio (es la vista por defecto; la vista de Mermaid y la copia del código siguen disponibles).

  • Aspecto: tarjetas con sombra y el tipo de nodo como pequeña etiqueta; los grupos se dibujan como marcos de color con el nombre en una pestaña. Las líneas continuas, punteadas, gruesas y sin flecha se distinguen, y pueden llevar etiquetas
  • Interacción: al pasar el cursor sobre un nodo (o enfocarlo con el teclado) solo quedan sus conexiones, y al hacer clic ves a qué se conecta y desde dónde. Arrastra los nodos (o enfócalos y usa las flechas) para reordenarlos, y «Restablecer la disposición» vuelve a la automática
  • Guardado: el diagrama se puede ajustar al ancho, ampliar o reducir y guardar como SVG o PNG, con la disposición que hayas puesto
  • Exportación: además de Mermaid, puedes exportar Graphviz DOT, PlantUML, D2 y architecture-beta de Mermaid

El diagrama y las posiciones de los nodos que muevas se guardan automáticamente en este navegador, así puedes continuar la próxima vez. También puedes borrar lo guardado, o exportarlo e importarlo como JSON. No se envía nada a ningún servidor.

Preguntas frecuentes

¿Dónde puedo usar los diagramas Mermaid?

Muchos servicios que soportan Mermaid —README e issues/PR de GitHub, GitLab, Notion y más— lo renderizan como diagrama al pegarlo como bloque de código. A diferencia de las imágenes, es texto que puedes gestionar en Git, así que vive en tus diffs y mantiene un historial de cambios.

¿Qué ventaja tiene frente a draw.io o PowerPoint?

Las herramientas GUI permiten ajustar el aspecto, pero editar y reexportar es tedioso, así que los diagramas tienden a quedar obsoletos. Mermaid actualiza el diagrama cambiando una sola línea de texto y se puede versionar en Git, lo que facilita mantenerlo sincronizado con los cambios de configuración y “siempre actual”.

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

El Constructor de diagramas de infraestructura procesa todo en tu navegador y nunca envía tu configuración ni el código Mermaid a un servidor, así que puedes diagramar con seguridad detalles sensibles como la arquitectura de sistemas internos.

¿Cómo puedo hacer más legible un diagrama grande y complejo?

Agrupa por capas de red, de aplicación y de datos, o por VPC y zona, con el subgraph de Mermaid, y mantén el sentido del tráfico coherente de arriba abajo (o de izquierda a derecha), para que los límites de responsabilidad y el flujo de datos sean fáciles de seguir. Dibujar primero solo las rutas principales y actualizar con cada cambio mantiene el diagrama más fresco que intentar dibujarlo todo de una vez.