Módulo 3: Comunicar la arquitectura

2. El C4 model: cuatro niveles de zoom

Siguiente →

Descripción

Al terminar esta lección vas a conocer el C4 model de Simon Brown, la herramienta que convierte "hay que elegir el zoom del diagrama" de una buena intención en un método con cuatro niveles nombrados. Las cuatro C son Context, Container, Component y Code —cuatro maneras de mirar el mismo sistema, de más lejos a más cerca—. Cada una responde una pregunta distinta para una audiencia distinta, exactamente como los niveles de zoom de un mapa: el Context es el mapa del mundo (qué hace el sistema y con quién habla), el Container es el mapa de la ciudad (de qué piezas desplegables se compone), el Component es el mapa del barrio (qué hay dentro de una pieza) y el Code es el mapa de la calle (cómo está escrito ese componente). La genialidad del C4 no es que sea sofisticado —es todo lo contrario—: es que con una sola notación de cajas y flechas y cuatro niveles de zoom cubres casi toda la necesidad de comunicar una arquitectura, sin memorizar la sopa de símbolos de notaciones más pesadas que casi nadie recuerda.

Esto importa porque el problema que el C4 resuelve es real y viejo. Antes del C4, "hacer un diagrama de arquitectura" no tenía reglas: cada quien dibujaba cajas de tamaños distintos, con significados distintos, mezclando en la misma lámina cosas de niveles de abstracción muy diferentes —un usuario, una base de datos, una clase de Java, una cola de mensajes, todo junto—. El resultado era el diagrama que "muestra el sistema" y que nadie sabe leer, porque no hay acuerdo sobre qué es una caja ni a qué distancia estás mirando. El C4 pone orden con una regla simple: decide primero a qué distancia miras —cuál de las cuatro C— y en ese diagrama solo entran las cajas de ese nivel. Un diagrama, un zoom. La completitud no vive en una lámina que lo muestra todo; vive en el conjunto de diagramas, cada uno limpio en su nivel.

Conexión con el módulo: en la lección 1 viste, con Google Maps, que comunicar una arquitectura es elegir el zoom según quién mira. Esta lección le pone nombre y estructura a esos zooms: los cuatro niveles del C4. Es el vocabulario que necesitas antes de poder dibujar nada —no puedes "elegir el nivel correcto para la audiencia" (lección 5) si no tienes los niveles nombrados—. En las lecciones 3 y 4 vas a dibujar cada nivel a fondo sobre Mercado: Context y Container (los dos que más usarás) en la 3, Component y Code (y cuándo parar) en la 4. Aquí construyes la escalera; en las dos siguientes bajas por ella, peldaño a peldaño.

Google Maps otra vez: la escalera de zooms

Vuelve a Google Maps, porque el C4 es literalmente eso. Imagina que empiezas viendo el planeta y vas apretando el botón de acercar, un nivel a la vez, hasta llegar a la puerta de una casa. Cada apretón te quita contexto y te da detalle:

  • Zoom 1 — el mundo. Ves continentes y países. Respondes: "¿dónde queda este país respecto a los demás?". No ves ni una calle, y no las echas de menos.
  • Zoom 2 — la ciudad. Ves avenidas, distritos, ríos, estaciones. Respondes: "¿cómo me muevo dentro de esta ciudad?". Perdiste la vista del país entero, pero ganaste las calles principales.
  • Zoom 3 — el barrio. Ves las cuadras, los edificios, los nombres de las calles pequeñas. Respondes: "¿qué hay en esta zona y cómo se conecta por dentro?".
  • Zoom 4 — la calle. Ves el número de la casa, la entrada, el árbol de la esquina. Respondes: "¿exactamente dónde está esta dirección?".

Tres cosas de esta escalera son el C4 entero. Primera: cada zoom responde una pregunta y sirve a alguien distinto —el que planea un viaje internacional usa el mundo, el mensajero usa la calle—. Segunda: subir es alejarse y bajar es acercarse —más contexto arriba, más detalle abajo, y no puedes tener los dos al máximo a la vez—. Tercera, la más importante: no mezclas zooms en una lámina. Google Maps nunca te muestra los continentes con los números de las casas encima; sería ilegible. Cuando quieres bajar de la ciudad al barrio, el mapa entero cambia de nivel, coherente consigo mismo. El C4 te pide exactamente esa disciplina para tus diagramas: elige un nivel, quédate en él, y si necesitas otro nivel, haz otro diagrama.

Las cuatro C, una por una

Context (nivel 1 — el mapa del mundo). Tu sistema es una sola caja en el centro, y alrededor están las personas que lo usan y los sistemas externos con los que habla. No muestra nada de cómo está construido por dentro —ni tecnologías, ni piezas, ni bases de datos—. Responde: ¿qué hace este sistema, quién lo usa y de qué otros sistemas depende? Su audiencia es la más amplia: cualquiera, incluido el negocio, un VP, un cliente, un inversionista. Es el único diagrama que puedes poner enfrente de alguien no técnico y esperar que lo entienda sin explicarle notación.

Container (nivel 2 — el mapa de la ciudad). Haces zoom dentro de esa única caja y ves las piezas desplegables de las que se compone el sistema: la aplicación web, la app móvil, la API del backend, la base de datos, el índice de búsqueda. "Container" aquí no significa Docker —significa algo que se ejecuta y se despliega por separado: un proceso, una app, una base de datos—. Cada container muestra su tecnología principal (React, FastAPI, PostgreSQL). Responde: ¿de qué piezas se compone el sistema, cuál es la responsabilidad de cada una y cómo se comunican? Su audiencia es técnica: arquitectos, desarrolladores, gente de operaciones. Es el diagrama más útil del conjunto para orientar a alguien que va a trabajar en el sistema.

Component (nivel 3 — el mapa del barrio). Haces zoom dentro de un container —digamos la API— y ves los componentes que lo forman: agrupaciones de código con una responsabilidad clara (el controlador de pedidos, el calculador de impuestos, el cliente del gateway de pagos). Responde: ¿qué hay dentro de esta pieza y cómo colaboran sus partes? Su audiencia es acotada: los desarrolladores que trabajan en ese container. No dibujas un Component de cada container —solo de los que son complejos y valen la pena—.

Code (nivel 4 — el mapa de la calle). Haces zoom dentro de un componente y ves las clases, interfaces y funciones concretas —un diagrama de clases UML, por ejemplo—. Responde: ¿cómo está escrito exactamente este componente? Su audiencia es la más estrecha: el dev que va a editar ese código hoy. Y aquí viene la sorpresa que veremos en la lección 4: este nivel casi nunca se dibuja a mano, porque el detalle a esa escala cambia todos los días y un dibujo hecho a mano envejece en horas. Cuando de verdad lo necesitas, lo genera una herramienta a partir del código real, o simplemente abres el código. El C4 lo incluye por completitud, pero el trabajo del arquitecto vive casi siempre en los niveles 1 y 2.

Ejemplo trabajado: la escalera del C4, ejecutada

Pongamos la escalera en una tabla que puedas correr, para fijar qué pregunta responde cada nivel y a quién sirve. El siguiente código no dibuja diagramas: imprime la escalera de zooms —los cuatro niveles del C4 emparejados con su analogía de mapa, la pregunta que responden y su audiencia—, para que el modelo mental quede claro antes de dibujar en las próximas lecciones.

# C4 como los niveles de zoom de un mapa: eliges el zoom segun lo que buscas.
# Nadie navega una ciudad con el mapa del mundo, ni cruza el pais con el de la calle.

zoom_ladder = [
    # (nivel C4, analogia de mapa, pregunta que responde, audiencia principal)
    ("Context",   "mapa del mundo",   "Que hace el sistema y con quien habla?", "cualquiera, incluido el negocio"),
    ("Container", "mapa de la ciudad", "De que piezas desplegables se compone?", "gente tecnica"),
    ("Component", "mapa del barrio",   "Que hay DENTRO de una pieza?",           "devs de esa pieza"),
    ("Code",      "mapa de la calle",  "Como esta escrito ese componente?",      "el dev que lo edita hoy"),
]

print("Los cuatro niveles del C4, como cuatro zooms de un mismo mapa:")
print()
print(f"{'Zoom':<6}{'Nivel C4':<11}{'Analogia de mapa':<18}Pregunta que responde")
print("-" * 76)
for i, (level, mapa, pregunta, _aud) in enumerate(zoom_ladder, start=1):
    print(f"{i:<6}{level:<11}{mapa:<18}{pregunta}")
print()

print("Regla: cada zoom responde UNA pregunta para UNA audiencia.")
for i, (level, mapa, _pregunta, aud) in enumerate(zoom_ladder, start=1):
    print(f"  Zoom {i} ({level:<9}) -> {aud}")
print()
print("Subir un nivel = alejarse (menos detalle, mas contexto).")
print("Bajar un nivel  = acercarse (mas detalle, menos contexto).")
print("El error no es el diagrama feo: es el zoom equivocado para quien mira.")

Qué esperar. Al correrlo:

Los cuatro niveles del C4, como cuatro zooms de un mismo mapa:

Zoom  Nivel C4   Analogia de mapa  Pregunta que responde
----------------------------------------------------------------------------
1     Context    mapa del mundo    Que hace el sistema y con quien habla?
2     Container  mapa de la ciudad De que piezas desplegables se compone?
3     Component  mapa del barrio   Que hay DENTRO de una pieza?
4     Code       mapa de la calle  Como esta escrito ese componente?

Regla: cada zoom responde UNA pregunta para UNA audiencia.
  Zoom 1 (Context  ) -> cualquiera, incluido el negocio
  Zoom 2 (Container) -> gente tecnica
  Zoom 3 (Component) -> devs de esa pieza
  Zoom 4 (Code     ) -> el dev que lo edita hoy

Subir un nivel = alejarse (menos detalle, mas contexto).
Bajar un nivel  = acercarse (mas detalle, menos contexto).
El error no es el diagrama feo: es el zoom equivocado para quien mira.

La tabla es todo el C4 en cuatro filas. Fíjate en la columna de audiencia: va de "cualquiera" arriba a "el dev que lo edita hoy" abajo. Esa es la propiedad clave del modelo —la audiencia se estrecha a medida que bajas—. El Context lo entiende medio mundo; el Code lo mira una sola persona. Y por eso el trabajo de comunicación del arquitecto se concentra arriba: los diagramas de nivel 1 y 2 los ve mucha gente y valen todo el esfuerzo de hacerlos bien; el nivel 4 lo ve casi nadie y casi nunca vale la pena dibujarlo a mano. La última línea es la moraleja del módulo: el diagrama no fracasa por feo, fracasa por estar en el zoom equivocado para quien mira.

Ahora, la relación entre los cuatro niveles no es una lista suelta: es un anidamiento. Cada nivel vive dentro del anterior, como las muñecas rusas. Así se ve la escalera dibujada:

+-------------------------------------------------------------+
|  NIVEL 1  CONTEXT  (el mapa del mundo)                      |
|  Mercado como UNA caja + sus usuarios + sistemas externos   |
|                                                             |
|    +----------------------------------------------------+   |
|    |  NIVEL 2  CONTAINER  (el mapa de la ciudad)        |   |
|    |  zoom DENTRO de Mercado: web, api, db, search...   |   |
|    |                                                    |   |
|    |    +-------------------------------------------+   |   |
|    |    |  NIVEL 3  COMPONENT  (el mapa del barrio) |   |   |
|    |    |  zoom DENTRO de un container: p.ej. la API|   |   |
|    |    |                                           |   |   |
|    |    |    +---------------------------------+    |   |   |
|    |    |    |  NIVEL 4  CODE (mapa de la calle)|   |   |   |
|    |    |    |  zoom DENTRO de un componente    |   |   |   |
|    |    |    +---------------------------------+    |   |   |
|    |    +-------------------------------------------+   |   |
|    +----------------------------------------------------+   |
+-------------------------------------------------------------+

     Afuera: menos detalle, mas audiencia.
     Adentro: mas detalle, menos audiencia.

Este anidamiento es la razón de que el C4 sea coherente: cada diagrama abre una caja del nivel de arriba. El Container hace zoom en la caja de Mercado del Context. El Component hace zoom en una caja del Container. El Code hace zoom en una caja del Component. Nunca saltas dos niveles de golpe (del Context al Code) porque perderías la ruta —igual que Google Maps no te lleva del planeta al número de la casa en un solo salto—. Y nunca mezclas dos niveles en una lámina, porque cada diagrama es un recuadro de esta muñeca rusa, no dos.

Por qué "una notación, cuatro niveles" gana

Vale la pena entender contra qué está compitiendo el C4, porque ahí está su valor. La alternativa histórica para diagramar software fue UML (Unified Modeling Language), un estándar con decenas de tipos de diagrama y cientos de símbolos: diagramas de clases, de secuencia, de despliegue, de componentes, de estados, con notaciones precisas para herencia, composición, agregación, multiplicidad. UML es potente y riguroso. También es algo que casi nadie recuerda entero: la mayoría de los equipos usa una fracción, mal, y termina con diagramas que solo el que los dibujó sabe leer —o peor, que cada quien lee distinto porque no todos recuerdan qué significa el rombo relleno contra el vacío—.

El C4 hace la apuesta opuesta: casi cero notación, casi todo el valor. Cajas, flechas, etiquetas. Una caja es un elemento; una flecha es "usa" o "habla con", con una etiqueta que dice cómo. No hay que memorizar símbolos. La disciplina no está en la notación sino en el nivel de abstracción: la pregunta importante no es "¿qué símbolo uso?" sino "¿a qué distancia estoy mirando?". Eso lo puede aprender cualquiera en cinco minutos, y —clave para comunicar— lo puede leer cualquiera sin entrenamiento. Un Context de Mercado con cinco cajas y cuatro flechas no necesita leyenda: se entiende solo. Esa legibilidad-sin-entrenamiento es exactamente lo que hace falta cuando tu audiencia incluye a un VP que nunca vio un diagrama de arquitectura en su vida.

Esto no quiere decir que UML esté "mal" ni que no exista lugar para notaciones más ricas —un diagrama de secuencia UML es insuperable para mostrar un protocolo de mensajes paso a paso—. Quiere decir que para la tarea de comunicar la forma de un sistema a audiencias distintas, la simplicidad del C4 es una virtud, no una carencia. El C4 y notaciones como UML no son rivales: el C4 te da el mapa de zooms para orientar, y si en un punto necesitas detallar un protocolo, usas la notación específica dentro del nivel correcto. Pero el esqueleto de tu comunicación —lo que decide qué mostrar a quién— son las cuatro C.

Más allá de las cuatro C: los diagramas de apoyo

Las cuatro C —Context, Container, Component, Code— son el esqueleto del C4, y con ellas cubres casi todo. Pero conviene saber que el modelo ofrece además unos pocos diagramas de apoyo, opcionales, para preguntas que las cuatro C no responden bien. No hace falta memorizarlos; basta conocer que existen para cuando la necesidad aparezca:

  • El System Landscape es un "Context de contextos": en vez de un solo sistema en el centro, muestra varios sistemas de la empresa y cómo se relacionan entre sí. Sirve cuando la pregunta no es "¿cómo es Mercado?" sino "¿cómo encaja Mercado en el mapa de todos los sistemas de la organización?" —una vista de más arriba aún que el Context—.
  • El Dynamic diagram muestra una secuencia: cómo colaboran los elementos para completar un caso concreto, paso numerado a paso ("1. la web llama a la API; 2. la API valida el stock; 3. la API cobra..."). Responde "¿cómo fluye esta operación?", que las cuatro C —estáticas— no capturan.
  • El Deployment diagram muestra dónde se ejecuta cada container en la infraestructura real: qué corre en qué servidor, contenedor o nube. Responde la pregunta de operaciones —"¿dónde vive esto desplegado?"— que el Container lógico no aborda.

La razón de mencionarlos y seguir es la misma disciplina del módulo: no los uses por defecto. La mayoría de los sistemas comunican bien con Context + Container + (a veces) Component, y añadir landscape, dynamic o deployment "para que esté completo" es caer otra vez en el museo. Están ahí para cuando una pregunta específica los pide —una operación compleja que hay que explicar paso a paso, un despliegue que confunde a ops— y no antes. El esqueleto sigue siendo las cuatro C; estos son herramientas de reserva.

Errores comunes

Creer que "Container" significa Docker (de falso amigo). Qué pasa: alguien oye "Container" en el C4 y asume que se refiere a contenedores de Docker o Kubernetes, y entonces su diagrama de Container solo tiene sentido si el sistema usa contenedores. Por qué pasa: la palabra se robó el significado en la industria. Cómo detectarlo: si tu diagrama de nivel 2 se vacía cuando el sistema no usa Docker, entendiste mal el término. Cómo corregirlo: en el C4, un container es cualquier cosa que se ejecuta y se despliega por separado —un proceso, una app de escritorio, una base de datos, una función serverless, un navegador ejecutando tu SPA—. Una base de datos PostgreSQL es un container aunque no haya un solo Docker en el proyecto. El nivel 2 pregunta "¿qué piezas desplegables hay?", no "¿qué contenedores de Docker hay?".

Saltarse niveles o mezclarlos (de impaciencia). Qué pasa: el diagrama pasa del sistema entero (Context) directo a mostrar clases (Code) en la misma lámina, o mezcla containers con componentes internos. Por qué pasa: por prisa o por querer "mostrar todo de una vez". Cómo detectarlo: si en tu diagrama conviven una caja que representa "el sistema completo" y otra que representa "una clase", saltaste de zoom 1 a zoom 4 sin escala intermedia. Cómo corregirlo: respeta el anidamiento —cada diagrama abre una caja del nivel de arriba—; si necesitas mostrar el interior de una pieza, haz un diagrama nuevo de ese nivel, no lo encimes en el anterior. La regla dura de la lección 7: un diagrama, un nivel.

Querer un diagrama de Component (o Code) para cada pieza (de exhaustividad). Qué pasa: el equipo decide "documentar bien" y hace un Component de cada uno de los cinco containers, y luego un Code de cada componente, y termina con treinta diagramas que nadie mantiene. Por qué pasa: se confunde completitud con calidad —"si documentamos todos los niveles de todo, estará bien documentado"—. Cómo detectarlo: si tienes más diagramas de los que alguien revisa o actualiza, estás manteniendo museo, no comunicación. Cómo corregirlo: Context y Container casi siempre; Component solo en los containers complejos que lo ameriten; Code casi nunca a mano. La regla del zoom (lección 4): bajas un nivel solo donde el detalle ayuda a alguien real a trabajar.

Ejercicios

Ejercicio 1 — Ubica el elemento en su nivel. Para cada uno de estos elementos de Mercado, di en qué nivel del C4 aparecería como una caja: (a) "un cliente que compra"; (b) "el índice de búsqueda (Elasticsearch)"; (c) "la clase TaxCalculator"; (d) "el gateway de pagos externo (Stripe)"; (e) "el controlador de pedidos dentro de la API".

Ver solución
  • (a) El cliente que compra → Context (nivel 1). Es una persona que usa el sistema; las personas aparecen en el Context (y suelen repetirse como decorado en el Container). Es un actor del mundo alrededor del sistema.
  • (b) El índice de búsqueda (Elasticsearch) → Container (nivel 2). Es una pieza desplegable por separado, con su tecnología. Un container clásico.
  • (c) La clase TaxCalculator → Code (nivel 4). Es una clase concreta; vive en el nivel más profundo, dentro de un componente.
  • (d) El gateway de pagos externo (Stripe) → Context (nivel 1). Es un sistema externo con el que Mercado habla; los sistemas externos aparecen en el Context (y como decorado en el Container).
  • (e) El controlador de pedidos dentro de la API → Component (nivel 3). Es una agrupación de código con una responsabilidad, dentro de un container (la API). Ese es el nivel 3.

La moraleja: cada elemento tiene un nivel natural. Cuando los mezclas —el cliente, el índice de búsqueda, la clase y el controlador en la misma lámina— produces el diagrama-espagueti, porque estás poniendo el mundo, la ciudad, el barrio y la calle en un solo mapa.

Ejercicio 2 — ¿Subir o bajar? Un dev está mirando el diagrama de Container de Mercado y dice: "necesito entender qué hace exactamente el componente que calcula impuestos dentro de la API". Otro, un gerente, mira el mismo diagrama y dice: "no me queda claro para qué sirve todo esto en el negocio". ¿En qué dirección debe moverse cada uno por la escalera del C4, y a qué nivel llega?

Ver solución

El dev necesita bajar (acercarse, más detalle). Está en el Container (nivel 2) y quiere ver el interior de una pieza —la API—, así que baja al Component (nivel 3), donde aparecen el controlador de pedidos, el calculador de impuestos, el cliente de pagos, etc. Si necesitara ver las clases exactas del cálculo, bajaría un peldaño más al Code (nivel 4), aunque para eso normalmente conviene abrir el código real en vez de un diagrama.

El gerente necesita subir (alejarse, más contexto). Está viendo el Container (piezas técnicas con tecnologías) y esa vista no responde su pregunta de negocio. Sube al Context (nivel 1), donde Mercado es una sola caja rodeada de sus usuarios (clientes, vendedores) y sus dependencias externas (pagos, envíos). Ahí "para qué sirve esto" se contesta solo: conecta compradores y vendedores, cobra y envía. El mismo sistema; cada uno se mueve en la dirección de su pregunta.

Ejercicio 3 — La defensa del C4 contra UML. Un colega experimentado te dice: "el C4 es demasiado simple; con cuatro tipos de cajas no puedes capturar la riqueza de un sistema como sí lo hace UML con sus decenas de diagramas". Sin descalificar UML, argumenta por qué la simplicidad del C4 es una ventaja para la tarea de comunicar, y en qué caso concreto sí conviene bajar a una notación más rica.

Ver solución

La simplicidad del C4 es una ventaja para comunicar precisamente porque la comunicación tiene éxito cuando el receptor entiende sin entrenamiento, y eso exige una notación que cualquiera pueda leer. Un Context de cinco cajas y cuatro flechas lo entiende un VP que nunca vio un diagrama de arquitectura; un diagrama UML con rombos, multiplicidades y estereotipos exige que el lector conozca la notación, y la mayoría no la conoce (o la recuerda mal). Para el objetivo de "que esta persona entienda la forma del sistema", menos notación significa más audiencia alcanzada. La "riqueza" que UML captura es, muchas veces, precisión que la audiencia no necesita y que le tapa la idea principal —como poner los números de las casas en el mapa del país—.

Dicho eso, el C4 no reemplaza toda notación: reemplaza el esqueleto de la comunicación (qué zoom, para quién). Cuando ya estás en el nivel correcto y necesitas mostrar algo que las cajas-y-flechas no capturan bien —por ejemplo, la secuencia exacta de mensajes de un protocolo de checkout, quién llama a quién y en qué orden, con esperas y respuestas—, ahí un diagrama de secuencia UML es superior y conviene usarlo dentro del nivel apropiado. La regla: el C4 orienta y comunica la estructura; una notación específica detalla un aspecto puntual cuando la estructura ya está clara. No compiten; se complementan.

Resumen y siguiente paso

En esta lección conociste el C4 model: cuatro niveles de zoom —Context (el mundo), Container (la ciudad), Component (el barrio), Code (la calle)—, cada uno con su pregunta y su audiencia, anidados como muñecas rusas donde cada diagrama abre una caja del nivel de arriba. Viste, ejecutado, la escalera completa y su propiedad clave: la audiencia se estrecha a medida que bajas, por eso el trabajo de comunicación del arquitecto se concentra en los niveles 1 y 2. Y entendiste por qué "una notación simple con cuatro niveles" le gana a la sopa de símbolos para la tarea de comunicar: porque la comunicación exige legibilidad-sin-entrenamiento, y el C4 la da.

Antes de avanzar deberías poder: nombrar las cuatro C y decir qué pregunta responde cada una; explicar el anidamiento (cada nivel abre una caja del anterior) y por qué no saltas ni mezclas niveles; y corregir el falso amigo (un "container" no es un contenedor de Docker sino cualquier pieza desplegable).

Lo que sigue es dejar la teoría y dibujar. En la lección 3 vas a construir los dos mapas que usarás el 80% del tiempo: el Context de Mercado para el VP (qué hace el sistema, con quién habla, cinco cajas sin jerga) y el Container de Mercado para el dev (las piezas desplegables con sus tecnologías, nueve cajas). El mismo sistema, dos zooms, dos audiencias —y vas a ver, ejecutado, cuánto detalle carga cada uno—. Es el paso de "sé que hay cuatro niveles" a "sé dibujar los dos que más importan".

Recursos

← Anterior1. Presentación del módulo: comunicar para que entiendan, no para archivarSiguiente →3. Context y Container: los dos mapas que casi siempre necesitas