arc42 vs modelo C4: diferencias y cómo combinarlos

Alguien de tu equipo propone arc42 para la documentación de arquitectura. Otra persona dice que el equipo ya usa C4. La discusión que sigue suele dar por hecho que hay que elegir uno, y esa es la primera suposición que conviene descartar.

Comparar arc42 con C4 es un poco como comparar el índice de un informe con los gráficos que van dentro. arc42 es una plantilla: doce secciones que te dicen qué documentar de una arquitectura, desde los objetivos de calidad hasta los riesgos. C4 es un modelo y una notación: cuatro niveles de diagramas que te dicen cómo dibujar la estructura de un sistema de software. Se solapan en algunos puntos y se combinan bien. Esta guía explica qué cubre cada uno, qué pide arc42 que C4 no dibuja, qué aporta C4 a arc42 y una correspondencia sección por sección de qué diagrama C4 va en cada sitio.

La respuesta en una línea

arc42 es una plantilla para documentar arquitectura. El modelo C4 es una forma de dibujar diagramas de arquitectura de software. La mayoría de los equipos que usan ambos colocan diagramas C4 dentro de las secciones de arc42.

La propia FAQ de arc42 describe así la relación. Ante la pregunta «What about arc42 and C4?», responde que el modelo C4 «tiene muchas similitudes con algunas secciones de arc42, pero omite ciertas partes (por ejemplo, requisitos de calidad, conceptos transversales, riesgos y algunas otras)» (arc42 FAQ, B-17). La misma FAQ incluye el modelo C4 de Simon Brown entre las alternativas a arc42 (A-6), lo cual es cierto si solo necesitas diagramas, y engañoso si necesitas todo lo demás que contiene un documento.

Las doce secciones de arc42

Antes de hacer ninguna correspondencia, ayuda tener delante las secciones con sus números exactos. Proceden de la documentación de arc42, plantilla versión 9.0 (julio de 2025, según la página de descarga):

Hay algo más sobre lo que arc42 es explícito: no se rellena todo. Su FAQ responde a «¿qué partes son esenciales?» con «Por favor, no lo rellenes todo. Documenta solo lo que necesitan tus stakeholders», porque todo lo que escribas «podrá requerir esfuerzo de mantenimiento en el futuro» (B-1). Ese consejo importa para la combinación de más abajo. Un documento arc42 ligero con buenos diagramas C4 en tres secciones es mejor que uno completo que nadie actualiza.

Qué cubre arc42 y C4 no

C4 trata de la estructura y, a través de sus diagramas complementarios, de la ejecución y el despliegue. No dice nada de las partes de una arquitectura que no son cajas. En términos de arc42, estas secciones no tienen ningún equivalente en C4:

• Sección 1, Introducción y objetivos. Por qué existe el sistema, a quién le importa y los tres a cinco objetivos de calidad que marcan cada decisión posterior. Un diagrama de contexto C4 muestra quién usa el sistema. No puede decir que «un checkout debe completarse en menos de dos segundos» importa más que «la interfaz de administración es bonita».
• Sección 2, Restricciones. «Debe ejecutarse en la plataforma Kubernetes de la empresa», «debe estar escrito en Java», «los datos no pueden salir de la UE». Las restricciones explican decisiones que un diagrama solo muestra.
• Sección 4, Estrategia de solución. El puñado de decisiones fundamentales (primero un monolito, event sourcing para el libro contable, comprar el motor de búsqueda) resumidas en un solo lugar.
• Sección 8, Conceptos transversales. Autenticación, gestión de errores, logging, patrones de persistencia, internacionalización. Atraviesan todas las cajas, así que ninguna caja por sí sola puede mostrarlos.
• Sección 10, Requisitos de calidad. Escenarios de calidad concretos: estímulo, respuesta, medida.
• Sección 11, Riesgos y deuda técnica. Lo que sabes que es frágil y lo que has aplazado.
• Sección 12, Glosario. Las palabras que usa el negocio, definidas una vez.

Son exactamente las secciones que nombra la FAQ de arc42 cuando dice que C4 «omite ciertas partes». Si tu documentación de arquitectura son solo diagramas C4, estas son las preguntas que un nuevo arquitecto o un auditor seguirá teniendo después de leerla.

Qué aporta C4 a arc42

arc42 no prescribe una notación a propósito. La sección 5 pide una «colección jerárquica de cajas negras y cajas blancas», la sección 3 sugiere «todo tipo de diagramas que muestren el sistema como una caja negra», y la sección 6 acepta cualquier cosa, desde una lista numerada de pasos hasta diagramas de secuencia, BPMN o máquinas de estados (sección 5, sección 3, sección 6). Esa flexibilidad es una virtud de la plantilla, y también es donde más varían los documentos arc42: cada autor dibuja de una manera.

C4 cubre ese hueco con dos cosas:

1. Un zoom coherente. La vista de bloques de arc42 ya tiene niveles: el nivel 1 es «la descripción de caja blanca del sistema global junto con descripciones de caja negra de todos los bloques que contiene», y el nivel 2 «hace zoom en algunos bloques del nivel 1» (sección 5). Los niveles de C4 dan a esos pasos de zoom un significado fijo (sistema, contenedor, componente, código), de modo que un lector que conoce C4 sabe qué está mirando antes de leer las etiquetas.
2. Un vocabulario común reducido. Persona, sistema de software, contenedor, componente, relación, cada uno con un nombre, una descripción y normalmente una tecnología. Es notación suficiente para que los diagramas sean comparables entre equipos, y lo bastante poca para que nadie necesite formación.

Hay además una ventaja práctica. Si los diagramas C4 salen de un modelo en lugar de una herramienta de dibujo, el mismo elemento aparece con el mismo nombre en las secciones 3, 5, 6 y 7. arc42 no opina sobre cómo conseguirlo, pero es lo que hace que las secciones cuadren entre sí.

Tabla de correspondencia: qué diagrama C4 va en cada sección de arc42

Esta correspondencia es nuestra, derivada de las definiciones de las secciones de arc42 y de las definiciones de los diagramas C4. La FAQ de arc42 remite a ejemplos de la comunidad que combinan ambos (por ejemplo, el repositorio de ejemplo arc42 + C4 de bitsmuggler) en lugar de prescribir uno, y los equipos varían en los detalles indicados en la última columna.

Las secciones que no están en la tabla (1, 2, 4, 8, 10, 11, 12) son texto y tablas, no diagramas C4. No es una carencia de ninguno de los dos métodos; es el reparto del trabajo.

Ejemplo práctico

Así queda la combinación para el sistema de e-commerce de nuestra guía completa del modelo C4: una single-page app en React, un API gateway, servicios en Go para pedidos, productos y usuarios, bases de datos PostgreSQL, Kafka y un servicio de notificaciones. Es un esqueleto arc42 ligero con los diagramas C4 colocados, no un documento completo.

1. Introducción y objetivos
   - Propósito: los clientes exploran y piden productos; el personal de almacén gestiona el stock
   - Objetivos de calidad: (1) el checkout se completa en menos de 2 s en p95
                           (2) ningún pedido se confirma sin una autorización de pago correcta
                           (3) se puede añadir un servicio nuevo sin cambiar los existentes

2. Restricciones
   - Se ejecuta en la plataforma Kubernetes de la empresa; Go para los servicios backend

3. Contexto y alcance
   - Contexto de negocio: diagrama C4 System Context
     [Cliente], [Personal de almacén] -> [Plataforma de e-commerce]
     -> [Stripe], [FedEx API], [SendGrid]
   - Contexto técnico: tabla de interlocutor / protocolo / datos intercambiados

4. Estrategia de solución
   - Base de datos por servicio; notificaciones asíncronas mediante Kafka

5. Vista de bloques
   - Nivel 1: diagrama C4 Container (SPA, API Gateway, servicios Order/Product/User,
     tres bases de datos PostgreSQL, Kafka, Notification Service)
   - Nivel 2: diagrama C4 Component solo del Order Service
     (Order Handler, Order Service, Order Repository, Payment Client,
     Inventory Client)

6. Vista de ejecución
   - "El cliente realiza un pedido": diagrama dinámico C4, 10 pasos numerados

7. Vista de despliegue
   - Producción: diagrama de despliegue C4
   - Staging: solo las diferencias respecto a producción

8. Conceptos transversales
   - Autenticación en el gateway; claves de idempotencia en POST /orders;
     logging estructurado con un request ID

9. Decisiones de arquitectura
   - ADR-001 Base de datos por servicio
   - ADR-002 Kafka para los eventos de pedido en lugar de llamadas síncronas
   - ADR-003 Autorizar el pago antes de escribir el pedido

10. Requisitos de calidad
   - Escenario: 500 checkouts por minuto durante una rebaja, p95 por debajo de 2 s

11. Riesgos y deuda técnica
   - El stock se reserva antes del pago; aún no hay compensación si el pago falla

12. Glosario
   - Pedido, Reserva, Autorización, Preparación

Fíjate en dónde están los diagramas: secciones 3, 5, 6 y 7. Todo lo demás son unas pocas líneas de texto. Fíjate también en que el riesgo de la sección 11 y el ADR-003 de la sección 9 se refieren a lo mismo que muestra el diagrama dinámico de la sección 6. En esas referencias cruzadas es donde un documento que combina arc42 y C4 demuestra su valor: el diagrama muestra el orden de los pasos, el ADR explica por qué y el riesgo dice qué sigue mal.

Para el diagrama dinámico en sí, la guía del diagrama dinámico C4 recorre exactamente este escenario paso a paso. Para la sección 9, la guía completa de architecture decision records cubre el formato que recomienda arc42 y cómo mantener un índice.

Si las doce secciones de arc42 te parecen más de lo que necesita tu equipo, nuestra plantilla de documentación de arquitectura de software es un esquema en Markdown más corto construido con las mismas ideas, con una sección que explica cómo se corresponde con arc42.

Mantener ambos al día

arc42 y C4 comparten un modo de fallo: los dos son excelentes el día en que se escriben. La propia FAQ de arc42 advierte que cada sección que rellenas es mantenimiento al que te comprometes (B-1). Algunos hábitos que funcionan:

• Saca los diagramas del cuerpo del documento siempre que puedas. Referencia o inserta diagramas generados a partir de un modelo en lugar de pegar capturas de pantalla. Una captura de un diagrama de contenedores queda obsoleta el día en que se renombra un contenedor. Un diagrama renderizado desde el modelo solo está tan desactualizado como el modelo.
• Pon las secciones que cambian rápido junto al código. Las secciones 5, 6 y 9 cambian con el código. Las secciones 1, 2 y 10 cambian con el negocio. Guardar el primer grupo en el repositorio (arc42 ofrece plantillas en Markdown y AsciiDoc para ello) permite que los pull requests las actualicen.
• Escribe los ADR hacia delante, nunca los edites. Una decisión sustituida recibe un ADR nuevo. La sección 9 se convierte en un historial en lugar de una historia reescrita.
• Asigna a cada sección un responsable y una fecha de revisión. Un documento sin responsable es un documento que nadie actualiza.
• Contrasta las secciones estructurales con el código. Las secciones 3 y 5 describen cosas que existen en el código, así que pueden comprobarse automáticamente. Las secciones 1, 8 y 10 no; necesitan una revisión humana, periódica.

Ese último punto es donde encaja archyl, y solo para una parte del problema. archyl contiene el modelo C4, no un documento arc42. Su descubrimiento por IA propone sistemas, contenedores, componentes y relaciones a partir de un repositorio para que tú los apruebes, los ADR se vinculan a los elementos C4 a los que afectan, y una puntuación de deriva comprueba si los elementos documentados siguen existiendo en el código. Eso cubre las secciones con más diagramas (3, 5, 6, 9). No escribe tus objetivos de calidad, tus conceptos transversales ni tu lista de riesgos, y no hay exportación a arc42; las secciones de texto se quedan en tu documento arc42, enlazando al modelo.

FAQ

¿Es arc42 mejor que C4?

Ninguno es mejor, porque no hacen el mismo trabajo. arc42 es una plantilla de documentación que cubre objetivos, restricciones, estructura, ejecución, despliegue, decisiones, calidad y riesgos. C4 es una forma de dibujar la estructura de manera coherente. Si necesitas un documento de arquitectura completo, usa arc42 (o algo con una forma parecida). Si necesitas diagramas coherentes, usa C4. La mayoría de los equipos que necesitan ambos usan diagramas C4 dentro de arc42.

¿Se pueden usar arc42 y C4 juntos?

Sí, y es habitual. arc42 no prescribe una notación, así que los diagramas C4 encajan directamente en sus secciones: el diagrama de contexto en la sección 3, los diagramas de contenedores y componentes en la sección 5, los diagramas dinámicos en la sección 6 y los diagramas de despliegue en la sección 7.

¿Dónde va el diagrama de contenedores C4 en arc42?

En la sección 5, Vista de bloques, en el nivel 1: la vista de caja blanca del sistema completo. Los diagramas de componentes van en el nivel 2, para los contenedores que los necesiten. Si tu sistema es un monolito modular, tus bloques de nivel 1 pueden ser módulos en lugar de contenedores, y el encaje es menos exacto.

¿arc42 exige UML?

No. arc42 sugiere notaciones en varias secciones (la sección 3 menciona, por ejemplo, un diagrama de despliegue UML para el contexto técnico), pero deja la elección en tus manos. Con él se usan C4, UML y simples cajas y flechas.

¿Dónde van los ADR en arc42?

En la sección 9, Decisiones de arquitectura. El propio arc42 recomienda un ADR para cada decisión importante, con la estructura de Michael Nygard, y permite documentar una decisión localmente en el bloque al que afecta si así se lee mejor.

¿arc42 es gratuito?

Sí. La plantilla es gratuita y de código abierto, con licencia CC BY-SA 4.0, y está disponible en doce idiomas y formatos, entre ellos AsciiDoc, Markdown, Word y Confluence (página de descarga).

¿Quieres que la mitad C4 de tu documento arc42 siga fiel al código? Prueba archyl gratis y genera el modelo a partir de tu repositorio. Sigue leyendo: ¿Qué es el modelo C4? Guía completa | Architecture Decision Records: la guía completa | Guía del diagrama dinámico C4 | Plantilla de documentación de arquitectura de software.