5. Produce el C4 y el ADR

Descripción

Este es el paso 4 del entregable, y es donde la decisión se vuelve comunicable. En la lección 4 decidiste la estructura —crear el equipo seller_platform, exponer una Seller API, volver la plataforma un servicio, con dos costuras por contrato—. Pero una decisión que solo vive en la cabeza del arquitecto no construye nada: hay que comunicarla, y a dos audiencias muy distintas —el VP que aprueba el presupuesto y el dev que va a construir—. Al terminar esta lección vas a tener dos artefactos del dossier: el C4 del cambio (el diagrama que muestra el qué al nivel correcto para cada audiencia) y el ADR-021 completo (el registro que empaqueta el por qué para quien llegue después). El diagrama y el ADR son las dos mitades de comunicar una arquitectura: el diagrama es la foto, el ADR es la historia de por qué la foto se ve así.

Esto importa porque en un cambio grande la comunicación decide si la decisión sobrevive al tiempo y a las personas. El C4 evita las dos audiencias mal atendidas: el VP ahogado en un diagrama técnico que no entiende, y el dev perdido en un diagrama de negocio que no le dice dónde vive cada cosa. Y el ADR resuelve el problema más caro de todos —el conocimiento que se pierde cuando quien decidió se va—: dentro de dos años, el dev que herede el surface de vendedores y piense "esto sería más simple sin el gateway" abrirá el ADR-021 y encontrará por qué existe el gateway, qué se sacrificó a conciencia (la latencia extra, las dos costuras), y así no deshará una decisión buena por ignorancia. En el capstone, además, el ADR es la pieza que conecta todos los pasos anteriores: su contexto cita el atributo rector (paso 2), su decisión describe la estructura (paso 3), y sus consecuencias nombran las costuras irreducibles y el trade-off que gobierna el cambio —el ADR es donde el hilo se hace texto—.

Conexión con el módulo: esta lección hace el paso 4 del hilo y aporta la pieza de M3 al capstone. Recibe su entrada del paso 3 (la decisión estructural que hay que comunicar) y del paso 2 (el atributo rector, que el ADR cita como justificación). Su salida —el C4 y el ADR— alimenta el paso 5 (el rollout): el diagrama y el ADR son las herramientas con las que el arquitecto influye en las squads para que adopten el contrato del cambio, y son parte de la documentación que el paso 6 versionará. La frontera con la guía hermana se mantiene firme, igual que en el módulo 3: la mecánica del ADR (su estructura, cuándo escribirlo, cómo se supersede) se enseñó en architecture-decisions-and-tradeoffs; aquí el ADR se usa como pieza de comunicación, no se re-explica su mecánica. La novedad no es el formato del ADR, es su papel: cómo un ADR bien escrito le habla a un lector futuro.

Dos mapas y una nota del dueño anterior

Piensa en una ciudad que visitas por primera vez. Tomas dos mapas del mismo lugar. Uno es el mapa turístico: la ciudad como una mancha con sus puntos de interés y cómo se relacionan a grandes rasgos —con eso entiendes qué es la ciudad sin ahogarte en detalle—. El otro es el mapa del metro: las líneas, las estaciones, los transbordos —las piezas por las que de verdad te mueves—. Nadie confunde uno con otro: el turístico sería inútil para saber en qué estación cambiar de línea, y el del metro sería abrumador para alguien que solo quiere saber qué tiene la ciudad de interesante. El Context del C4 es el mapa turístico (para el VP); el Container es el mapa del metro (para el dev). Misma ciudad —Mercado tras el cambio—, dos mapas, dos audiencias.

Pero hay algo que ningún mapa te dice: por qué la ciudad está construida así. Para eso imagina que te mudas a una casa vieja y encuentras, pegada dentro de la caja de fusibles, una nota del dueño anterior: "la puerta del garaje la tapié porque daba a un terreno que se inunda; la tubería da la vuelta porque debajo hay una viga que no se puede perforar". De golpe, lo que parecía incompetencia resulta ser decisiones informadas ante restricciones que no veías. Eso es un ADR. El diagrama muestra que el surface de vendedores está detrás de un gateway; no dice por qué. El ADR es la nota que el arquitecto de hoy le pega a la caja de fusibles para el dev de dentro de dos años, para que no destape el garaje y se inunde. El diagrama es el mapa; el ADR es la nota. En el paso 4 produces los dos.

Ejemplo trabajado: el C4 del cambio

Empecemos por el diagrama, en dos niveles. El Context responde: ¿qué hace Mercado tras el cambio, quién lo usa y de qué depende? La novedad del cambio salta a la vista —un vendedor externo que ahora integra por API, con su propio sistema (el Seller Backend)—.

C4Context
    title Mercado tras el cambio - System Context (nivel 1, el mapa del VP)
    Person(customer, "Customer", "Busca y compra productos")
    Person(seller, "Seller (externo)", "Publica y vende por la Seller API")

    System(mercado, "Mercado", "Marketplace: ahora abierto a vendedores externos por API")

    System_Ext(sellerbe, "Seller Backend", "El ERP/e-commerce del tercero que integra")
    System_Ext(payments, "Payment Gateway", "Procesa pagos y payouts")
    System_Ext(carrier, "Carrier API", "Genera guias y rastrea envios")

    Rel(customer, mercado, "Busca, compra, rastrea pedidos")
    Rel(seller, mercado, "Publica productos, gestiona inventario")
    Rel(sellerbe, mercado, "Sincroniza catalogo y recibe payouts", "HTTPS/API")
    Rel(mercado, payments, "Cobra y paga a vendedores", "HTTPS/API")
    Rel(mercado, carrier, "Solicita envios", "HTTPS/API")

Léelo como lo leería el VP: los clientes compran; los vendedores externos publican por la API; el sistema del vendedor (su ERP) se sincroniza con Mercado; y Mercado cobra y paga por un gateway y envía por un carrier. Seis cajas, cero jerga, y la historia del cambio en treinta segundos —el VP ve que ahora hay un actor nuevo (el tercero) que integra por API, que es exactamente lo que aprobó—. No aparece el gateway interno, ni PostgreSQL, ni el servicio seller_platform, y está bien: el VP no vino a eso.

Ahora el Container: hacemos zoom dentro de Mercado. Responde: ¿de qué piezas desplegables se compone y cómo se comunican? Aquí aparece lo que el cambio agregó por dentro —el gateway de la Seller API y el servicio seller_platform—.

C4Container
    title Mercado tras el cambio - Containers (nivel 2, el mapa del dev)
    Person(customer, "Customer", "Compra")
    Person(seller, "Seller (externo)", "Vende por API")

    System_Boundary(mercado, "Mercado") {
        Container(web, "Web App", "React", "Storefront en el navegador")
        Container(mobile, "Mobile App", "React Native", "App de compra")
        Container(storefront, "Storefront API", "FastAPI", "Catalogo, pedidos, checkout")
        Container(gateway, "Seller API Gateway", "API Gateway", "Auth de terceros, rate limiting, cuotas")
        Container(sellerplat, "seller_platform", "Service", "Onboarding, ingesta de listings, payouts")
        ContainerDb(db, "Database", "PostgreSQL", "Productos, pedidos, usuarios")
        Container(search, "Search Index", "Elasticsearch", "Busqueda de catalogo")
    }

    System_Ext(sellerbe, "Seller Backend", "ERP del tercero")
    System_Ext(payments, "Payment Gateway", "Stripe")
    System_Ext(carrier, "Carrier API", "Envia")

    Rel(customer, web, "Usa", "HTTPS")
    Rel(seller, sellerbe, "Opera su tienda")
    Rel(sellerbe, gateway, "Integra", "JSON/HTTPS")
    Rel(gateway, sellerplat, "Enruta peticiones autenticadas", "JSON/HTTPS")
    Rel(sellerplat, storefront, "Publica listings via contrato", "JSON/HTTPS")
    Rel(sellerplat, payments, "Ordena payouts", "HTTPS/API")
    Rel(web, storefront, "Llama", "JSON/HTTPS")
    Rel(storefront, db, "Lee y escribe", "SQL")
    Rel(storefront, search, "Consulta e indexa", "HTTPS")
    Rel(storefront, payments, "Cobra", "HTTPS/API")

Léelo como lo leería el dev nuevo: el sistema del vendedor externo integra contra un Seller API Gateway (que hace auth de terceros, rate limiting y cuotas —el control de la puerta—), que enruta al servicio seller_platform (onboarding, ingesta de listings, payouts); seller_platform publica los listings en el catálogo por contrato a través de la Storefront API, y ordena los payouts al gateway de pagos externo. El resto del sistema —web, móvil, la Storefront API, PostgreSQL, Elasticsearch— sigue como estaba. En un minuto, el dev sabe qué piezas agregó el cambio, con qué tecnología, y cómo fluye una petición de un vendedor externo desde su ERP hasta el catálogo. Fíjate que las dos costuras genuinas de la lección 4 aparecen aquí como flechas explícitas: sellerplat → storefront (publicar listings) y sellerplat → payments (payouts). El diagrama las hace visibles como contratos, no como acoplamientos.

Cuánto detalle carga cada zoom, medido

Los dos mapas son del mismo sistema pero cargan cantidades distintas de detalle. Contémoslo, porque "menos detalle" no es "menos honesto": es el detalle correcto para la pregunta de cada audiencia. Este mismo bloque genera además el ADR —el porqué— a partir de datos estructurados.

# Capstone paso 4: comunicar la decision. El C4 (en mermaid, aparte) muestra el QUE;
# el ADR muestra el POR QUE, empaquetado para viajar en el tiempo. Aqui GENERAMOS el
# ADR de la decision insignia del cambio a partir de datos estructurados, y contamos
# cuanto detalle carga cada nivel del C4 para cada audiencia.

adr = {
    "id": "ADR-021",
    "title": "Exponer a los vendedores externos con una Seller API dedicada y un equipo seller_platform",
    "status": "Accepted",
    "date": "2026-07-20",
    "deciders": ["arquitecto", "VP de producto", "leads de catalog / payments / platform"],
    "context": (
        "Abrimos Mercado a vendedores externos por API y esperamos crecer 10x. El "
        "atributo que mas pesa es scalability (score 38), seguido de security (30) "
        "porque entran terceros. Hoy el surface de vendedores no tiene duenio: catalog, "
        "orders y payments le crecerian un apendice co-poseido cada uno (friccion medida "
        "de 21 pares de coordinacion). Es una decision arquitectonicamente significativa: "
        "moldea la estructura, es cara de revertir y es de alto riesgo (expone a terceros)."
    ),
    "decision": (
        "Crear una Seller API publica detras de un API gateway (auth de terceros, rate "
        "limiting, cuotas), y un equipo stream-aligned 'seller_platform' que posee el "
        "surface completo (seller_api, seller_onboarding, listing_ingestion, "
        "payout_processing). catalog, payments, notifications y auth se consumen como "
        "servicios de plataforma por contrato estable."
    ),
    "consequences_pos": [
        "Un solo equipo posee el surface: escala y evoluciona sin coordinar con cuatro squads (sirve a grow_10x).",
        "El contrato publico aisla a los terceros del modelo interno: mas seguro y mas facil de cambiar por dentro.",
        "La friccion de coordinacion del sistema baja de 21 a 7 pares (-67%).",
    ],
    "consequences_neg": [
        "Un equipo nuevo que contratar y montar: la mejora es el destino, no el primer dia.",
        "El gateway agrega un salto en el camino critico: hay que cuidar latencia y fallos (choca con instant_checkout).",
        "Quedan dos costuras genuinas (importar listings al catalogo; pagar a los vendedores via payments) que exigen contratos estables.",
    ],
}


def render_adr(a):
    out = []
    out.append(f"# {a['id']}: {a['title']}")
    out.append("")
    out.append(f"**Status:** {a['status']}  |  **Fecha:** {a['date']}  |  "
               f"**Deciden:** {', '.join(a['deciders'])}")
    out.append("")
    out.append("## Contexto")
    out.append(a["context"])
    out.append("")
    out.append("## Decision")
    out.append(a["decision"])
    out.append("")
    out.append("## Consecuencias")
    out.append("A favor:")
    for c in a["consequences_pos"]:
        out.append(f"- {c}")
    out.append("En contra (el precio que aceptamos):")
    for c in a["consequences_neg"]:
        out.append(f"- {c}")
    return "\n".join(out)


print(render_adr(adr))
print()
print("-" * 70)

# Cuanto detalle carga cada nivel del C4 para cada audiencia del cambio.
context_elements = [
    ("person", "Customer"), ("person", "Seller (externo)"),
    ("software_system", "Mercado"),
    ("external_system", "Seller Backend"), ("external_system", "Payment Gateway"),
    ("external_system", "Carrier API"),
]
container_elements = [
    ("person", "Customer"), ("person", "Seller (externo)"),
    ("container", "Web App"), ("container", "Mobile App"), ("container", "Storefront API"),
    ("container", "Seller API Gateway"), ("container", "seller_platform Services"),
    ("container_db", "Database"), ("container", "Search Index"),
    ("external_system", "Seller Backend"), ("external_system", "Payment Gateway"),
    ("external_system", "Carrier API"),
]


def summarize(name, elements):
    kinds = {}
    for kind, _ in elements:
        kinds[kind] = kinds.get(kind, 0) + 1
    detalle = ", ".join(f"{v} {k}" for k, v in kinds.items())
    print(f"{name:<11} {len(elements):>2} elementos  ({detalle})")


print("El MISMO sistema tras el cambio, dos zooms:")
summarize("Context", context_elements)
summarize("Container", container_elements)
print()
print("El VP lee el Context: ve que ahora hay un Seller externo que integra por API.")
print("El dev lee el Container: ve el gateway nuevo y el servicio seller_platform.")
print("El ADR les dice, a los dos, POR QUE existe ese gateway. El diagrama no lo dice.")

Qué esperar. Al correrlo:

# ADR-021: Exponer a los vendedores externos con una Seller API dedicada y un equipo seller_platform

**Status:** Accepted  |  **Fecha:** 2026-07-20  |  **Deciden:** arquitecto, VP de producto, leads de catalog / payments / platform

## Contexto
Abrimos Mercado a vendedores externos por API y esperamos crecer 10x. El atributo que mas pesa es scalability (score 38), seguido de security (30) porque entran terceros. Hoy el surface de vendedores no tiene duenio: catalog, orders y payments le crecerian un apendice co-poseido cada uno (friccion medida de 21 pares de coordinacion). Es una decision arquitectonicamente significativa: moldea la estructura, es cara de revertir y es de alto riesgo (expone a terceros).

## Decision
Crear una Seller API publica detras de un API gateway (auth de terceros, rate limiting, cuotas), y un equipo stream-aligned 'seller_platform' que posee el surface completo (seller_api, seller_onboarding, listing_ingestion, payout_processing). catalog, payments, notifications y auth se consumen como servicios de plataforma por contrato estable.

## Consecuencias
A favor:
- Un solo equipo posee el surface: escala y evoluciona sin coordinar con cuatro squads (sirve a grow_10x).
- El contrato publico aisla a los terceros del modelo interno: mas seguro y mas facil de cambiar por dentro.
- La friccion de coordinacion del sistema baja de 21 a 7 pares (-67%).
En contra (el precio que aceptamos):
- Un equipo nuevo que contratar y montar: la mejora es el destino, no el primer dia.
- El gateway agrega un salto en el camino critico: hay que cuidar latencia y fallos (choca con instant_checkout).
- Quedan dos costuras genuinas (importar listings al catalogo; pagar a los vendedores via payments) que exigen contratos estables.

----------------------------------------------------------------------
El MISMO sistema tras el cambio, dos zooms:
Context      6 elementos  (2 person, 1 software_system, 3 external_system)
Container   12 elementos  (2 person, 6 container, 1 container_db, 3 external_system)

El VP lee el Context: ve que ahora hay un Seller externo que integra por API.
El dev lee el Container: ve el gateway nuevo y el servicio seller_platform.
El ADR les dice, a los dos, POR QUE existe ese gateway. El diagrama no lo dice.

Primero el conteo, que confirma la disciplina del C4. El Context carga 6 elementos y el Container 12 —el doble—: el zoom del nivel 1 al 2 abre la única caja "Mercado" en sus piezas desplegables sin tocar el mundo que la rodea (las 2 personas y los 3 sistemas externos se conservan idénticos). El VP ve 6 cajas y entiende el cambio; el dev ve 12 y sabe dónde vive cada cosa. Ninguno de los dos ve el código —el nivel 4—, porque ninguno lo necesita todavía. La lección del conteo: comunicar bien no es mostrar todo, es mostrar el detalle correcto para la pregunta de cada quien.

Ahora el ADR, que es donde el hilo del capstone se hace texto. Léelo con los ojos del dev del futuro que hereda el surface y piensa "¿por qué este gateway extra?, sería más simple sin él". El Contexto le hace sentir la tensión y —clave— cita el paso 2 y el paso 3: dice que scalability (38) es el atributo rector y security (30) el segundo (por qué importan), y que sin dueño el surface tendría 21 pares de fricción (por qué se creó el equipo). El dev entiende que la decisión no fue un capricho: fue la respuesta al atributo que el negocio priorizó. La Decisión describe exactamente la estructura de la lección 4. Y las Consecuencias son la parte más honesta y más útil: no solo listan los beneficios (un equipo dueño, el contrato que aísla, la fricción 21→7), sino el precio consciente —el equipo nuevo que hay que montar, la latencia extra del gateway que choca con instant_checkout, y las dos costuras irreducibles—. Cuando el dev del futuro note esa latencia, el ADR le dirá "sí, lo sabíamos, fue el precio de la separación", y no perderá una semana investigando un "problema" que fue una decisión. El diagrama le mostró la foto; el ADR le contó la historia —incluido lo que dolió—.

Fíjate en un detalle que la lección 7 va a explotar: como el ADR salió de datos estructurados y cabe en una pantalla, es un archivo de texto chico que puede vivir en el repositorio, versionado junto al código, cambiando cuando la decisión cambie. Igual que el C4 en mermaid, que es texto y no una imagen que se pudre. Esa propiedad —diagramas y decisiones como texto versionable— es la base de la documentación que sobrevive del paso 6.

Profundización: por qué el diagrama y el ADR son inseparables en el capstone

Conviene fijar la división de trabajo entre las dos piezas, porque juntas es como comunican de verdad una arquitectura —y en el capstone esa unión es especialmente importante—.

	Comunica el...	Envejece...	Responde a...
Diagrama (C4)	qué — la forma del sistema tras el cambio	cuando la estructura cambia	quien necesita orientarse en el sistema actual
ADR	por qué — el razonamiento detrás	casi nunca (la decisión y su contexto son históricos)	quien necesita entender por qué el sistema es así

Hay una asimetría útil. El diagrama describe el presente, así que envejece cada vez que el sistema cambia —hay que mantenerlo—. El ADR describe un momento histórico —"en julio de 2026, dadas estas condiciones, decidimos esto"—, y ese momento no cambia nunca: aunque la decisión luego se revierta, el registro de que se tomó, por qué y qué se sabía sigue siendo verdad para siempre. Por eso un ADR no se "actualiza": se supersede (se escribe uno nuevo que dice "reemplaza al ADR-021") y el viejo se conserva como historia. Esa permanencia es lo que le permite viajar en el tiempo.

En el capstone, esta unión es más que una buena práctica: es el mecanismo que mantiene el hilo cohesionado a través del tiempo. El diagrama comunica la decisión estructural del paso 3; el ADR ancla esa decisión a los pasos 2 (el atributo rector que la justifica) y a las consecuencias que los pasos 6 y 8 van a gestionar (las costuras, el trade-off scalability-vs-cost). Un arquitecto que entregara solo el diagrama dejaría el porqué en su cabeza —y cuando se fuera, el surface de vendedores quedaría como una foto sin historia, lista para que alguien la deshiciera por no entenderla—. Un arquitecto que entregara solo el ADR dejaría el razonamiento sin la foto que lo aterriza. El paquete de comunicación completo de una decisión importante es el diagrama que muestra la nueva forma más el ADR que explica por qué —y eso es exactamente lo que entregas en este paso, y lo que ensamblarás en el dossier de la lección 8—.

Un punto de frontera, para no invadir la guía hermana. La mecánica del ADR —cómo se estructura, cuándo se escribe, cómo se numera, cómo se supersede, cómo se decide cuál opción elegir con una matriz— es de architecture-decisions-and-tradeoffs. Aquí no elegimos entre opciones (¿gateway sí o no?, ¿un servicio o varios?); esa decisión ya se tomó en el paso 3, derivada del atributo rector. Aquí solo comunicamos la decisión ya tomada, escribiendo el ADR pensando en el lector que no estuvo en la sala. La habilidad de este paso no es decidir; es comunicar una decisión para que sobreviva.

Errores comunes

Meter tecnología en el Context o clases en el Container (de fuga de nivel). Qué pasa: el Context del cambio termina con "Seller API Gateway (Kong)" o "PostgreSQL", perdiendo al VP; o el Container muestra "SellerOnboardingController" y "PayoutService" —clases internas del servicio, no piezas desplegables—. Por qué pasa: para el arquitecto la tecnología es la parte interesante y cuesta resistir mencionarla. Cómo detectarlo: enseña el Context a alguien no técnico; si pregunta "¿qué es un gateway?", metiste nivel 2 en el nivel 1. En el Container, pregunta de cada caja "¿esto se despliega por separado?"; si no, es un componente disfrazado. Cómo corregirlo: en el Context, lenguaje de negocio ("Mercado abierto a vendedores por API"); en el Container, solo piezas desplegables (el gateway, el servicio seller_platform, la base); las clases internas son el nivel 3, que casi nunca vale la pena dibujar.

Escribir el ADR "para el archivo", sin la tensión ni el precio (de trámite). Qué pasa: el ADR del cambio dice seco "Decidimos exponer una Seller API con un equipo dedicado. Consecuencias: mejor separación", sin el contexto que cita el atributo rector ni el precio consciente. El dev futuro no aprende por qué, y deshace la decisión por ignorancia. Por qué pasa: se trata el ADR como un requisito de cumplimiento, no como una carta a un lector futuro. Cómo detectarlo: si tu ADR se resume en "decidimos X" sin un "porque scalability pesaba 38 y sin dueño había 21 de fricción, y aceptando estas costuras", es archivo, no comunicación. Cómo corregirlo: llena el Contexto con la tensión real (el atributo rector, la fricción medida) y las Consecuencias con el precio (la latencia, las costuras) —justo lo que el lector futuro necesita para no reabrir un debate cerrado—.

Entregar el diagrama sin el ADR (de foto sin historia). Qué pasa: el arquitecto entrega un C4 impecable y se va, dejando el porqué en su cabeza. Meses después, un dev mira el gateway y piensa "esto es complejidad innecesaria, lo quito" —sin saber que el gateway existe por la seguridad de terceros (security 30) y para aislar el modelo interno—. Por qué pasa: el diagrama es tangible y "se ve terminado", así que parece suficiente. Cómo detectarlo: si tu entregable tiene la foto (el C4) pero no la historia (el ADR), comunicaste la mitad. Cómo corregirlo: nunca entregues una decisión estructural importante solo con el diagrama; el par diagrama+ADR es lo mínimo, porque el diagrama envejece y el ADR es lo que evita que alguien deshaga la decisión cuando quien la tomó ya no está para explicarla.

Ejercicios

Ejercicio 1 — ¿Qué mapa le doy a cada quien? Para cada situación del cambio, di si necesitas el Context o el Container, y por qué: (a) el VP quiere una lámina para presentarle el cambio al board de inversionistas; (b) un dev del equipo de un vendedor externo pregunta "¿contra qué integro y cómo?"; (c) el lead de payments quiere entender qué parte del sistema tocará el flujo de payouts antes de comprometer a su squad.

Ver solución

• (a) El VP ante el board → Context. El board trae la pregunta del mundo: ¿qué es este cambio, quién lo usa, qué habilita? Seis cajas sin jerga cuentan la historia (ahora entran vendedores externos que integran por API) y caben en una diapositiva. Un Container lo perdería en gateways y servicios que el board no evalúa.

• (b) El dev del vendedor externo → Container (y el contrato de la Seller API). Necesita saber contra qué pieza integra y cómo: el Container le muestra el Seller API Gateway como el punto de entrada, con su protocolo (JSON/HTTPS) y que detrás está seller_platform. El Context sería muy poco (no vería el gateway); lo que de verdad va a usar es el contrato de la Seller API, que es el detalle del gateway. Aquí el Container es el nivel correcto para orientarlo, y el contrato el documento que sigue.

• (c) El lead de payments → Container acotado. Su pregunta es específica: "qué toca el flujo de payouts". El Container se lo muestra: seller_platform ordena payouts al Payment Gateway externo, y ahí está la costura payout ↔ payments. Ve exactamente qué contrato tendrá que exponer su squad. El Context sería demasiado abstracto para una pregunta tan concreta sobre una pieza.

El patrón: preguntas de qué es / quién lo usa → Context; preguntas de contra qué pieza y cómo / qué parte toca esto → Container. Muestra el nivel mínimo que responde la pregunta y ni uno más —la disciplina del C4—.

Ejercicio 2 — Rescata un ADR de trámite. Un miembro del equipo escribió este "ADR" del cambio, completo: "Decisión: Creamos la Seller API con un equipo nuevo. Consecuencias: Mejor organización." Un dev del futuro no aprende nada útil. Reescríbelo para que comunique, citando lo que el hilo del capstone ya produjo. ¿Qué le faltaba?

Ver solución

Le faltaban las dos cosas que hacen que un ADR comunique: la tensión en el contexto (que en el capstone son los pasos 2 y 3) y el precio en las consecuencias. Tal como está, no dice por qué un equipo nuevo y no repartir el surface, ni qué se sacrificó. Una versión que comunica:

ADR-021: Seller API dedicada con un equipo seller_platform Status: Accepted — 2026-07 Contexto: Abrimos a vendedores externos y esperamos crecer 10x. El atributo rector es scalability (score 38, derivado de las metas), y security es segundo (30) porque entran terceros. Si el surface de vendedores se reparte por proximidad entre catalog, orders, payments y platform, mide 21 pares de fricción de coordinación y no puede escalar (cada cambio arrastra a varios squads). Es una decisión arquitectónicamente significativa: moldea la estructura, es cara de revertir con terceros ya integrados, y es de alto riesgo. Decisión: Una Seller API pública detrás de un gateway (auth de terceros, rate limiting), y un equipo stream-aligned seller_platform dueño del surface completo. catalog, payments, auth y notifications se consumen como servicios por contrato estable. Consecuencias:

• A favor: un equipo dueño que escala sin coordinar (fricción 21→7, −67%); el contrato público aísla a los terceros del modelo interno.
• El precio: hay que montar un equipo nuevo (la mejora es el destino, no el día uno); el gateway agrega un salto que choca con instant_checkout; quedan dos costuras genuinas (import listings ↔ catalog, payouts ↔ payments) que exigen contratos.

Ahora el dev futuro entiende por qué el equipo nuevo (scalability lo exigía y sin dueño había 21 de fricción), por qué el gateway (security de terceros), y qué costó (latencia, dos costuras). Lo que rescató el ADR es el hilo: citó el atributo rector del paso 2 y la fricción medida del paso 3, que es lo que convierte una decisión que "parece complejidad" en una respuesta obvia a lo que el negocio priorizó. Un ADR del capstone que no cite los pasos anteriores desperdicia la ventaja de haberlos hecho.

Ejercicio 3 — La decisión que se revierte. Un año después, Mercado descubre que la latencia del gateway está frenando el checkout de los vendedores más grandes, y decide revertir parte de la decisión: darles a esos vendedores una integración directa sin gateway. Un dev propone "borremos el ADR-021, ya no aplica". ¿Es correcto? ¿Qué se hace, y por qué importa para el capstone?

Ver solución

No se debe borrar. Borrar el ADR-021 destruye la historia de por qué se tomó y por qué se ajustó. Si lo borras, dentro de un año alguien podría proponer de nuevo meter todos los vendedores detrás del gateway —sin saber que ya se hizo, que la latencia frenó a los grandes, y que por eso se les dio integración directa—. Repetiría el dolor. El conocimiento más caro (qué probamos y por qué no funcionó para cierto caso) se perdería.

Lo correcto, según la mecánica de la guía hermana: marcar el ADR-021 como parcialmente superseded y escribir un ADR nuevo —digamos ADR-034, "Integración directa para vendedores de alto volumen"— que explique el nuevo contexto (la latencia del gateway frenaba a los grandes), la nueva decisión (un camino directo para ese segmento) y su relación con el viejo ("ajusta el ADR-021 para vendedores de alto volumen"). El 021 se conserva, ahora con un status que apunta al 034.

Por qué importa para el capstone: el ADR-021 no solo registraba una decisión —registraba el precio que se aceptó a conciencia, incluida "el gateway agrega un salto que choca con instant_checkout"—. Cuando la latencia se volvió un problema real, ese precio ya estaba documentado: el equipo no se sorprendió, porque el ADR lo había advertido. La cadena ADR-021 → ADR-034 le cuenta al futuro la historia completa —se puso el gateway por scalability y security, se ajustó para los grandes por performance—, que es infinitamente más útil que cualquiera de las dos decisiones sola. Y confirma la lección del paso 4: escribir el precio consciente en las consecuencias no es pesimismo, es el regalo más valioso para el futuro —convierte una revisión dolorosa en una evolución informada, que es justo lo que el paso 6 (planear la evolución) va a hacer explícito—. La historia no se edita ni se borra: se le añade.

Resumen y siguiente paso

En esta lección hiciste el paso 4 del entregable: comunicar la decisión con el C4 y el ADR. Con los dos mapas de la ciudad (el turístico para el VP, el del metro para el dev) y la nota del dueño anterior (el ADR), entendiste que el diagrama comunica el qué y el ADR el por qué, y que una arquitectura solo se comunica de verdad con los dos. Dibujaste el Context del cambio (6 elementos, con el vendedor externo que integra por API) y el Container (12 elementos, con el gateway y seller_platform), y mediste que bajar del zoom 1 al 2 es abrir la caja de Mercado sin tocar el mundo que la rodea. Y generaste, ejecutado, el ADR-021 como pieza de comunicación —con la tensión en el contexto (que cita el atributo rector del paso 2 y la fricción del paso 3), el precio en las consecuencias (la latencia, las dos costuras), y el status que dice si aún aplica—. Entendiste que en el capstone el ADR es donde el hilo se hace texto: ancla la decisión estructural a los pasos anteriores y a las consecuencias que los pasos siguientes gestionarán.

Antes de avanzar deberías poder: dibujar un Context legible para el negocio y un Container legible para devs de un cambio; escribir un ADR que comunique (tensión que cita el porqué, precio consciente, status) y no solo archive; decidir qué nivel del C4 le corresponde a cada audiencia; y manejar una decisión revertida sin borrar la historia.

Lo que sigue es el paso 5, donde la comunicación se pone al servicio de la acción. Ya tienes el diagrama y el ADR que explican la decisión; la lección 6 te enseña a usarlos para liderar el rollout sin autoridad. Porque comunicar bien no basta: las squads que ahora deben adoptar los contratos del cambio (el de la Seller API, los de plataforma-como-servicio) no le reportan al arquitecto, y una decisión bien comunicada no se implementa sola. Vas a medir, ejecutado, la adopción genuina que consigue influir con guardrails (sembrar en el early adopter, dar el contract-test que la hace barata, buscar el consenso) contra el reflejo del mandato —y a ver por qué el arquitecto que ordena consigue papeleo y se vuelve el cuello de botella que el paso 1 juró evitar—.

Recursos

• Simon Brown — The C4 model (c4model.com) — la definición canónica de los cuatro niveles; contrasta el Context y el Container que dibujaste con las definiciones de nivel 1 y 2 (y la aclaración de que "container" no es Docker).
• Michael Nygard — "Documenting Architecture Decisions" (2011) — el artículo que popularizó el ADR y su estructura Context/Decision/Consequences/Status. Aquí lo usamos como comunicación; este es el origen de la herramienta.
• Joel Parker Henderson — ADR templates y ejemplos — una colección de plantillas y ADRs reales; útil para ver cómo distintos equipos escriben el porqué para el futuro, que es la habilidad de este paso.
• arc42 — decisiones de arquitectura (sección 9) y building block view (sección 5) — cómo arc42 integra el C4 (bloques) y los ADRs (decisiones) dentro de una documentación mayor; muestra el par diagrama+ADR como parte de un paquete de comunicación completo, que es lo que el paso 6 versionará.