System Design
Diagramas C4
Explica el modelo C4 para comunicar contexto, contenedores, componentes y código según la audiencia, manteniendo relaciones y responsabilidades coherentes.
- Última actualización
- Actualizada
- Nivel
- Aplicación
System Design
Explica el modelo C4 para comunicar contexto, contenedores, componentes y código según la audiencia, manteniendo relaciones y responsabilidades coherentes.
C4 organiza la comunicación arquitectónica por niveles de zoom. Su valor no está en producir cuatro diagramas obligatorios, sino en evitar mezclar personas, sistemas, procesos, módulos y clases en una sola vista.
C4 propone cuatro niveles: Context, Container, Component y Code. Cada uno responde una pregunta distinta para una audiencia concreta.
Context → ¿quién usa el sistema y con qué sistemas externos colabora?
Container → ¿qué aplicaciones, servicios y almacenes forman la solución?
Component → ¿cómo se divide internamente un contenedor?
Code → ¿qué estructuras concretas implementan una parte?Los diagramas “de arquitectura” suelen mezclar elementos de escalas incompatibles: usuario, frontend, función, clase, región y base de datos. El resultado parece detallado, pero no responde con claridad ninguna pregunta.
C4 fuerza a elegir un nivel y mantener una jerarquía coherente.
Muestra:
No muestra bases de datos internas, frameworks ni clases.
C4Context
title Contexto de DomiSys
Person(customer, "Cliente", "Realiza y consulta pedidos")
Person(staff, "Personal de tienda", "Gestiona catálogo, inventario y pedidos")
System(domisys, "DomiSys", "Centraliza operación comercial")
System_Ext(payment, "Pasarela de pago", "Procesa pagos")
System_Ext(email, "Proveedor de notificaciones", "Entrega mensajes")
Rel(customer, domisys, "Compra y consulta", "HTTPS")
Rel(staff, domisys, "Opera la tienda", "HTTPS")
Rel(domisys, payment, "Solicita cobros", "HTTPS")
Rel(domisys, email, "Envía notificaciones", "API")El sistema de interés y sus fronteras quedan visibles. No se explica todavía cómo está construido internamente.
En C4, container significa unidad ejecutable o almacén de datos: aplicación web, API, worker, base de datos o broker. No se refiere exclusivamente a Docker.
C4Container
title Contenedores de DomiSys
Person(user, "Usuario", "Cliente o empleado")
System_Boundary(sys, "DomiSys") {
Container(web, "Web App", "Next.js", "Interfaces públicas y operativas")
Container(api, "Backend API", "Node.js", "Casos de uso y contratos")
Container(worker, "Workers", "Node.js", "Procesos asíncronos")
ContainerDb(db, "PostgreSQL", "PostgreSQL", "Datos transaccionales")
ContainerQueue(broker, "Broker", "Messaging", "Eventos y trabajos")
}
System_Ext(payment, "Pasarela", "Pagos")
Rel(user, web, "Usa", "HTTPS")
Rel(web, api, "Invoca", "JSON/HTTPS")
Rel(api, db, "Lee y escribe", "SQL")
Rel(api, broker, "Publica", "Events")
Rel(worker, broker, "Consume", "Events")
Rel(api, payment, "Cobra", "HTTPS")Explica módulos internos de un contenedor, como adaptadores, casos de uso, dominio y repositorios. Solo merece existir para contenedores cuya estructura necesite comunicación.
Puede usar diagramas de clases u otras representaciones. Normalmente conviene generarlo desde código o limitarlo a áreas complejas; documentar cada clase manualmente se desactualiza rápido.
Cada elemento debería incluir:
Cada relación debería indicar:
Malo:
API → DatabaseMejor:
Order API → PostgreSQL: persiste pedidos y outbox mediante SQLDefine exactamente qué estás documentando.
Identifica personas, sistemas externos y relaciones.
Enumera unidades ejecutables y almacenes reales.
No todos los contenedores necesitan diagrama de componentes.
Un contenedor del nivel 2 debe corresponder al límite abierto en el nivel 3.
Contrasta con repositorios, despliegues, ownership e integraciones actuales.
C4 organiza vistas estructurales por zoom. UML ofrece notaciones para clases, secuencias, estados, actividades y despliegue. Se complementan:
No intentes que C4 responda todas las preguntas.
Existen vistas complementarias:
Estas vistas no cambian los cuatro niveles principales; responden preguntas adicionales.
Un diagrama debe marcar si representa:
Mezclar lo actual con lo aspiracional dificulta soporte y decisiones.
El contexto puede mostrar tipos de usuarios y sistemas externos. El nivel container debe explicar dónde se aplica aislamiento, sin dibujar cada tenant como sistema separado.
Puede aparecer como un solo container con componentes internos. No necesita representarse como microservicios.
Funciones desplegadas separadamente pueden ser containers si tienen responsabilidad y ejecución independientes; no dibujes cada función trivial si la vista pierde legibilidad.
Una base o cola administrada sigue siendo container o sistema externo según ownership y frontera del sistema.
Es especialmente útil para onboarding, revisiones, documentación de sistemas y comunicación entre negocio y tecnología. Para una aplicación pequeña puede bastar Context y Container.
Diagramas de despliegue ubica los contenedores en infraestructura real y explica disponibilidad, red y operación.