Un diagrama C4 es un método estandarizado de visualización arquitectónica diseñado para modelar sistemas de software a múltiples niveles de abstracción estructural. Integrado nativamente en Mermaid.js, el c4motor sigue los cuatro niveles centrales del modelo C4: Contexto (el macroecosistema), Contenedores (aplicaciones, servicios y bases de datos), Componentes (módulos estructurales internos), y Interacciones dinámicas. Esta herramienta elimina la molestia de aplicar estilos CSS personalizados al aplicar bloques arquitectónicos coherentes y listos para presentación basados en sus declaraciones de texto.
Entendiendo las abstracciones y palabras clave del diagrama C4
Mermaid admite cuatro encabezados especializados para la inicialización de diagramas, dependiendo del nivel de detalle que requiera su diseño de sistema:
C4Contexto: Se centra en la visión general, mostrando usuarios, ecosistemas de software principales y dependencias externas de alto nivel.C4Contenedor: Se acerca un nivel para descomponer aplicaciones independientes, interfaces de frontend, microservicios, sistemas de almacenamiento de bases de datos y colas.C4Componente: Explora en profundidad un contenedor para mostrar módulos a nivel de código interno, como Controladores, Servicios y Repositorios.C4Dinámico: Se centra en rastrear interacciones de datos en tiempo de ejecución o la secuenciación paso a paso de transacciones entre bloques de infraestructura.
Estructura básica de sintaxis
Cada diagrama C4 comienza con su encabezado de nivel específico, seguido de una declaración opcional de título y componentes macro separados por comas. Los paréntesis albergan los parámetros, con cadenas delimitadas por comillas dobles.
C4Contexto
título "Boceto de contexto del sistema para el núcleo de Internet"
Persona(cliente, "Cliente de banca", "Un cliente del banco con cuentas personales.")
Sistema(sistema_bancario, "Sistema de banca en línea", "Permite a los clientes ver la información de sus cuentas.")
Rel(cliente, sistema_bancario, "Utiliza", "HTTPS")
La taxonomía completa de macros de elementos C4
La biblioteca C4 de Mermaid proporciona un amplio conjunto de macros especializadas para distinguir claramente entre componentes internos, sistemas externos y capas de bases de datos en todos los niveles de abstracción.
1. Macros de Persona y Usuario
Persona(alias, etiqueta, [descr], [sprite], [tags]): Modela un usuario humano interno o un interesado.Persona_Ext(alias, etiqueta, [descr], [sprite], [tags]): Modela un usuario externo (por ejemplo, un proveedor de terceros o auditor) fuera de los límites organizativos centrales.
2. Macros de Sistema y Ecosistema de Software
Sistema(alias, etiqueta, [descr], [sprite], [tags]): Representa un grupo de sistemas de software interno y dentro del alcance bajo su gestión directa.Sistema_Ext(alias, etiqueta, [descr], [sprite], [tags]): Modela un sistema de software externo crucial gestionado por un tercero (por ejemplo, proveedores de identidad, libros mayores de banca central).SistemaDb(alias, etiqueta, [descr], [sprite], [tags]): Representa una caja de repositorio de datos a nivel de sistema con forma de cilindro.SistemaDb_Ext(alias, etiqueta, [descr], [sprite], [tags]): Representa una capa de base de datos externa de terceros.
3. Macros de Capa de Contenedor (Nivel C4Container)
Contenedor(alias, etiqueta, tecnología, [descr], [sprite], [tags]): Modela una aplicación ejecutable independiente, servidor de API o interfaz de frontend.ContenedorDb(alias, etiqueta, tecnología, [descr], [sprite], [tags]): Representa un envoltorio de motor de base de datos relacional o no relacional a nivel de contenedor.Contenedor_Ext(alias, etiqueta, tecnología, [descr], [sprite], [tags]): Representa un contenedor en la nube externo o un servicio de aplicación.ContenedorDb_Ext(alias, etiqueta, tecnología, [descr], [sprite], [tags]): Representa una capa de almacenamiento de base de datos en la nube gestionada externamente.
4. Macros de Capa de Componente (Nivel C4Component)
Componente(alias, etiqueta, tecnología, [descr], [sprite], [tags]): Mapea un módulo, capa o controlador de clase a nivel de código interno.ComponenteDb(alias, etiqueta, tecnología, [descr], [sprite], [tags]): Modela un sistema de almacenamiento de microcomponentes interno o un sistema de caché de archivos de bajo nivel.
Contenedores de Límite y Envoltura Estructural
Para indicar perímetros de seguridad, cortafuegos corporativos o límites lógicos de aplicaciones, Mermaid proporciona tres envoltorios de contenedor con corchetes dedicados. Los elementos anidados dentro se agrupan visualmente.
Enterprise_Boundary(alias, etiqueta) { ... }: Envuelve sistemas de alto nivel dentro de una amplia frontera visual que representa el perímetro general de la infraestructura corporativa o de la empresa.System_Boundary(alias, etiqueta) { ... }: Agrupa contenedores de aplicaciones o microservicios estrechamente relacionados dentro de una caja de ecosistema de software unificado.Container_Boundary(alias, etiqueta) { ... }: Aisla componentes a nivel de código dentro de una única capa de contexto de módulo de aplicación.
Operadores direccionales avanzados de relaciones
Conectar bloques en diagramas C4 depende del Relmacro o sus variaciones explícitamente direccionadas. En lugar de pasar líneas de diagrama de flujo directas, rastreas las conexiones semánticamente declarando vectores de tecnología directamente dentro de los bloques lógicos.
| Token de sintaxis de relación | Dirección visual de la flecha | Contexto de alineación de uso |
|---|---|---|
Rel(desde, hasta, etiqueta, [tecn]) |
Dinámico / Automatizado | Relación predeterminada. Deja que el algoritmo de diseño determine la mejor ruta de línea. |
BiRel(desde, hasta, etiqueta, [tecn]) |
Bidireccional (<–>) | Indica intercambios interactivos de dos vías, protocolos dúplex o procesos de sincronización. |
Rel_Atras(desde, hasta, etiqueta, [tecn]) |
Flecha invertida en la parte superior (<–) | Dibuja la relación hacia adelante en la lógica del código, pero invierte la flecha visual visible hacia atrás. |
Rel_Vecino(desde, hasta, etiqueta, [tecn]) |
Preferencia de diseño horizontal | Forza al nodo objetivo a permanecer directamente al lado del nodo de origen en la misma fila horizontal. |
Rel_Abajo(desde, hasta, etiqueta, [tecn]) / Rel_Abajo(...) |
Recto hacia abajo (v) | Forza los flujos de datos verticales hacia abajo hasta capas de base de datos o procesos posteriores en segundo plano. |
Rel_Up(from, to, label, [tech]) / Rel_U(...) |
Hacia arriba recto (^) | Forza a que las rutas de relación viajen rectas hacia los componentes de la interfaz de usuario del cliente. |
Rel_Izq(from, to, label, [tech]) / Rel_I(...) |
Hacia la izquierda recto (<-) | Dirige las rutas horizontalmente hacia el lado izquierdo del elemento del lienzo. |
Rel_Der(from, to, label, [tech]) / Rel_D(...) |
Hacia la derecha recto (->) | Dirige las rutas horizontalmente hacia el lado derecho del elemento del lienzo. |
Estilo y etiquetado dinámicos personalizados (anulaciones de forma C4)
Para marcar aplicaciones heredadas, destacar sistemas premium o resaltar flujos de datos seguros, puedes crear estilos personalizados utilizando el motor de etiquetas de elementos. Definirás una matriz de propiedades de etiqueta en la parte superior de tu documento y luego agregarás esa etiqueta a las definiciones de tus elementos.
Palabras clave para modificar el estilo:
ActualizarEstiloElemento(elemento, colorFondo, colorFuente, [colorBorde], [sombreado]): Sustitución directa de la paleta de fondo predeterminada de una caja de elemento explícita.ActualizarEstiloRel(from, to, colorLinea, colorTexto): Dirige explícitamente una ruta de conexión para cambiar el color de las líneas o las descripciones de conexión.
C4Context
título "Mapa de arquitectura global con codificación por colores personalizada"
Sistema(legacy_api, "Núcleo de facturación heredado", "Procesa las renovaciones de suscripciones.")
Sistema(modern_portal, "Portal de panel de control del cliente", "Motor moderno de vista web para usuarios.")
%% Personalización directa de colores
ActualizarEstiloElemento(legacy_api, "#d9534f", "#ffffff", "#c9302c")
ActualizarEstiloElemento(modern_portal, "#5cb85c", "#ffffff", "#4cae4c")
Plano del mundo real: Mapa de contenedor de límites del sistema empresarial de comercio electrónico
Este plano completo y de múltiples niveles de contenedor rastrea un ecosistema de comercio electrónico en línea. Aisla los servidores centrales internos utilizando un Contenedor_Sistema contenedor de bloque, implementa retransmisiones de notificaciones externas en la nube mediante System_Ext, mapea los almacenes de bases de datos relacionales internas junto con los microservicios externos de seguimiento, y fija los canales de comunicación usando parámetros explícitos de la pila tecnológica.
C4Container
título "Plantilla de Contenedores para Plataforma Empresarial de Comercio Electrónico"
Persona(cliente, "Comprador en Línea", "Explora artículos del catálogo y agrega productos a su carrito digital.")
System_Ext(pago_gateway, "Servicio API de Stripe", "Bóveda de tarjetas de crédito de terceros y motor de procesamiento.")
System_Boundary(alcance_e_commerce, "Perímetro Central de Comercio Electrónico") {
Contenedor(aplicacion_front, "Aplicación Web de Tienda", "Next.js, React", "Entrega activos estáticos y gestiona sesiones de carrito de usuario.")
Contenedor(servicio_checkout, "Microservicio de Checkout", "Node.js, Express", "Procesa flujos de trabajo del carrito de compras y calcula impuestos.")
ContenedorDb(base_datos_pedidos, "Base de Datos del Libro de Pedidos", "PostgreSQL", "Almacena líneas de transacciones históricas y registros de libro seguro.")
}
%% Caminos de Interacción Arquitectónica
Rel(cliente, aplicacion_front, "Visualiza productos y realiza pedidos usando", "HTTPS/Navegador")
Rel_Down(aplicacion_front, servicio_checkout, "Envía transacciones de carga de compra mediante", "JSON/REST API")
Rel_Derecha(servicio_checkout, base_datos_pedidos, "Persiste estados transaccionales dentro de", "SQL/Conexión JDBC")
Rel_Izquierda(servicio_checkout, pago_gateway, "Autoriza llamadas de cargo tokenizadas con", "API Segura TLS/HTTPS")
Errores comunes de sintaxis y restricciones del sistema
Al compilar mapas C4 limpios para marcos de software, ten cuidado con estos parámetros de ejecución para evitar que los diagramas se dañen:
- Formato de separadores de coma: A diferencia de casi cualquier otro esquema de Mermaid, los macros C4 requieren comas estrictas entre los parámetros:
Persona(id, "Etiqueta", "Desc"). Olvidar una coma separadora hará que el constructor de diseño falle por completo. - Comillas reservadas para etiquetas: Los campos de visualización, etiquetas técnicas y bloques de descripción dentro de los macros *deben* estar envueltos en comillas dobles claras. Incluir textos sin envolver entre comillas provoca errores de análisis que rompen el proceso.
- Orden de anidamiento de límites: Cuando envuelves elementos dentro de un
System_BoundaryoEnterprise_Boundarybloque, debes borrar explícitamente el contenido de su área de trabajo usando corchetes estándar{ }. Dejar un corchete de límite abierto o emparejarlos incorrectamente rompe los diseños de renderizado. - Instanciación dinámica de alias: No puedes dibujar relaciones (
Rel) a un identificador de alias que no haya sido inicializado explícitamente por un bloque de macro de elemento por encima. Mantén tu flujo de declaración avanzando progresivamente de arriba hacia abajo.