Introducción al modelo C4 para arquitectura de software
Todavía recuerdo la sesión de pizarra que me hizo repensar todo sobre los diagramas de arquitectura. Estábamos integrando a una nueva desarrolladora, y pasé 45 minutos dibujando cajas y flechas tratando de explicar nuestra plataforma de e-commerce. Al final, ella parecía más confundida que al principio. El diagrama tenía todo — microservicios, bases de datos, colas de mensajes, APIs externas — todo amontonado con notación inconsistente y sin jerarquía clara.
Esa noche, me topé con el modelo C4 de Simon Brown, y fue uno de esos momentos de "¿por qué no pensé en esto?". La idea es engañosamente simple: en lugar de meter todo en un solo diagrama, creas múltiples diagramas a diferentes niveles de zoom. Como Google Maps, empiezas alejado para ver el panorama general, luego haces zoom progresivamente para ver más detalle.
Los cuatro niveles de C4
El "C4" representa cuatro niveles de abstracción, cada uno respondiendo diferentes preguntas:
Nivel 1: Contexto del Sistema
Esta es la vista a 10.000 metros de altura. Todo tu sistema es una sola caja, y muestras:
- Quién usa tu sistema (personas o roles)
- Qué sistemas externos integras
Eso es todo. Sin detalles internos, sin elecciones de tecnología, sin bases de datos. Solo "aquí está nuestro sistema, aquí está quién lo usa, y aquí está con qué habla."
Cuando dibujé mi primer diagrama de Contexto de Sistema para nuestra plataforma, cabía en una sola diapositiva. Nuestro CEO podía entenderlo. Eso nunca había pasado antes con mis diagramas de arquitectura.
Esto es lo que hace poderoso este nivel: te obliga a pensar en los límites. ¿Qué está dentro de tu sistema versus qué está afuera? ¿Qué posees versus de qué dependes? Estas preguntas parecen obvias, pero he visto equipos batallar para responderlas claramente.
Nivel 2: Diagrama de Containers
Ahora hacemos zoom un nivel. Un "container" en terminología C4 no es un container Docker — es cualquier unidad desplegable que ejecuta código o almacena datos:
- Aplicaciones web
- Aplicaciones móviles
- Servicios backend
- Bases de datos
- Colas de mensajes
- Almacenamiento de archivos
Este diagrama muestra la arquitectura técnica de alto nivel. Puedes ver las principales elecciones de tecnología (frontend React, backend Go, base de datos PostgreSQL) y cómo fluyen los datos entre ellos.
Encuentro este nivel más útil para:
- Planificar infraestructura y despliegues
- Discutir elecciones de tecnología con el equipo
- Explicar el sistema a nuevos desarrolladores backend o frontend
Una cosa que aprendí: ten cuidado con la granularidad aquí. Si tienes 30 microservicios, no muestres los 30 como containers separados. Agrupa servicios relacionados o crea múltiples diagramas de Containers para diferentes áreas de tu sistema.
Nivel 3: Diagrama de Componentes
Aquí es donde hacemos zoom en un solo container. Los componentes son los bloques de construcción estructurales principales dentro de ese container — piensa en servicios, repositorios, controladores o módulos.
Para nuestro backend Go, un diagrama de Componentes podría mostrar:
- Handlers HTTP
- Servicios de lógica de negocio
- Interfaces de repositorio
- Clientes de APIs externas
Seré honesto: no creo diagramas de Componentes para cada container. Solo para los complejos que los nuevos desarrolladores tienen problemas para entender. Para un servicio CRUD simple, el código mismo es la documentación.
Nivel 4: Diagrama de Código
El nivel más profundo muestra elementos de código reales — clases, interfaces, funciones. El mismo Simon Brown dice que este nivel es opcional y frecuentemente auto-generado desde el código.
En la práctica, rara vez creo diagramas de Código manualmente. Cuando lo hago, es para algoritmos o patrones particularmente complejos que se benefician de explicación visual. La mayoría del tiempo, si necesitas este nivel de detalle, deberías estar leyendo el código real.
Por qué el C4 funcionó para nuestro equipo
Antes de C4, nuestra documentación de arquitectura era un desastre. Teníamos:
- Diagramas Visio de 2019 que nadie actualizaba
- Fotos de pizarras en canales de Slack aleatorios
- Archivos README con arte ASCII que más o menos explicaba las cosas
- Conocimiento tribal que se iba cuando la gente se marchaba
El modelo C4 nos dio un marco que realmente funciona. He aquí por qué:
Es suficientemente simple para recordar
Cuatro niveles. Eso es todo. No necesitas memorizar 14 tipos diferentes de diagramas UML o discutir si algo debería ser un "componente" o un "módulo" en el sentido UML.
Diferentes audiencias, diferentes diagramas
Nuestro CEO mira el diagrama de Contexto de Sistema. Nuestros arquitectos discuten el diagrama de Containers. Nuestros desarrolladores trabajan con diagramas de Componentes. Cada uno obtiene el nivel correcto de detalle para sus necesidades.
Se mantiene actualizado
Porque los diagramas C4 son relativamente simples, no es doloroso actualizarlos. Cuando agregamos una nueva integración externa, actualizar el diagrama de Contexto de Sistema toma 5 minutos. Compara eso con actualizar un diagrama UML detallado con cada clase y método.
Es agnóstico de herramientas
Empezamos con draw.io, nos movimos a Miro para colaboración, y ahora usamos Archyl para diagramación asistida por IA. El modelo C4 funciona con cualquier herramienta porque se trata de los conceptos, no de la notación.
Errores comunes que he cometido (para que tú no los cometas)
Error 1: Mostrar demasiado detalle demasiado pronto
Mi primer diagrama de Containers tenía 47 cajas. Era preciso pero inútil. Ahora sigo una regla: si tu diagrama no cabe en una pantalla, estás en el nivel de zoom equivocado.
Error 2: Olvidar las relaciones
Un diagrama con cajas pero sin flechas es solo un inventario. Las relaciones — quién llama a quién, qué datos fluyen hacia dónde — son frecuentemente más importantes que las cajas mismas. Etiqueta tus flechas. Describe los protocolos y formatos de datos.
Error 3: No actualizar después de cambios
El mejor diagrama es inútil si describe el sistema de hace dos años. Resolvimos esto haciendo que las actualizaciones de diagramas sean parte de nuestra checklist de PR para cambios arquitecturales. No es perfecto, pero ayuda.
Error 4: Sobre-ingeniería de la notación
Pasé una semana diseñando iconos personalizados y esquemas de colores para nuestros diagramas C4. Pérdida total de tiempo. Cajas simples con etiquetas claras funcionan bien. Enfócate en el contenido, no en la estética.
Para empezar
Si eres nuevo en C4, esto es lo que sugeriría:
Empieza con Contexto de Sistema. Toma 30 minutos para dibujar tu sistema como una sola caja, rodeada de los usuarios y sistemas externos. Solo esto ya tiene valor.
Agrega un diagrama de Containers. Elige tu sistema más complejo y descomponlo en unidades desplegables. Muestra cómo se comunican.
Para ahí por ahora. No intentes documentar todo de una vez. Deja que los diagramas prueben su valor antes de invertir más tiempo.
Hazlo colaborativo. Comparte los diagramas con tu equipo. Obtén retroalimentación. La documentación de arquitectura no debería ser una actividad solitaria.
Cómo usamos C4 en Archyl
Construyendo Archyl, obviamente comemos nuestra propia comida de perro. Nuestra documentación de arquitectura usa C4 en todas partes:
- El diagrama de Contexto de Sistema muestra Archyl conectándose a varios proveedores git, servicios de IA y sistemas de pago
- Los diagramas de Containers detallan el backend Go y el frontend React
- Los diagramas de Componentes detallan el servicio de descubrimiento y el motor de renderizado de diagramas
Lo poderoso es vincular estos diagramas a otra documentación. Un Architecture Decision Record sobre elegir PostgreSQL en lugar de MongoDB se vincula directamente al container de base de datos en nuestro diagrama de Containers. Los flujos de usuario referencian los componentes específicos que atraviesan.
Esta documentación interconectada es lo que estamos construyendo en Archyl — la capacidad de ver tu arquitectura no como diagramas aislados sino como un grafo de conocimiento conectado.
Conclusión
El modelo C4 no es revolucionario en sus conceptos. Los niveles de abstracción y la descomposición jerárquica han existido siempre. Lo que Simon Brown hizo brillantemente fue empaquetar estas ideas en un marco simple y memorable que realmente se usa.
Si tu documentación de arquitectura es un desorden de archivos Visio obsoletos y fotos de pizarras, prueba C4. Empieza pequeño, con solo un diagrama de Contexto de Sistema. Podrías sorprenderte de cuánta claridad puede traer un solo diagrama bien pensado.
Esto es parte de nuestra serie sobre documentación de arquitectura. Siguiente: Cómo la IA puede descubrir automáticamente tu arquitectura y Por qué la documentación importa más de lo que crees.