Más allá de las imágenes estáticas: Desbloqueando el poder del diagrama como código con Mermaid y herramientas de IA
La crisis de la documentación
Cada equipo de ingeniería conoce el dolor. Pasa semanas diseñando una hermosa arquitectura de microservicios, creando con esmero diagramas de Visio que impresionan a los interesados. Seis meses después, el sistema ha evolucionado: se han añadido nuevos servicios, se han migrado bases de datos, se han descontinuado puntos finales de API, pero el diagrama está congelado en el tiempo. Es una reliquia. Incluso una mentira.
Esto es la ‘podredumbre de documentación’, y es el asesino silencioso de la productividad de ingeniería. Cuando los diagramas mienten, los desarrolladores los ignoran. Cuando los desarrolladores ignoran la documentación, prevalece el conocimiento tribal. Cuando la única persona que conoce el sistema se va, queda un código complejo y sin mapa.
Diagrama como código (DaC)es la solución. Y en su núcleo estáMermaid, la herramienta de diagramación basada en JavaScript que convierte texto plano en visualizaciones hermosas.
La filosofía fundamental: Tratar los diagramas como software
El cambio fundamental con el diagrama como código es tratar tus diagramas con la misma rigurosidad que tu código de aplicación. Esto significa:
1. El control de versiones es lo estándar
Cuando tu diagrama es un archivo.mermaidse almacena en tu repositorio Git junto con tu código fuente. Cada cambio se rastrea. Puedes usargit blamepara ver quién añadió ese nuevo servicio,git diffpara revisar los cambios antes de fusionarlos, y revertir a cualquier estado anterior.
gitGraph
commit id: "Arquitectura inicial"
commit id: "Añadir servicio de usuario"
branch feature/order-service
commit id: "Servicio de pedidos v1"
commit id: "Añadir pasarela de pago"
checkout main
merge feature/order-service
commit id: "Actualizar puerta de enlace de API"
Ejemplo: Visualizar el historial Git propio de tu diagrama usando la sintaxis de gráfico Git de Mermaid
2. Revisiones de código para diagramas
Las solicitudes de extracción ya no son solo para código. Cuando un desarrollador propone un nuevo servicio o cambia un flujo de datos, ese cambio aparece como una diferencia legible en la solicitud. Los revisores pueden comentar directamente sobre el diagrama, asegurando que las decisiones arquitectónicas se discutan y aprueben antes de fusionarse.
3. Integración con la canalización CI/CD
Tus diagramas pueden generarse y validarse automáticamente en tu canalización. Imagina una acción de GitHub que:
-
Convierte todos los diagramas de Mermaid en PNG/SVG
-
Los sube a tu sitio de documentación
-
Falla la compilación si se detecta sintaxis de Mermaid inválida
diagrama de flujo LR
A[El desarrollador envía código] --> B[Se ejecuta la canalización de CI]
B --> C[Ejecutar pruebas]
B --> D[Generar diagramas de Mermaid]
D --> E{Sintaxis válida?}
E -->|Sí| F[Subir a la documentación]
E -->|No| G[Error en la compilación y notificación al equipo]
F --> H[Desplegar la aplicación]
G --> I[El desarrollador corrige la sintaxis]
I --> A
Ejemplo: Un flujo de trabajo CI/CD para la validación y despliegue de diagramas
Mermaid en acción: Ejemplos del mundo real
Exploraremos los tipos de diagramas que Mermaid admite con ejemplos prácticos del mundo real.
Ejemplo 1: Arquitectura de microservicios (diagrama de flujo)
Este es el caso de uso más común: visualizar cómo se comunican sus servicios.
diagrama de flujo TB
subgrafo "Capa de cliente"
MobileApp[Aplicación móvil]
WebApp[Aplicación web]
fin
subgrafo "Pasarela de API"
Gateway[Pasarela de API]
fin
subgrafo "Microservicios"
UserSvc[Servicio de usuario]
OrderSvc[Servicio de pedidos]
ProductSvc[Servicio de productos]
PaymentSvc[Servicio de pagos]
fin
subgrafo "Capa de datos"
UserDB[(Base de datos de usuarios)]
OrderDB[(Base de datos de pedidos)]
ProductDB[(Base de datos de productos)]
Redis[(Caché Redis)]
fin
subgrafo "Servicios externos"
Stripe[Pago con Stripe]
EmailAPI[API de correo electrónico]
fin
MobileApp --> Gateway
WebApp --> Gateway
Gateway --> UserSvc
Gateway --> OrderSvc
Gateway --> ProductSvc
Gateway --> PaymentSvc
UserSvc --> UserDB
UserSvc --> Redis
OrderSvc --> OrderDB
OrderSvc --> Redis
ProductSvc --> ProductDB
ProductSvc --> Redis
PaymentSvc --> Stripe
OrderSvc --> EmailAPI
PaymentSvc --> EmailAPI
Ejemplo: Una arquitectura completa de microservicios con caché, bases de datos y dependencias externas
Ejemplo 2: Flujo de autenticación de usuario (diagrama de secuencia)
Los diagramas de secuencia son perfectos para documentar interacciones complejas entre servicios.
diagrama de secuencia
numeración automática
participante Usuario
participante Frontend
participante AuthSvc como Servicio de autenticación
participante UserDB como Base de datos de usuarios
participante Cache como Caché Redis
participante EmailSvc como Servicio de correo electrónico
Usuario->>Frontend: Ingresar credenciales
Frontend->>AuthSvc: POST /login (correo electrónico, contraseña)
AuthSvc->>UserDB: Consultar usuario por correo electrónico
UserDB-->>AuthSvc: Devolver contraseña encriptada y datos del usuario
AuthSvc->>AuthSvc: Verificar contraseña con bcrypt
alternativa Credenciales válidas
AuthSvc->>AuthSvc: Generar token JWT
AuthSvc->>Cache: Almacenar sesión (clave: user_id, tiempo de vida: 1 hora)
AuthSvc-->>Frontend: 200 OK + token JWT
Frontend-->>Usuario: Redirigir al panel de control
sino Credenciales inválidas
AuthSvc->>EmailSvc: Activar alerta de inicio de sesión fallido
AuthSvc-->>Frontend: 401 No autorizado
Frontend-->>Usuario: Mostrar mensaje de error
fin
Nota sobre AuthSvc,EmailSvc: Después de 5 intentos fallidos, bloquear la cuenta durante 15 minutos
Ejemplo: Un flujo de autenticación detallado que muestra rutas de éxito y fracaso, incluyendo efectos secundarios como caché y alertas
Ejemplo 3: Infraestructura en la nube en AWS (diagrama de clases)
Los diagramas de clases no son solo para código: también pueden modelar recursos en la nube y sus relaciones.
diagrama de clases
clase VPC {
+string cidr_block
+string región
+createSubnet()
+deleteSubnet()
}
clase Subnet {
+string zona de disponibilidad
+string cidr_block
+boolean es_pública
+attachRouteTable()
}
clase EC2Instance {
+string tipo_de_instancia
+string ami_id
+int almacenamiento_gb
+start()
+stop()
+reboot()
}
clase RDSDatabase {
+string motor
+string versión
+int almacenamiento_gb
+boolean multi_az
+takeSnapshot()
+restoreFromSnapshot()
}
clase S3Bucket {
+string nombre_del_bucket
+string región
+boolean versioning_enabled
+uploadFile()
+downloadFile()
}
clase IAMRole {
+string nombre_del_rol
+string policy_document
+attachPolicy()
+detachPolicy()
}
VPC "1" --> "*" Subnet
Subnet "1" --> "*" EC2Instance
Subnet "1" --> "0..1" RDSDatabase
VPC "1" --> "0..*" S3Bucket
EC2Instance --> IAMRole
RDSDatabase --> IAMRole
Ejemplo: Modelar la infraestructura de AWS como clases con propiedades y métodos, útil para documentación y planificación de infraestructura como código
Ejemplo 4: Procesamiento de pedidos en comercio electrónico (diagrama de estados)
Los diagramas de estado destacan al mostrar cómo las entidades pasan por diferentes estados.
stateDiagram-v2
[*] --> Carrito: El usuario agrega artículos
Carrito --> Pago: El usuario procede al pago
Pago --> PagoPendiente: El usuario envía el pedido
PagoPendiente --> ProcesandoPago: Iniciar gateway de pago
ProcesandoPago --> Pagado: El pago fue exitoso
ProcesandoPago --> FalloPago: El pago fue rechazado
FalloPago --> Pago: El usuario intenta nuevamente el pago
FalloPago --> [*]: El usuario abandona el carrito
Pagado --> ConfirmadoPedido: Enviar correo de confirmación
ConfirmadoPedido --> Preparando: Asignar al almacén
Preparando --> Enviado: Entregar al transportista
Enviado --> EnTránsito: El transportista recoge el paquete
EnTránsito --> Entregado: Confirmación de entrega
Entregado --> SolicitadoRevisión: Solicitar revisión al usuario
SolicitadoRevisión --> [*]: El usuario envía la revisión
Entregado --> SolicitudReembolso: El usuario inicia el reembolso
SolicitudReembolso --> AprobadoReembolso: Soporte aprueba
AprobadoReembolso --> ProcesadoReembolso: Devolver dinero
ProcesadoReembolso --> [*]: Pedido cerrado
estado "Verificación de fraude de alto riesgo" como VerificacionFraude {
[*] --> VerificarPuntuación
VerificarPuntuación --> BajoRiesgo: Puntuación < 50
VerificarPuntuación --> AltoRiesgo: Puntuación >= 50
AltoRiesgo --> RevisiónManual: Marcar para el equipo
RevisiónManual --> BajoRiesgo: Aprobado
RevisiónManual --> FalloPago: Rechazado
}
PagoPendiente --> VerificacionFraude: Se activó la evaluación de riesgo
VerificacionFraude --> ProcesandoPago: BajoRiesgo
Ejemplo: Máquina de estados completa para pedidos de comercio electrónico con estado anidado de detección de fraude
Ejemplo 5: Planificación de sprint con problemas de GitHub (gráfico Git)
Los gráficos Git pueden representar flujos de trabajo más allá de Git mismo.
gitGraph
commit id: "Planificación de sprint" type: HIGHLIGHT
branch sprint-1
commit id: "Historia de usuario #101: Página de inicio de sesión"
commit id: "Historia de usuario #102: Registro de usuario"
branch bugfix/hotfix
commit id: "Corrección urgente: Caducidad del token de autenticación"
checkout sprint-1
merge bugfix/hotfix
commit id: "Historia de usuario #103: Restablecimiento de contraseña"
checkout main
merge sprint-1 tag: "v1.0.0"
branch sprint-2
commit id: "Característica #201: Carrito de compras"
commit id: "Característica #202: Flujo de pago"
branch experiment/ai-recommendations
commit id: "POC: Motor de recomendación con ML"
checkout sprint-2
commit id: "Característica #203: Historial de pedidos"
checkout main
merge sprint-2 tag: "v2.0.0"
commit id: "Notas de lanzamiento: Sprint 1 y 2 completos"
Ejemplo: Visualización de gestión de proyectos, sprints y ramas de características como un gráfico Git
La revolución de la IA en la diagramación
A pesar de la elegancia de Mermaid, la sintaxis puede ser una barrera. ¿Quién quiere depurar una flecha mal alineada o un corchete faltante cuando está tratando de documentar un sistema?
Aquí es donde las herramientas impulsadas por IA cambian todo.
Corrección automática con IA
Herramientas como VPasCode (plataforma de Diagramas como Código de Visual Paradigm) y Mermaid Chart han integrado modelos de IA (como Google Gemini y OpenAI) que pueden:
-
Detectar automáticamente errores de sintaxis
-
Corregir diagramas rotos con un solo clic
-
Sugerir mejoras en la estructura del diagrama
Veámoslo en acción:
Código Mermaid dañado:
flowchart LR
A[Frontend] --> B(Puerta de enlace de API
B --> C(Servicio de usuario)
C --> D[(Base de datos
D --> E[Cache]
Código corregido por IA:
diagrama de flujo LR
A[Frontend] --> B(Gateway de API)
B --> C[Servicio de Usuario]
C --> D[(Base de datos)]
D --> E[Caché]
La IA reconoce los paréntesis y corchetes faltantes y los corrige instantáneamente.
Lenguaje natural a diagrama
Quizás la característica más potente es generar diagramas a partir de descripciones en lenguaje natural. Con herramientas como OpenDocs (plataforma de documentación de VP), simplemente puedes describir lo que deseas:
“Crea un diagrama de flujo que muestre a un usuario iniciando sesión. Si las credenciales son válidas, redirige al panel de control. Si son inválidas, muestra un error y permite 3 intentos. Después de 3 fallas, bloquea la cuenta.”
Mermaid generado por IA:
diagrama de flujo TD
Start([Intentos de inicio de sesión del usuario]) --> EnterCreds[Ingresar correo electrónico y contraseña]
EnterCreds --> Validate{Validar credenciales}
Validate -->|Válido| Dashboard[Redirigir al panel de control]
Validate -->|Inválido| CheckAttempts{Intentos < 3}
CheckAttempts -->|Sí| Increment[Incrementar contador de intentos]
Increment --> ShowError[Mostrar mensaje de error]
ShowError --> EnterCreds
CheckAttempts -->|No| LockAccount[Bloquear cuenta durante 15 minutos]
LockAccount --> SendAlert[Enviar correo de alerta de seguridad]
SendAlert --> End([El proceso finaliza])
Dashboard --> End
Traducción entre tipos de diagramas
La IA también puede traducir entre diferentes formatos de diagramas. ¿Necesitas convertir un diagrama PlantUML a Mermaid? Las herramientas de IA pueden manejar eso:
Entrada de PlantUML:
@startuml
actor Usuario
participant "Frontend" as FE
participant "Backend" as BE
database "BD" as DB
Usuario -> FE: Hacer clic en Iniciar sesión
FE -> BE: POST /login
BE -> DB: SELECT usuario
DB --> BE: datos del usuario
BE --> FE: token JWT
FE --> Usuario: Mostrar panel de control
@enduml
Mermaid convertido por IA:
diagrama de secuencia
actor Usuario
participant Frontend
participant Backend
participant Base de datos
Usuario->>Frontend: Hacer clic en Iniciar sesión
Frontend->>Backend: POST /login
Backend->>Base de datos: SELECT usuario
Base de datos-->>Backend: datos del usuario
Backend-->>Frontend: token JWT
Frontend-->>Usuario: Mostrar panel de control
Integración de chatbot interactivo
Algunas plataformas ahora ofrecen interfaces de chatbot para la creación de diagramas. Puedes tener una conversación:
Usuario: “Agrega un nuevo servicio llamado ‘Servicio de Inventario’ a mi diagrama de arquitectura.”
IA: «Añadiré un servicio de inventario conectado a sus servicios existentes de Producto y Pedido.»
El diagrama se actualiza automáticamente
Usuario: «En realidad, haz que también se conecte a una nueva base de datos llamada «InventoryDB».»
IA: «Hecho. El servicio de inventario ahora se conecta al servicio de Producto, al servicio de Pedido y a la nueva base de datos InventoryDB.»
Integración de Diagramas como Código en su Flujo de Trabajo
Paso 1: Comience pequeño
No intente diagramar todo su sistema de una vez. Comience con un solo componente, tal vez su flujo de autenticación o una nueva funcionalidad que esté desarrollando.
Paso 2: Incrustar en la documentación
Mantenga sus .mermaid archivos junto con su documentación (por ejemplo, en una carpeta /docs ). Use herramientas como mermaid-cli para renderizarlos durante el proceso de compilación.
Paso 3: Aproveche el motor unificado de VPasCode
Si trabaja en un equipo con preferencias diversas, VPasCode es invaluable. Soporta múltiples lenguajes de diagramas como código en un solo lugar:
# En VPasCode, puede combinar y mezclar:
diagramas/
├── arquitectura.mermaid
├── despliegue.puml # PlantUML
├── base-de-datos-erd.mermaid
└── flujo-trabajo.d2 # Lenguaje D2
Paso 4: Automatice con CI/CD
Agregue un paso a sus GitHub Actions o GitLab CI:
- name: Renderizar diagramas Mermaid
run: |
for file in $(find docs -name "*.mermaid"); do
npx @mermaid-js/mermaid-cli -i $file -o ${file%.mermaid}.png
done
- name: Subir al sitio de documentación
run: |
aws s3 sync docs/ s3://su-bucket-de-documentacion/
Paso 5: Revisión en solicitudes de extracción
Hágalo una política que todos los cambios de arquitectura requieran actualizaciones de diagramas. Use comentarios de PR para discutir cambios visuales:
Revisor: «¿No debería estar la caché entre el servicio de Pedido y la base de datos? Actualmente solo está conectada al servicio de Usuario.»
Autor:«Buena observación. Actualizaré el diagrama.»
Impacto en el Mundo Real: Un Estudio de Caso
Considere una startup de fintech que adoptó Diagramas como Código con Mermaid y VPasCode:
-
Antes:47 archivos estáticos de Visio, la mayoría con más de 6 meses de antigüedad. Los nuevos empleados dedicaron 3 semanas a comprender la arquitectura.
-
Después:12 diagramas de Mermaid, todos almacenados en Git, actualizados con cada nueva funcionalidad. Los nuevos empleados fueron productivos desde la semana 1.
El CTO del equipo señaló: «Pasamos de que los diagramas fueran una casilla de cumplimiento a convertirse en una parte viva de nuestro proceso de desarrollo. Cuando debatimos una nueva arquitectura, abrimos el editor de Mermaid y esbozamos literalmente el diseño en código. Es un cambio de juego.»
El Futuro: Documentación Continua
El objetivo final es la «documentación continua», donde los diagramas se generan automáticamente a partir de su infraestructura o código. Ya están surgiendo herramientas que pueden:
-
Escanea tus manifiestos de Kubernetes y genera diagramas de topología de servicios
-
Analiza archivos OpenAPI/Swagger y crea diagramas de flujo de API
-
Monitorea tus recursos en la nube y actualiza automáticamente los diagramas de arquitectura
Mermaid está en el centro de este movimiento, ofreciendo un formato simple basado en texto que las máquinas pueden generar y los humanos pueden entender.
Comenzando Hoy
¿Listo para ir más allá de las imágenes estáticas? Este es tu plan de acción:
-
Instala la extensión de Mermaiden tu IDE favorito (VS Code, IntelliJ)
-
Crea tu primer diagramaen un archivo
.mdusando la sintaxis de Mermaid -
Explora la versión gratuita de VPasCodepara experimentar el diagramado impulsado por IA
-
Inicia un repositorio de documentación vivajunto a tu código base
-
Comparte este artículo con tu equipoy empieza la conversación
Tu arquitectura merece algo mejor que un diagrama polvoriento en una carpeta olvidada. Es momento de tratar tus diagramas como los activos críticos que son.
