¿Qué es el modelo C4? Guía completa para equipos de software
Los diagramas de arquitectura de software tienen un problema de reputación. Son demasiado abstractos para ser útiles o demasiado detallados para ser mantenibles. Probablemente has visto ambos: el diagrama de una sola caja etiquetada "El Sistema" que no te dice nada, y el extenso diagrama UML con 200 clases que te dice todo excepto lo que realmente necesitas saber.
El modelo C4, creado por Simon Brown, resuelve esto tomando prestada una idea de la cartografía. Los mapas funcionan a múltiples niveles de zoom. Empiezas con un mapa mundial para orientarte, luego haces zoom a un país, luego a una ciudad, luego a una calle. Cada nivel muestra la cantidad correcta de detalle para las preguntas que estás haciendo. El modelo C4 aplica este mismo principio a la arquitectura de software.
En esta guía, recorreremos todo lo que necesitas saber sobre el modelo C4: qué representa cada nivel, cuándo usarlo, errores comunes y cómo los equipos modernos implementan C4 en la práctica.
¿Qué significa C4?
C4 representa los cuatro niveles de abstracción que define el modelo:
- Context (Contexto) -- El panorama general. Cómo tu sistema encaja en el mundo.
- Containers (Contenedores) -- Los bloques técnicos de alto nivel de tu sistema.
- Components (Componentes) -- La estructura interna de cada contenedor.
- Code (Código) -- Los detalles reales de implementación.
Cada nivel responde diferentes preguntas para diferentes audiencias. Un product manager se interesa por el Contexto. Un ingeniero de plataforma se interesa por los Containers. Un desarrollador trabajando en un servicio específico se interesa por los Components. Nadie realmente necesita el nivel de Code dibujado a mano -- más sobre esto después.
El poder de C4 no está en ningún diagrama individual. Está en la jerarquía. Cada elemento en un nivel se descompone en un diagrama del siguiente nivel. Una caja etiquetada "Backend API" en el diagrama de Containers se convierte en su propio diagrama de Components mostrando los módulos internos. Esto crea una vista navegable y ampliable de tu arquitectura.
Nivel 1: Diagrama de Contexto del Sistema
El diagrama de Contexto del Sistema es el punto de partida para cualquier modelo C4. Responde una pregunta: ¿cómo encaja tu sistema en el entorno más amplio?
Qué muestra
- Tu sistema de software como una sola caja en el centro
- Las personas (actores, roles, personas) que lo usan
- Los sistemas externos con los que se integra
- Las relaciones entre todos ellos
Qué no muestra
- La estructura interna de tu sistema
- Las elecciones de tecnología
- Bases de datos, colas o infraestructura
- Detalles de despliegue
Un ejemplo real
Imagina que estás documentando una plataforma de e-commerce. Tu diagrama de Contexto del Sistema mostraría:
[Cliente] --> [Plataforma de E-Commerce] : Navega productos, realiza pedidos
[Personal de Almacén] --> [Plataforma de E-Commerce] : Gestiona inventario
[Plataforma de E-Commerce] --> [Pasarela de Pagos (Stripe)] : Procesa pagos
[Plataforma de E-Commerce] --> [Proveedor de Envíos (FedEx API)] : Crea envíos
[Plataforma de E-Commerce] --> [Servicio de Email (SendGrid)] : Envía notificaciones
Cinco usuarios y sistemas externos. Una sola caja para toda tu plataforma. Eso es todo.
Por qué este nivel importa
El diagrama de Contexto del Sistema obliga a tener claridad sobre los límites. ¿Qué posees? ¿De qué dependes? ¿Quiénes son tus usuarios? Estas preguntas parecen obvias, pero los equipos regularmente luchan para responderlas de manera consistente.
Este diagrama también es el que muestras a stakeholders no técnicos. Tu CEO puede mirarlo y entender qué hace el sistema, quién lo usa y de qué servicios de terceros depende. Intenta hacer eso con un diagrama de clases UML.
Consejos para un buen diagrama de Contexto del Sistema
- Mantenlo en una página. Si no cabe, el límite de tu sistema podría estar mal.
- Etiqueta cada relación con una frase verbal: "envía emails mediante", "procesa pagos a través de", "lee inventario de".
- Incluye todos los sistemas externos, incluso los que das por sentado (DNS, CDN, monitoreo).
- No incluyas detalles internos. Resiste la tentación.
Nivel 2: Diagrama de Containers
El diagrama de Containers hace zoom en tu sistema y muestra sus bloques técnicos de alto nivel. En terminología C4, un "container" es cualquier unidad desplegable o ejecutable por separado -- no necesariamente un container Docker.
Qué cuenta como Container
- Una aplicación web (React SPA, app Next.js)
- Una aplicación móvil (app iOS, app Android)
- Un servicio de backend API (Go API, servidor Node.js)
- Una base de datos (PostgreSQL, MongoDB, Redis)
- Un message broker (Kafka, RabbitMQ)
- Un sistema de almacenamiento de archivos (S3, MinIO)
- Una función serverless (AWS Lambda, Cloud Functions)
Cada container ejecuta en su propio proceso o tiene su propio almacenamiento de datos. Ese es el factor diferenciador. Dos paquetes de Go desplegados juntos son parte del mismo container. Dos servicios de Go desplegados independientemente son containers separados.
Un ejemplo real
Haciendo zoom en nuestra plataforma de e-commerce:
[Single-Page Application (React)] --> [API Gateway (Kong)] : Realiza llamadas API (HTTPS/JSON)
[API Gateway] --> [Order Service (Go)] : Enruta peticiones
[API Gateway] --> [Product Service (Go)] : Enruta peticiones
[API Gateway] --> [User Service (Go)] : Enruta peticiones
[Order Service] --> [Order Database (PostgreSQL)] : Lee/escribe pedidos
[Product Service] --> [Product Database (PostgreSQL)] : Lee/escribe productos
[User Service] --> [User Database (PostgreSQL)] : Lee/escribe usuarios
[Order Service] --> [Message Queue (Kafka)] : Publica eventos de pedidos
[Notification Service (Go)] --> [Message Queue] : Consume eventos de pedidos
Ahora puedes ver las elecciones de tecnología, los patrones de comunicación y los almacenes de datos. Un arquitecto puede discutir si fusionar las bases de datos de Order y Product. Un ingeniero DevOps puede planificar la topología de despliegue. Un nuevo desarrollador puede entender dónde termina el frontend React y dónde empieza el backend Go.
Consejos para un buen diagrama de Containers
- Incluye la tecnología entre paréntesis: "Order Service (Go)", "Database (PostgreSQL)".
- Muestra el protocolo de comunicación en las relaciones: "HTTPS/JSON", "gRPC", "AMQP".
- Si tienes más de 15-20 containers, crea múltiples diagramas de Containers para diferentes subsistemas.
- Incluye bases de datos y colas. También son containers.
- No bajes al nivel de container aquí. Los módulos internos pertenecen al diagrama de Components.
Nivel 3: Diagrama de Components
El diagrama de Components hace zoom en un solo container y muestra sus bloques de construcción estructurales internos. Los componentes son las abstracciones principales dentro de un container -- piensa en paquetes, módulos, servicios o capas.
Qué cuenta como Component
- Un handler HTTP o controlador
- Un servicio de lógica de negocio
- Un repositorio o capa de acceso a datos
- Un cliente de API externa
- Un procesador de trabajos en segundo plano
- Un middleware o interceptor
Los componentes son agrupaciones lógicas, no necesariamente archivos individuales. El componente OrderHandler podría estar implementado en varios archivos, pero conceptualmente es una sola cosa: la parte del sistema que maneja las peticiones HTTP relacionadas con pedidos.
Un ejemplo real
Haciendo zoom en el container Order Service:
[Order Handler] --> [Order Service] : Delega lógica de negocio
[Order Service] --> [Order Repository] : Persiste pedidos
[Order Service] --> [Payment Client] : Valida pago
[Order Service] --> [Inventory Client] : Verifica disponibilidad de stock
[Order Repository] --> [Order Database (PostgreSQL)] : Consultas SQL
[Payment Client] --> [Payment Gateway (Stripe)] : HTTPS/REST
[Inventory Client] --> [Product Service] : gRPC
Un desarrollador que se une a este equipo puede ver inmediatamente cómo está estructurado el Order Service: las peticiones entran por el handler, la lógica de negocio vive en el servicio, el acceso a datos pasa por el repositorio, y las llamadas externas van a través de clientes dedicados.
Cuándo crear diagramas de Components
No todo container necesita un diagrama de Components. Crea uno cuando:
- El container es lo suficientemente complejo como para que un nuevo desarrollador tenga dificultades para navegarlo
- Hay patrones de diseño importantes (arquitectura hexagonal, CQRS) que el diagrama puede hacer explícitos
- Múltiples equipos contribuyen al mismo container y necesitan una comprensión compartida de su estructura
Omite el diagrama de Components cuando:
- El container es simple (un servicio CRUD con tres endpoints)
- La estructura del código es obvia desde la organización de carpetas
- El container es una herramienta de terceros (Redis, Kafka) donde no controlas los internos
Nivel 4: Diagrama de Code
El nivel de Code muestra los detalles reales de implementación: clases, interfaces, funciones y sus relaciones. Esto es esencialmente un diagrama de clases UML o un diagrama entidad-relación.
La verdad honesta sobre el Nivel 4
El mismo Simon Brown aconseja no crear diagramas de Code manualmente. Aquí está por qué:
- Cambian con demasiada frecuencia. Cada refactoring los invalida.
- Son costosos de mantener. Dibujar diagramas de clases a mano es tedioso.
- Duplican información que ya existe en el código.
- Los IDEs modernos pueden generarlos bajo demanda.
Si necesitas diagramas a nivel de Code, genéralos desde tu código fuente usando herramientas que soporten tu lenguaje. No los dibujes a mano.
Cuándo los diagramas de Code realmente ayudan
Hay excepciones:
- Algoritmos complejos que se benefician de un recorrido visual
- Patrones de diseño (Strategy, Observer, State Machine) donde la estructura es la parte interesante
- Superficies de API públicas donde quieres documentar los contratos
- Materiales de entrevista o onboarding donde estás enseñando patrones
En la práctica, la mayoría de los equipos usan tres niveles de C4 (Context, Container, Component) y dejan el nivel de Code a las vistas generadas por el IDE.
Los diagramas complementarios
Más allá de los cuatro niveles principales, Simon Brown define varios diagramas complementarios que complementan la jerarquía C4:
Diagrama de Landscape del Sistema
Un diagrama de Contexto del Sistema con más zoom hacia afuera. Muestra todos los sistemas de software de una empresa y cómo se relacionan entre sí. Útil para arquitectos empresariales que gestionan un portafolio de sistemas.
Diagrama de Deployment
Mapea containers a infraestructura. Muestra qué containers ejecutan en qué servidores, en qué regiones cloud, detrás de qué load balancers. Esencial para equipos de DevOps y plataforma.
Diagrama dinámico
Muestra cómo los elementos colaboran en tiempo de ejecución para cumplir un caso de uso específico. Similar a un diagrama de secuencia UML pero usando notación C4. Útil para documentar flujos complejos como "qué pasa cuando un usuario hace un pedido."
Modelo C4 vs. otros enfoques
C4 vs. UML
UML define 14 tipos de diagramas. La mayoría de los equipos usan 2-3 de ellos, y frecuentemente de manera inconsistente. C4 te da 4 niveles con propósitos claros. Es más simple de aprender, más simple de usar y más simple de mantener.
Dicho esto, C4 y UML no son mutuamente excluyentes. Puedes usar diagramas de clases UML en el Nivel 4, o diagramas de secuencia UML como diagramas dinámicos. C4 proporciona la jerarquía; UML proporciona notaciones específicas cuando las necesitas.
C4 vs. Arc42
Arc42 es una plantilla para documentación de arquitectura. Cubre mucho más que solo diagramas: requisitos de calidad, restricciones, riesgos, vistas de despliegue y más. C4 se enfoca específicamente en diagramas jerárquicos. Muchos equipos usan ambos: Arc42 como estructura de documentación y C4 como enfoque de diagramación dentro de ella.
C4 vs. "Solo usa una pizarra"
Las pizarras son excelentes para exploración y lluvia de ideas. Son terribles para documentación. Los diagramas de pizarra se borran, se fotografían mal y nunca se actualizan. C4 proporciona la estructura para convertir exploraciones de pizarra en documentación duradera.
Errores comunes al adoptar C4
Intentar mostrar todo a la vez
El punto central de C4 es la divulgación progresiva. Si tu diagrama de Containers muestra clases individuales, has colapsado la jerarquía. Cada diagrama debería mostrar elementos en un solo nivel de zoom.
Ignorar las relaciones
Cajas sin flechas son un inventario, no arquitectura. Las relaciones -- quién llama a quién, qué protocolo usan, qué datos fluyen entre ellos -- son frecuentemente más valiosas que las cajas mismas. Siempre etiqueta tus relaciones.
Hacerlo una actividad de una sola persona
La documentación de arquitectura es un deporte de equipo. Si solo una persona crea y mantiene los diagramas, reflejarán la comprensión (o malentendido) de esa sola persona. Revisa los diagramas C4 en equipo, idealmente como parte de tu proceso de revisión de arquitectura.
No vincular a otra documentación
Un diagrama C4 gana poder cuando se conecta a otros artefactos. Vincula containers a sus runbooks de despliegue. Vincula componentes a sus Architecture Decision Records (ADRs). Vincula sistemas externos a su documentación de API. Los diagramas aislados son menos valiosos que los conectados.
Dejar que los diagramas se desactualicen
El mayor asesino de cualquier enfoque de documentación es la obsolescencia. Un diagrama que describe la arquitectura del año pasado es peor que no tener diagrama porque activamente confunde. Incorpora las actualizaciones de diagramas en tu flujo de trabajo -- hazlas parte de las checklists de pull requests, sprint reviews o reuniones de arquitectura.
Cómo Archyl implementa el modelo C4
Archyl fue construido alrededor del modelo C4 como concepto de primera clase. Así es como cada nivel se mapea a funcionalidades de la plataforma:
Contexto del Sistema en Archyl
Cuando creas un proyecto en Archyl, defines sistemas y sus relaciones con actores externos. La vista de Contexto del Sistema se renderiza automáticamente desde tu modelo -- no se requiere dibujo manual. Agrega un sistema, agrega un actor externo, dibuja una relación, y el diagrama se actualiza en tiempo real.
Diagrama de Containers en Archyl
Dentro de cada sistema, defines containers con sus stacks tecnológicos. Archyl renderiza el diagrama de Containers y te permite hacer drill down en cualquier container para ver sus componentes. Las relaciones entre containers muestran los protocolos de comunicación y flujos de datos.
Diagrama de Components en Archyl
Dentro de cada container, defines componentes. Archyl los mapea a código real a través de su funcionalidad de Code Elements, que vincula componentes a archivos y directorios específicos en tu repositorio. Esta conexión entre diagrama y código es lo que habilita la detección de drift.
Descubrimiento asistido por IA
Lo que diferencia a Archyl de una herramienta de dibujo es que no tienes que construir el modelo a mano. Conecta tu repositorio, ejecuta el descubrimiento por IA, y Archyl genera un borrador del modelo C4 desde tu código. La IA identifica sistemas, containers, componentes y relaciones analizando la estructura de tu código, archivos de configuración y grafos de dependencias.
Revisas las sugerencias, las aceptas o modificas, y tienes un modelo C4 en minutos en lugar de semanas.
Detección de drift
Una vez que tu modelo C4 existe, Archyl verifica continuamente si aún refleja la realidad. El drift score te dice qué porcentaje de tu arquitectura documentada realmente existe en el código. Si alguien renombra un servicio o elimina un componente, el drift score baja, y sabes que tu documentación necesita actualización.
Este es el vacío que la mayoría de las herramientas de C4 no cubren. Crear diagramas es la parte fácil. Mantenerlos precisos es la parte difícil. La detección de drift de Archyl cierra esa brecha.
Para empezar con C4: un enfoque paso a paso
Si tu equipo es nuevo en el modelo C4, aquí tienes un camino práctico de adopción:
Semana 1: Contexto del Sistema
Reúne a tu equipo para un taller de una hora. Dibuja tu sistema como una sola caja. Identifica cada rol de usuario y sistema externo. Dibuja las relaciones. Te sorprenderá cuánto debate genera este simple ejercicio -- y cuánta alineación crea.
Semana 2: Diagrama de Containers
Toma la caja del sistema de tu diagrama de Contexto y divídela en containers. ¿Cuáles son las unidades desplegables? ¿Qué bases de datos existen? ¿Qué message brokers o cachés están en juego? Aquí es donde haces visibles las elecciones de tecnología.
Semanas 3-4: Diagramas de Components para containers clave
Elige los dos o tres containers más complejos. Descompón cada uno en componentes. Aquí es donde los nuevos desarrolladores pasarán la mayor parte de su tiempo, así que prioriza los containers que son más difíciles de entender.
Continuamente: Mantener y evolucionar
La creación inicial es la parte fácil. La disciplina de mantener los diagramas actualizados es lo que separa a los equipos que obtienen valor de C4 de los que lo abandonan después de un mes. Automatiza lo que puedas. Usa herramientas que detecten drift. Haz que las revisiones de diagramas sean parte de tu flujo de desarrollo.
Por qué C4 funciona
El modelo C4 no es técnicamente revolucionario. La descomposición jerárquica y los niveles de abstracción han existido en informática desde los años 60. Lo que Simon Brown hizo fue empaquetar estas ideas en un framework simple y memorable con reglas claras y notación mínima.
Funciona porque:
- Es fácil de aprender. Cuatro niveles. Cajas y flechas. No se requiere certificación UML.
- Escala. Desde un proyecto de fin de semana hasta una plataforma empresarial, los mismos cuatro niveles aplican.
- Sirve a múltiples audiencias. Ejecutivos, arquitectos y desarrolladores cada uno obtiene el diagrama que habla su lenguaje.
- Es agnóstico de herramientas. Puedes usar una pizarra, una herramienta de dibujo, un formato basado en texto o una plataforma dedicada como Archyl.
- Se enfoca en lo correcto. Estructura y relaciones, no detalles de implementación.
Si la documentación de arquitectura de tu equipo consiste en archivos Visio desactualizados, fotos de pizarras en Slack y conocimiento tribal, el modelo C4 es el camino más práctico hacia algo mejor.
¿Listo para construir tu modelo C4? Prueba Archyl gratis y genera tu primer diagrama de arquitectura desde código en minutos. O explora más: Descubrimiento de arquitectura asistido por IA | Architecture as Code: Define tu modelo C4 en YAML | Architecture Drift Score.