Generador de Diagramas de Contenedor C4

¿Qué hace Generador de Diagramas de Contenedor C4?

Genera diagramas de contenedor C4 siguiendo las convenciones del modelo C4, exportados como archivos XML editables de draw.io que se abren directamente en draw.io (escritorio o web).

Cuándo Usarlo

Disparadores explícitos:

• El usuario solicita un diagrama C4, diagrama de contenedor o diagrama de arquitectura
• El usuario dice "dibuja la arquitectura", "diagrama del sistema", "muéstrame los componentes"
• El usuario necesita visualizar la arquitectura del sistema para documentación o una presentación
• El usuario menciona draw.io, drawio o quiere un diagrama editable

Disparadores proactivos:

• Explicando un sistema con 3 o más componentes que interactúan
• Discutiendo microservicios, APIs, bases de datos y sus relaciones
• Revisando o diseñando la arquitectura del sistema

Omitir cuando:

• El usuario quiere un diagrama de flujo simple (usar Mermaid en su lugar)
• El usuario quiere wireframes o maquetas de UI
• El sistema tiene menos de 3 componentes

Proceso

Paso 1: Recopilar Requisitos

Identificar de la conversación o preguntar al usuario:

• ¿Qué sistema estamos diagramando?
• ¿Quiénes son los usuarios/actores (Persona)?
• ¿Qué contenedores existen (apps, servicios, bases de datos, colas, almacenamiento de archivos)?
• ¿Con qué sistemas externos interactúa?
• ¿Cuáles son los flujos de datos y protocolos clave?

Si el usuario proporciona una especificación, descripción del código base o resumen de la arquitectura, extraer los elementos automáticamente y confirmar antes de generar.

Paso 2: Clasificar Elementos

Mapear cada elemento a una categoría C4:

Categoría	Color	Forma	Descripción
Persona	#08427B (azul oscuro)	shape=actor + etiqueta de texto	Usuarios, actores, roles
Contenedor	#438DD5 (azul)	Rectángulo redondeado	Aplicaciones, servicios, APIs
Base de Datos	#438DD5 (azul)	Cilindro	Cualquier almacén de datos (SQL, NoSQL, archivos)
Cola/Broker	#438DD5 (azul)	Rectángulo redondeado con etiqueta	Colas de mensajes, buses de eventos
Sistema Externo	#999999 (gris)	Rectángulo redondeado	Servicios de terceros, APIs
Límite del Sistema	ninguno (transparente)	Rectángulo discontinuo	Agrupa contenedores internos

Referencia: references/element-templates.md para las plantillas XML exactas de draw.io.

Paso 3: Planificar Diseño

Aplicar diseño estricto en capas (de arriba a abajo):

Capa 1 (y ~= 20):     Elementos Persona (actores)
Capa 2 (y ~= 250):    Límite del Sistema que contiene Contenedores internos
Capa 3 (y ~= 700+):   Sistemas Externos

Reglas de diseño:

• Cada elemento recibe coordenadas x, y explícitas (sin auto-diseño)
• Mínimo 200px de separación horizontal entre elementos en la misma capa
• Mínimo 200px de separación vertical entre capas
• Límite del sistema = rectángulo discontinuo que encierra todos los contenedores internos con 40px de relleno
• Ordenar elementos de izquierda a derecha siguiendo la dirección principal del flujo de datos
• Agrupar contenedores relacionados dentro de sub-límites si el sistema tiene subsistemas distintos
• Mantener el ancho del diagrama por debajo de 1600px para legibilidad
• Centrar elementos horizontalmente dentro de su capa

Minimizar cruces de líneas:

• Colocar elementos que se comunican frecuentemente adyacentes entre sí
• Enrutar conexiones verticalmente cuando sea posible
• Evitar líneas diagonales que crucen otros elementos
• Sin flechas a través de contenedores no relacionados: si A se conecta a C, la flecha NO debe pasar a través de B. Solucionar: (a) colocando A y C adyacentes, (b) usando puntos de salida/entrada explícitos, o (c) reorganizando el diseño
• Las etiquetas de las flechas no deben superponerse al texto del contenedor: usar labelBackgroundColor=#ffffff en todos los bordes, y usar desplazamiento perpendicular (y en mxGeometry) para alejar las etiquetas de los contenedores

Paso 4: Definir Conexiones

Para cada conexión, especificar:

• Elemento origen y destino
• Etiqueta: acción + protocolo (ej., "Lee/escribe [SQL/TCP]", "Envía eventos [AMQP]")
• Estilo: línea sólida = llamada síncrona, línea discontinua = asíncrona (eventos, colas, webhooks)
• Dirección: siempre origen -> destino (seguir el flujo de datos)

Reglas de conexión:

• Cada flecha debe tener una etiqueta (sin conexiones sin etiquetar) - si una etiqueta se superpone, corregir el diseño o el desplazamiento, nunca eliminar la etiqueta
• Incluir siempre labelBackgroundColor=#ffffff en los estilos de conexión
• Usar sufijo [Protocolo]: [REST/JSON], [gRPC], [SQL], [AMQP], [WebSocket]
• Flujos bidireccionales: usar dos flechas separadas con etiquetas distintas
• Auto-referencias: evitar (reestructurar el diagrama en su lugar)

Paso 5: Generar XML .drawio

Usar la estructura XML de references/drawio-template.md como base.

Construir el XML siguiendo estas reglas:

1. Comenzar con el envoltorio <mxfile> y <mxGraphModel> con las dimensiones adecuadas
2. Agregar las celdas raíz (id="0" e id="1")
3. Agregar primero los rectángulos del límite del sistema (son los padres de los elementos contenidos)
4. Agregar todos los elementos con geometría explícita (x, y, ancho, alto)
5. Agregar todas las conexiones con referencias origen/destino
6. Agregar la leyenda en la esquina inferior derecha

Dimensionado de elementos:

• Persona: 40 x 60px actor + 220 x 60px etiqueta de texto debajo
• Contenedor: 240 x 120px
• Base de Datos (cilindro): 240 x 120px
• Sistema Externo: 240 x 120px
• Límite del Sistema: calculado para encerrar a los hijos + 40px de relleno por cada lado

Paso 6: Agregar Leyenda

Cada diagrama debe incluir una leyenda. Colocarla en la esquina inferior derecha.

La leyenda debe mostrar:

• Persona = monigote azul oscuro (#08427B)
• Contenedor = rectángulo redondeado azul (#438DD5)
• Base de Datos = cilindro azul (#438DD5)
• Sistema Externo = rectángulo redondeado gris (#999999)
• Flecha sólida = flujo síncrono
• Flecha discontinua = flujo asíncrono

Referencia: references/legend-template.md para el XML exacto.

Paso 7: Guardar y Validar

Guardar en la ruta solicitada por el usuario, o por defecto en ./c4_[nombre_del_sistema].drawio.

Lista de validación:

• Todos los elementos tienen coordenadas x, y explícitas
• Las capas están ordenadas de arriba a abajo: Persona -> Límite del Sistema -> Externo
• El límite del sistema encierra todos los contenedores internos
• La leyenda está presente en la esquina inferior derecha
• Sin elementos superpuestos (verificar coordenadas + dimensiones)
• Mínimos cruces de líneas
• Cada conexión tiene una etiqueta con protocolo
• Líneas sólidas = síncronas, líneas discontinuas = asíncronas
• Los colores de fuente son blancos (#ffffff) sobre fondos de color
• El archivo se abre correctamente en draw.io (estructura XML válida)

Reglas del Modelo C4

Seguir las restricciones del diagrama de Contenedor C4:

• El diagrama de contenedor muestra las decisiones tecnológicas de alto nivel y cómo se comunican los contenedores
• Cada contenedor es una unidad desplegable/ejecutable por separado (no una clase o módulo)
• No mezclar niveles C4: esta habilidad genera solo el nivel de Contenedor
• Para detalle a nivel de Componente dentro de un contenedor, crear un diagrama separado
• Los elementos Persona representan roles, no personas individuales
• Los sistemas externos son todo lo que está fuera del límite del sistema que el equipo no posee

Antipatrones

• SIN auto-diseño - usar siempre coordenadas x, y explícitas para resultados predecibles
• SIN flechas sin etiquetar - cada conexión necesita una acción y un protocolo
• SIN leyenda faltante - la leyenda es obligatoria en cada diagrama
• SIN diseño apretado - mantener espacios mínimos entre elementos
• SIN mezcla de niveles C4 - solo nivel de Contenedor (sin clases, sin infraestructura)
• SIN texto invisible - asegurar que el color de fuente contraste con el fondo
• SIN dimensiones fijas - calcular el tamaño del límite del sistema a partir de los hijos
• SIN formas mxgraph.c4.* - requieren la biblioteca de formas C4 que NO está cargada por defecto en draw.io. Usar formas nativas: shape=actor para personas, shape=cylinder3 para bases de datos
• SIN flechas que crucen contenedores no relacionados - reorganizar el diseño para que cada flecha tenga un camino claro entre origen y destino
• SIN etiquetas sin labelBackgroundColor=#ffffff - las etiquetas sin fondo se vuelven ilegibles al cruzar otros elementos
• SIN eliminar etiquetas para corregir superposición - si una etiqueta se superpone a un contenedor, corregir el diseño o el desplazamiento, nunca eliminar información