El modelo C4 explicado con un ejemplo realista

El modelo C4 es fácil de explicar y igual de fácil de aplicar mal. Muchos equipos acaban con un diagrama gigante que mezcla usuarios, microservicios, clases Java y cajas de la nube, justo lo que C4 quiere evitar. Esta guía recorre un ejemplo completo de diagrama del modelo C4: un sistema inventado, dibujado en los niveles 1, 2 y 3, para que veas qué va en cada diagrama, quién lo lee y dónde aparecen los errores habituales.

El modelo C4 en un minuto

El modelo C4, creado por Simon Brown, describe la arquitectura de software como un conjunto de diagramas en los que puedes hacer zoom. Cada nivel responde a una pregunta distinta para un público distinto.

En C4, un "container" es cualquier cosa que se ejecuta o almacena datos por sí misma: una aplicación web, una API, un worker, una base de datos, una cola de mensajes o un topic. No se refiere específicamente a un contenedor Docker. C4 define abstracciones, no formas ni colores, así que la notación depende de ti. La referencia oficial está en c4model.com.

El sistema de ejemplo: Folio, una librería online

Para mantenerlo concreto usaremos un sistema inventado. Folio es una librería online ficticia, no una empresa real, que vende libros impresos y e-books.

• Los clientes exploran el catálogo, compran libros y descargan e-books.
• El equipo de back-office gestiona catálogo, stock y precios.
• Folio depende de tres sistemas externos: un proveedor de pagos, un servicio de envío de correo y el sistema de fulfilment de un socio logístico.

Nivel 1: diagrama de contexto (System Context)

El diagrama de contexto muestra Folio como una sola caja y todo lo que la rodea. Nada de detalle interno.

• Customer (Person): explora y compra libros.
• Back-office Staff (Person): gestiona catálogo, stock y precios.
• Folio (Software System, dentro del alcance): permite comprar libros impresos y e-books.
• Payment Provider (Software System, externo): autoriza y captura pagos con tarjeta.
• Email Service (Software System, externo): envía correos de pedido y de envío.
• Fulfilment System (Software System, externo, propiedad del socio logístico): prepara, empaqueta y envía los pedidos impresos.

Cada relación lleva una etiqueta que indica la intención:

• Customer → Folio: "Explora y compra libros usando"
• Back-office Staff → Folio: "Gestiona catálogo y stock usando"
• Folio → Payment Provider: "Cobra pagos con tarjeta usando"
• Folio → Email Service: "Envía correos de pedido usando"
• Folio → Fulfilment System: "Envía pedidos impresos a"

Para quién: product managers, nuevas incorporaciones, revisores de seguridad, otros equipos. Si alguien necesita más que un vistazo para entenderlo, está demasiado cargado. Los protocolos y tecnologías suelen quedar fuera de este nivel.

Nivel 2: diagrama de contenedores

Haz zoom en Folio. Las personas y los sistemas externos se quedan; Folio pasa a ser una boundary alrededor de sus contenedores.

Ahora las relaciones llevan intención y protocolo:

• Web Storefront → API Application: "Lee el catálogo, crea pedidos [JSON/HTTPS]"
• API Application → Main Database: "Lee y escribe [SQL/TCP]"
• API Application → Payment Provider: "Crea y captura pagos [HTTPS]"
• API Application → Order Events Queue: "Publica eventos OrderPaid [AMQP]"
• Order Worker → Order Events Queue: "Consume eventos OrderPaid [AMQP]"
• API Application → E-book Store: "Firma enlaces de descarga para archivos de e-books [HTTPS]"
• Order Worker → Fulfilment System: "Envía pedidos impresos [JSON/HTTPS]"
• Order Worker → Email Service: "Envía correos de confirmación [HTTPS]"

Para quién: ingenieros, arquitectos y SRE. En el día a día suele ser el diagrama C4 más útil: el que proyectas en una design review o le das a alguien nuevo en el equipo. Fíjate en lo que falta: Pods, VPC, balanceadores de carga. Su sitio es un diagrama de despliegue.

Nivel 3: diagrama de componentes

Haz zoom en un solo contenedor, la API Application. No todos los contenedores necesitan un diagrama de componentes; dibújalo donde el interior merezca una explicación.

• Catalogue Controller (controlador REST de Spring MVC): endpoints de búsqueda y ficha de libro.
• Checkout Controller (controlador REST de Spring MVC): endpoints de carrito y checkout.
• Order Service (servicio Spring): valida carritos, crea pedidos, publica eventos.
• Payment Gateway Client (componente Spring): encapsula la API del proveedor de pagos.
• Order Repository (Spring Data JPA): persiste pedidos.
• Catalogue Repository (Spring Data JPA): lee libros, precios y stock.

Las relaciones siguen la misma regla que en el nivel 2, por ejemplo Order Service → Payment Gateway Client "Solicita la captura del pago" y Order Repository → Main Database "[SQL/TCP]".

Para quién: los desarrolladores dueños de ese contenedor. Los diagramas de componentes son los que antes se quedan desactualizados.

Nivel 4, Code: no lo dibujes a mano. Genera diagramas de clases desde tu IDE cuando los necesites.

Consejos de notación para diagramas C4 legibles

• Cada caja tiene cuatro cosas: nombre, tipo de elemento, tecnología y una responsabilidad en una línea.

API Application
[Container: Java, Spring Boot]
Provides catalogue, ordering and account functionality via a JSON/HTTPS API.

• Etiqueta cada relación con la intención y, desde el nivel 2, con el protocolo. Una flecha que solo dice "Usa" no le cuenta nada al lector.
• Una dirección por flecha, descrita desde el punto de vista del origen.
• Añade una leyenda que explique formas, colores, estilos de línea y siglas. Una línea discontinua no significa nada hasta que dices qué significa.
• Pon título a cada diagrama con su tipo y alcance, por ejemplo "Diagrama de contenedores: Folio".
• Dibuja la boundary del sistema en alcance para que se vea qué es tuyo y a qué llamas.

Errores comunes

1. Saltar directamente a los componentes. Sin vista de contexto ni de contenedores, nadie sabe dónde vive un componente ni por qué existe.
2. Mezclar niveles. Una Person, un Pod y una clase Java en el mismo diagrama: ninguno queda bien explicado.
3. Flechas sin etiqueta. Sin intención ni protocolo, el lector tiene que adivinar, y cada uno adivina distinto.
4. Dibujar el nivel Code a mano. Queda obsoleto al día siguiente.
5. Infraestructura en el diagrama de contenedores. Namespaces, subredes y tipos de instancia van en un diagrama de despliegue.

Diagramas complementarios: despliegue y dinámico

C4 también define vistas de apoyo. Dos son especialmente útiles:

• Diagrama de despliegue: asigna los contenedores a la infraestructura. Para Folio podría ser la API Application y el Order Worker como Deployments en un clúster de Kubernetes, PostgreSQL como base de datos gestionada y el E-book Store en almacenamiento de objetos. Aquí es donde va el detalle de Kubernetes y nube.
• Diagrama dinámico: muestra un flujo concreto en pasos numerados, por ejemplo "Un cliente compra un e-book": 1) el Storefront envía el checkout, 2) la API captura el pago, 3) la API publica OrderPaid, 4) el worker envía el correo con el enlace de descarga.

Cómo crear este ejemplo de diagrama del modelo C4 en Archboard

Archboard tiene un pack C4 Model con nodos Person, Software System, Container, Component y Database, además de boundaries. Son nodos de primera clase con puertos, no formas genéricas, así que las relaciones se conectan de puerto a puerto.

1. Inicia sesión con Google o GitHub y crea un diagrama.
2. Nivel 1: coloca dos nodos Person (Customer, Back-office Staff), un nodo Software System para Folio y tres nodos External System para los sistemas de pagos, correo y fulfilment. Conecta los puertos y etiqueta cada conexión con su intención.
3. Nivel 2: añade una boundary para Folio y coloca nodos Container para Web Storefront, Admin Portal, API Application, Order Worker, Order Events Queue y E-book Store, más un nodo Database para Main Database. Rellena nombre, tecnología y responsabilidad, y etiqueta las conexiones con intención y protocolo.
4. Nivel 3: añade una boundary para la API Application y coloca dentro los nodos Component.
5. Leyenda y notas: usa un bloque Markdown o una Table de los elementos Core para la leyenda, y un Frame para mantener cada nivel en su propia zona del canvas infinito.
6. La vista de despliegue al lado: las vistas C4 pueden convivir en el mismo canvas con los packs Kubernetes y Cloud. Dibuja un frame Namespace con nodos Deployment, Service e Ingress para la API Application y el Order Worker, justo al lado de la vista de contenedores que implementan.

Como Archboard es un canvas, dibujas cada vista de forma deliberada: decides qué va en cada nivel, y los nodos C4 conviven en el mismo board con los nodos de los packs Kubernetes y Cloud. Así, la vista de despliegue queda justo al lado de la vista de contenedores.

En el plan Free un diagrama admite 15 nodos de diagrama más 150 notas, textos, pegatinas y temas de mapa mental, suficiente para un nivel C4 por diagrama en un sistema como Folio. Pro elimina los límites de nodos y diagramas si quieres todos los niveles en un solo canvas. Más sobre flujos de trabajo C4: caso de uso C4.

Plantilla gratuita

El ejemplo de vista de contenedores C4 es un diagrama público que puedes copiar a tu espacio de trabajo con Usar este ejemplo. Úsalo para la disposición de boundaries y luego etiqueta cada conexión con su intención y protocolo, como se describe arriba.

Preguntas frecuentes

¿Necesito los cuatro niveles? No. La mayoría de equipos obtiene casi todo el valor de los diagramas de contexto y de contenedores. Añade diagramas de componentes de forma selectiva y genera vistas de código solo si las necesitas.

¿Un container de C4 es un contenedor Docker? No. Es cualquier unidad que se ejecuta o despliega por separado, incluidas bases de datos y SPAs. Puede correr en Docker o no.

¿Dónde van los detalles de Kubernetes? En un diagrama de despliegue. El diagrama de contenedores se centra en responsabilidades y comunicación.

Empieza gratis — un asiento, sin tarjeta de crédito