Diagramas C4
Fuente: el modelo C4 oficial en https://c4model.com/. Aplica estas reglas cada vez que dibujes, revises o expliques un diagrama C4. Carga también el skill de escritura cuando la salida incluya prosa (ADR, documentos, descripciones de PR).
1. Propósito
C4 es un conjunto de "mapas de tu código" en cuatro niveles de zoom: Contexto, Contenedores, Componentes, Código. Simon Brown lo creó, inspirado en UML y el modelo de vistas 4+1, para reemplazar los diagramas ad hoc de cajas y líneas. Fallos típicos que soluciona: sin leyenda, abstracciones mezcladas, flechas sin etiqueta, tecnología ausente y etiquetas vagas como "lógica de negocio".
C4 es independiente de la notación y de las herramientas. Las abstracciones y las reglas que se indican a continuación son lo que importa; las formas no.
2. Abstracciones
Jerarquía: Persona -> Sistema de Software -> Contenedor -> Componente -> Código. Cada nivel se acerca a un elemento del nivel superior.
| Abstracción | Definición | Ejemplos |
|---|---|---|
| Persona | Un usuario humano, actor, rol o persona del sistema | Cliente, Agente de Soporte, Administrador |
| Sistema de Software | Nivel más alto de abstracción; aporta valor a los usuarios. Normalmente es propiedad de un solo equipo y lo construye. No es un dominio de producto, contexto delimitado, tribu o squad | Plataforma de Ticketing, Sistema de Pagos |
| Contenedor | Una aplicación o almacén de datos que se ejecuta/despliega de forma independiente dentro de un sistema de software | Aplicación web del lado del servidor, SPA, aplicación de escritorio, aplicación móvil, función serverless, aplicación por lotes/consola, API de microservicio, esquema de base de datos, almacenamiento S3/blob, CDN, sistema de archivos, script de shell |
| Componente | Una agrupación de funcionalidad relacionada detrás de una interfaz bien definida, dentro de un contenedor. No se puede desplegar por separado: todos los componentes de un contenedor comparten un espacio de proceso | OrderController, PaymentService, EmailSender |
| Código | Clases, interfaces, funciones o tablas de base de datos dentro de un componente | class OrderValidator, tabla orders |
Reglas de los contenedores (Preguntas frecuentes de C4)
- Un contenedor C4 no es Docker. Es una aplicación o almacén de datos ejecutable/desplegable, independientemente del empaquetado.
- Una aplicación HTML renderizada en el servidor es 1 contenedor. Un servidor más un SPA o cliente móvil son 2 contenedores que se comunican a través de una API remota.
- Los JAR, DLL, assemblies y módulos no son contenedores. Organizan el código dentro de un contenedor.
- Los servicios de datos gestionados (S3, RDS, CDN) son contenedores dentro del límite de tu sistema cuando tú posees o controlas los buckets o esquemas. No son sistemas externos.
Reglas de los componentes
- Un componente no es una carpeta, paquete o JAR. Es una agrupación funcional con una interfaz.
- Los componentes no se pueden desplegar de forma independiente. Si se despliega por separado, es un contenedor.
Adaptación de la terminología
Los equipos pueden sustituir nombres idiomáticos del lenguaje (por ejemplo Módulo o Función en código funcional) cuando definen el término explícitamente en el diagrama o en su documentación. No inventes niveles de abstracción adicionales a menos que cada uno esté estrictamente definido.
3. Patrones de modelado especiales
Colas y tópicos
- Incorrecto: un único "Bus de Mensajes" gigante en el centro con todos los servicios conectados (hub-and-spoke). Oculta quién produce y quién consume qué.
- Opción 1 (preferida): modela cada cola o tópico como su propio contenedor (un almacén de datos de mensajes). Los productores escriben en él, los consumidores leen o se suscriben a él.
- Opción 2: para acoplamiento directo punto a punto, omite la caja de la cola y etiqueta la relación
"Publica eventos de pedido a través de Cola orders [AMQP]". Opcionalmente, estiliza estas líneas de forma diferente a las llamadas HTTP (explícalo en la leyenda).
Por ejemplo: Order API --"Publica OrderPlaced en [Kafka]"--> [(orders topic)] --"Lee OrderPlaced desde [Kafka]"--> Fulfilment Worker.
Microservicios (Regla de la Ley de Conway)
- Un equipo posee todo el sistema de software: modela cada microservicio como un grupo de contenedores dentro del límite de ese sistema (contenedor de API más su propio contenedor de esquema de base de datos, o un único contenedor Lambda sin estado).
- Equipos separados poseen cada servicio: promociona cada servicio de propiedad independiente a su propio Sistema de Software, cada uno con sus propios diagramas de Contexto del Sistema y de Contenedores. Indica la propiedad de la cola/tópico explícitamente a través de los límites del sistema.
4. Catálogo de diagramas
Niveles estáticos principales
| Nivel | Diagrama | Recomendado | Alcance | Audiencia | Mostrar / omitir |
|---|---|---|---|---|---|
| 1 | Contexto del Sistema | Sí | 1 sistema de software | Técnica y no técnica | Personas y sistemas externos alrededor del sistema. Omitir tecnología y protocolos de bajo nivel |
| 2 | Contenedor | Sí | 1 sistema de software | Técnica, operaciones | Opciones tecnológicas principales y protocolos entre procesos. Omitir clustering, balanceadores de carga, recuperación tras fallos |
| 3 | Componente | No: solo cuando aporte valor claro, idealmente automatizado | 1 contenedor | Arquitectos, desarrolladores | Componentes dentro de un contenedor y sus interacciones |
| 4 | Código | No: generar bajo demanda en el IDE | 1 componente | Desarrolladores | Diagrama de clases UML o DER |
Diagramas de apoyo
| Diagrama | Recomendado | Uso |
|---|---|---|
| Paisaje del Sistema | Sí, para organizaciones y carteras | Mapa empresarial o departamental de todos los sistemas y personas. Un diagrama de Contexto sin un sistema de enfoque único |
| Dinámico | No: usar con moderación | Colaboraciones complejas en tiempo de ejecución. Estilo de colaboración numerada o estilo de secuencia UML |
| Despliegue | Sí | 1 entorno (producción, staging, desarrollo). Nodos de despliegue anidados (físicos, VM, Docker, Kubernetes, runtime) que contienen instancias de sistema/contenedor, más nodos de infraestructura (DNS, balanceadores de carga, cortafuegos) |
Compatibilidad
- arc42: Contexto y Alcance -> L1; Nivel de Bloque de Construcción 1 -> L2; Nivel de Bloque de Construcción 2 -> L3; Nivel de Bloque de Construcción 3 -> L4.
- UML: complementa C4 con diagramas UML de estado, secuencia y ERD para flujos de trabajo, máquinas de estado y modelos de datos.
Regla de escalado
Cuando un diagrama se satura, no metas docenas de cajas en un solo lienzo. Divide en el mismo nivel de abstracción por área de negocio, contexto delimitado, característica o enfoque de un solo servicio (el servicio central más sus vecinos entrantes y salientes).
5. Reglas de notación
Diagrama
- El título indica el tipo de diagrama y el alcance:
Diagrama de Contenedores para el Sistema de Pago. - Incluye siempre una clave/leyenda que explique formas, colores, bordes, tipos de línea, puntas de flecha y acrónimos.
- Mantén una pureza estricta de abstracción: nunca mezcles niveles de abstracción (por ejemplo, no incluyas cajas de
Componentedentro de un diagrama de Contenedores L2), y nunca pongas protocolos o pasos de implementación internos ([HTTPS],paquete enmascarado,tool_runner) dentro de un diagrama de Contexto del Sistema L1. - Al comparar arquitecturas competidoras o históricas, etiqueta los títulos de los límites explícitamente (
Opción A (Reemplazada)vs.Opción B (Actual)) y actualiza todos los diagramas en el documento cada vez que los requisitos o supuestos cambien.
Elemento
- Nombre, tipo de elemento explícito (
Persona,Sistema de Software,Contenedor,Componente,Base de Datos,Nodo de Despliegue) y una descripción concisa de la responsabilidad. - Tecnología explícita en cada contenedor, componente y nodo de despliegue.
Relación
- Solo flechas unidireccionales. Nunca
<-->. Si los datos fluyen en ambas direcciones, muestra la dirección del iniciador y describe la respuesta en la etiqueta. - Etiquetas con verbos activos específicos. Nunca un simple "Usa". Escribe
Envía pedidos a,Lee mapa de asientos de. - Protocolo/tecnología en las relaciones entre contenedores:
[JSON/HTTPS],[SQL],[gRPC],[AMQP].
6. Mermaid en Markdown
Usa por defecto flowchart (flowchart TB o LR), no el C4Context/C4Container nativo de Mermaid. La sintaxis C4 nativa es experimental y a menudo falla al renderizarse en los visores de Markdown. Emítela solo si el usuario lo solicita explícitamente y confirma que el renderizador lo soporta.
Convenciones para flowchart:
- Usa
subgraphpara el límite del sistema (Contenedores/Componentes) o nodos de despliegue. - Usa
[(...)]para bases de datos, almacenes de datos, colas y tópicos. - Etiquetas HTML entre comillas:
"<b>Nombre</b><br/>«Contenedor: Tecnología»<br/>Responsabilidad breve". - Flechas con etiquetas entre comillas:
A -->|"Acción [Protocolo]"| B. - Un
classDefpor tipo de elemento, aplicado de forma consistente. - Se requiere un
Legendsubgraph compacto (nodos no conectados, anclado en la parte inferior con un enlace invisiblebottomNode ~~~ Legendcuando Dagre lo coloca arriba) siempre que se usen colores, formas cilíndricas o múltiples estilos de línea; coloca un título como encabezado o en una líneaTitle: ...directamente sobre el bloque de código. - Diagramas dinámicos:
sequenceDiagram, o unflowchartcon etiquetas de flecha numeradas (1. Envía pedido [JSON/HTTPS]). - Diagramas de despliegue:
subgraphs anidados en unflowchart. - Pon siempre entre comillas las etiquetas que contengan paréntesis, corchetes o dos puntos.
- Nunca pongas punto y coma (
;) sin escapar dentro de las etiquetas desequenceDiagramostateDiagram-v2(Mermaid trata;como terminador de sentencia y divide el texto restante en estados falsos o errores de análisis); envuelve los bloquesNotelargos ensequenceDiagramcon<br/>para que el texto nunca se corte en el borde del viewport.
Plantilla: L1 Contexto del Sistema
Título: Diagrama de Contexto del Sistema para Plataforma de Ticketing
flowchart TB
customer["<b>Cliente</b><br/>«Persona»<br/>Compra entradas para eventos"]
ticketing["<b>Plataforma de Ticketing</b><br/>«Sistema de Software»<br/>Permite a los clientes explorar eventos y comprar entradas"]
payments["<b>Proveedor de Pagos</b><br/>«Sistema de Software, externo»<br/>Cobra tarjetas"]
email["<b>Servicio de Correo</b><br/>«Sistema de Software, externo»<br/>Entrega correos de confirmación"]
customer -->|"Explora eventos y compra entradas usando"| ticketing
ticketing -->|"Solicita cargos a tarjeta a"| payments
ticketing -->|"Envía correos de confirmación usando"| email
email -->|"Entrega correos de confirmación a"| customer
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef system fill:#1168bd,stroke:#0b4884,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class ticketing system
class payments,email external
subgraph Leyenda
direction LR
l1["Persona"]:::person
l2["Sistema de Software (en alcance)"]:::system
l3["Sistema de Software (externo)"]:::external
end
Plantilla: L2 Contenedor (con contenedor de cola)
Título: Diagrama de Contenedores para Plataforma de Ticketing
flowchart TB
customer["<b>Cliente</b><br/>«Persona»<br/>Compra entradas para eventos"]
payments["<b>Proveedor de Pagos</b><br/>«Sistema de Software, externo»<br/>Cobra tarjetas"]
subgraph boundary["Plataforma de Ticketing [Sistema de Software]"]
spa["<b>Web App</b><br/>«Contenedor: React SPA»<br/>Exploración de eventos y UI de pago"]
api["<b>API de Pedidos</b><br/>«Contenedor: Java, Spring Boot»<br/>Valida y coloca pedidos"]
db[("<b>DB de Pedidos</b><br/>«Contenedor: PostgreSQL»<br/>Almacena pedidos y entradas")]
topic[("<b>tópico de pedidos</b><br/>«Contenedor: tópico Kafka»<br/>Eventos OrderPlaced")]
worker["<b>Trabajador de Cumplimiento</b><br/>«Contenedor: Python»<br/>Emite entradas y envía correos"]
end
customer -->|"Explora y compra usando [HTTPS]"| spa
spa -->|"Envía pedidos a [JSON/HTTPS]"| api
api -->|"Escribe pedidos en [SQL/TCP]"| db
api -->|"Publica OrderPlaced en [Kafka]"| topic
worker -->|"Lee OrderPlaced desde [Kafka]"| topic
worker -->|"Actualiza estado de entrada en [SQL/TCP]"| db
api -->|"Solicita cargos a tarjeta a [JSON/HTTPS]"| payments
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef container fill:#438dd5,stroke:#2e6295,color:#fff
classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class spa,api,worker container
class db,topic store
class payments external
subgraph Leyenda
direction LR
l1["Persona"]:::person
l2["Contenedor"]:::container
l3[("Almacén de datos / cola / tópico")]:::store
l4["Sistema externo"]:::external
end
Nota de leyenda: las flechas apuntan desde el iniciador al destino. La etiqueta indica la acción y [protocolo].
Plantilla: Despliegue
Título: Diagrama de Despliegue para Plataforma de Ticketing (Producción)
flowchart TB
users["<b>Navegador del cliente</b><br/>«Nodo de Despliegue: Chrome»"]
subgraph aws["AWS «Nodo de Despliegue: Cloud, us-east-1»"]
dns["<b>Route 53</b><br/>«Nodo de Infraestructura: DNS»"]
lb["<b>Balanceador de Carga</b><br/>«Nodo de Infraestructura: ALB»"]
subgraph eks["EKS «Nodo de Despliegue: clúster Kubernetes»"]
subgraph pod["pod order-api «Nodo de Despliegue: Docker, x3»"]
api["<b>API de Pedidos</b><br/>«Instancia de Contenedor: Java, Spring Boot»"]
end
end
subgraph rds["RDS «Nodo de Despliegue: PostgreSQL 16»"]
db[("<b>DB de Pedidos</b><br/>«Instancia de Contenedor: esquema PostgreSQL»")]
end
end
users -->|"Resuelve nombre de host usando [DNS]"| dns
users -->|"Envía solicitudes a [HTTPS]"| lb
lb -->|"Reenvía solicitudes a [HTTP]"| api
api -->|"Lee y escribe pedidos en [SQL/TCP]"| db
Agrega un subgraph de Leyenda si usas colores o estilos más allá de los predeterminados.
Plantilla: Dinámico (Secuencia)
Título: Diagrama dinámico (estilo secuencia) para Pago de Pedido en Plataforma de Ticketing
sequenceDiagram
autonumber
actor customer as Cliente
participant spa as Web App (React SPA)
participant api as API de Pedidos (Spring Boot)
participant payments as Proveedor de Pagos
participant db as DB de Pedidos (PostgreSQL)
participant topic as tópico de pedidos (Kafka)
customer->>spa: Hace clic en "Realizar Pedido"
spa->>api: POST /orders [JSON/HTTPS]
api->>payments: Cobra tarjeta [JSON/HTTPS]
payments-->>api: Pago autorizado
api->>db: Inserta fila de pedido [SQL/TCP]
api->>topic: Publica OrderPlaced [Kafka]
api-->>spa: 201 Creado (confirmación de pedido)
spa-->>customer: Muestra recibo de pedido
Mantén las etiquetas de los participantes y mensajes de sequenceDiagram libres de barras inclinadas no escapadas, punto y coma (;, que Mermaid analiza como terminadores de sentencia), o saltos de línea sin procesar para máxima compatibilidad con visores de Markdown.
7. Diagramas
...
[truncado para traducción]