Modelo C4

Los cuatro niveles

Nivel	Pregunta que responde	Audiencia
1. Contexto	¿Qué sistema construimos, quién lo usa y con qué se integra?	Todo el mundo, incluido negocio
2. Contenedores	¿Qué aplicaciones y almacenes de datos ejecutables lo componen?	Técnicos, operaciones
3. Componentes	¿Cómo se organiza internamente un contenedor?	Desarrolladores del equipo
4. Código	¿Qué clases o módulos implementan un componente?	Rara vez necesario

Un contenedor en C4 no es un contenedor Docker: es cualquier cosa que se ejecuta o almacena datos por separado (una API, una SPA, una base de datos, una función serverless, un bucket).

Además existen diagramas complementarios: paisaje de sistemas (varios sistemas de la organización), dinámico (secuencia de interacciones para un caso) y de despliegue (cómo se mapean contenedores a infraestructura).

Reglas de notación

• Cada elemento lleva nombre, tipo y una frase de responsabilidad.
• Cada relación es unidireccional y lleva un verbo y, en nivel 2, la tecnología: «Envía eventos de solicitud [Kafka, Avro]».
• Incluye leyenda. Los colores y formas son libres, pero deben explicarse.
• Un diagrama, un nivel de abstracción. No mezcles una tabla de base de datos con un sistema externo.

Ejemplo: diagramas como código con Structurizr DSL

workspace "Originación" {
  model {
    cliente = person "Solicitante" "Pide un crédito desde el móvil"
    buro = softwareSystem "Buró de crédito" "Externo" { tags "Externo" }
    originacion = softwareSystem "Originación" {
      app = container "App móvil" "Captura la solicitud" "React Native"
      api = container "API de solicitudes" "Valida y orquesta" "Spring Boot"
      db  = container "Base de solicitudes" "Estado de cada solicitud" "PostgreSQL" {
        tags "Database"
      }
    }
    cliente -> app "Rellena la solicitud"
    app -> api "Envía la solicitud" "HTTPS/JSON"
    api -> db "Lee y escribe" "JDBC"
    api -> buro "Consulta el historial" "HTTPS/mTLS"
  }
  views {
    systemContext originacion { include * autolayout lr }
    container originacion { include * autolayout lr }
  }
}

Del mismo modelo salen las vistas de contexto y de contenedores, de modo que un cambio en una relación se refleja en todas. Alternativas válidas: PlantUML con C4-PlantUML, Mermaid (C4Context) o D2.

Antipatrones frecuentes

• Flechas sin etiqueta o bidireccionales: no se sabe quién inicia ni qué viaja.
• Diagrama de componentes para todo: el nivel 3 envejece rápido; dibújalo solo donde aporta.
• Mezclar lógico y físico: el diagrama de despliegue existe para hablar de nodos, regiones y redes.
• Dibujo único en una herramienta gráfica: nadie lo actualiza. Prefiere texto versionado.

Diagrama de despliegue

deploymentEnvironment "Producción" {
  deploymentNode "Google Cloud" {
    deploymentNode "us-east1" {
      deploymentNode "Cloud Run" {
        containerInstance api
      }
      deploymentNode "Cloud SQL (HA, zonas b/c)" {
        containerInstance db
      }
    }
  }
  deploymentNode "Dispositivo del cliente" {
    deploymentNode "iOS / Android" { containerInstance app }
  }
}

Este nivel muestra regiones, redes, réplicas y servicios gestionados: es el diagrama de referencia en revisiones de seguridad, recuperación ante desastres y costes.

Cuántos diagramas mantener

Diagrama	Por sistema	Frecuencia de actualización
Paisaje de sistemas	Uno para la organización	Al añadir o retirar sistemas
Contexto	Uno	Al cambiar integraciones externas
Contenedores	Uno	Al añadir servicios o almacenes
Componentes	Solo los contenedores complejos	Raramente; o generarlo del código
Dinámicos	Los 2–3 flujos críticos	Al cambiar el flujo
Despliegue	Uno por entorno relevante	Al cambiar la infraestructura

Pocos diagramas actualizados valen más que muchos obsoletos.

Checklist de revisión de un diagrama

• ¿Tiene título que indique tipo de diagrama y alcance?
• ¿Cada elemento tiene nombre, tipo/tecnología y responsabilidad?
• ¿Cada flecha tiene dirección, verbo y, en el nivel de contenedores, protocolo?
• ¿Hay leyenda para colores, formas y líneas discontinuas?
• ¿Se entiende sin que lo explique su autor?
• ¿Mezcla niveles de abstracción?
• ¿Están marcados los sistemas externos y los límites de confianza?

Integrarlo en el trabajo

Genera las imágenes en CI desde el modelo (Structurizr CLI, PlantUML o D2) y publícalas en el portal de documentación o el catálogo de servicios (Port). Incluye el diagrama de contenedores en la plantilla de ADR cuando la decisión cambia relaciones entre contenedores.

Criterios de implementación

Empieza por el diagrama de contexto y el de contenedores de cada sistema; suelen cubrir el 80 % de las conversaciones. Guárdalos en el repositorio junto a los ADR y revísalos en los pull requests que cambien integraciones. Usa el diagrama de despliegue para revisiones de seguridad y threat modeling.