Diagrama de Componentes C4: guía completa con ejemplos
El diagrama de Componentes es el nivel 3 del modelo C4 -- y es el nivel con peor reputación. El nivel 1 (Contexto de Sistema) es fácil de dibujar y rara vez cambia. El nivel 2 (Contenedor) se corresponde de forma limpia con lo que despliegas. ¿Pero el nivel 3? Hace zoom en los internos de un único contenedor, lo que significa que cambia cada vez que un desarrollador reestructura un paquete. La mayoría de los equipos o bien lo omiten por completo, o lo dibujan una vez y dejan que se pudra.
Es una lástima, porque un diagrama de componentes bien mantenido es el artefacto más útil para un desarrollador que se incorpora a una base de código. Responde a la pregunta que se hace todo recién llegado: "¿dónde vive realmente la lógica de X?".
Esta guía cubre qué es un diagrama de Componentes C4, en qué se diferencia de un diagrama de componentes UML, cuándo vale la pena el coste de mantenimiento del nivel 3 (y cuándo no), un ejemplo completo resuelto, los errores que hacen inútiles los diagramas de componentes, y cómo mantenerlos precisos sin hacerlo todo a mano.
Si el modelo C4 en sí es nuevo para ti, empieza por nuestra guía completa del modelo C4 y luego vuelve aquí.
¿Qué es un diagrama de Componentes C4?
Un diagrama de componentes abre un contenedor -- una unidad desplegable de tu diagrama de contenedores -- y revela los componentes que hay dentro.
En términos de C4, un componente es una agrupación cohesiva de funcionalidad relacionada que se sitúa tras una interfaz bien definida. Piensa en las piezas principales dentro de una aplicación:
- Un grupo de controladores o handlers HTTP
- Un servicio de dominio que posee una porción de la lógica de negocio
- Un repositorio o capa de acceso a datos
- Un cliente que envuelve una API externa
- Un middleware, interceptor o worker en segundo plano
La palabra clave es agrupación. Un componente es una abstracción sobre el código, no una única clase o archivo. El componente OrderService podría abarcar una docena de archivos, pero conceptualmente es una sola cosa: la parte del contenedor responsable de la lógica de negocio de pedidos. Como dice la definición del glosario, un componente C4 es "una agrupación de código de más alto nivel con una única responsabilidad" -- no un mapeo 1:1 a una clase de un lenguaje de programación.
Qué responde el diagrama de Componentes
- ¿Cómo está estructurado internamente este contenedor?
- ¿Qué componente posee qué responsabilidad?
- ¿Cómo colaboran los componentes para gestionar una petición?
- ¿Dónde se originan las llamadas a bases de datos y sistemas externos?
Qué deja fuera deliberadamente
- Clases, interfaces y funciones individuales (eso es el nivel 4, el diagrama de Código)
- Los internos de otros contenedores
- Detalles de despliegue e infraestructura
Un contenedor por diagrama, solo componentes. Si te descubres dibujando clases, has hecho zoom demasiado lejos.
Diagrama de Componentes C4 vs. diagrama de Componentes UML
Esto confunde a la gente constantemente, porque UML también tiene algo llamado "diagrama de componentes" -- y no es lo mismo.
Un diagrama de componentes UML modela los componentes de software como unidades con interfaces provistas y requeridas (la famosa notación de piruleta y enchufe), a menudo enfatizando el empaquetado físico, los artefactos y las relaciones de despliegue. Viene con reglas de notación formales y un metamodelo preciso.
Un diagrama de componentes C4 es más laxo y más pragmático. Es simplemente el nivel 3 de una jerarquía de zoom: cajas para los componentes, flechas para las relaciones, una breve descripción de texto en cada uno. No hay ninguna notación especial que aprender. El valor viene de la jerarquía -- cada caja de componente vive dentro de un contenedor específico, que vive dentro de un sistema específico -- no de la notación en sí.
En la práctica: si alguien pide un "diagrama de componentes" en un contexto C4, quiere un mapa estructural de los internos de un contenedor que un nuevo desarrollador pueda leer en dos minutos. Si quiere interfaces de piruleta y estereotipos <<artifact>>, está pidiendo UML.
¿Cuándo vale la pena mantener el nivel 3?
Aquí está la respuesta honesta que la mayoría de las guías se saltan: el nivel 3 es el nivel con la peor relación esfuerzo-estabilidad de todo el modelo C4.
Los diagramas de contexto cambian unas pocas veces al año. Los diagramas de contenedores cambian cuando añades o eliminas un servicio -- quizá mensualmente. Los diagramas de componentes cambian cada vez que alguien refactoriza un paquete, extrae un servicio o renombra un módulo. Si los mantienes a mano, te estás apuntando a una jardinería constante, y en el momento en que paras, el diagrama empieza a mentir.
Así que sé deliberado sobre dónde inviertes ese esfuerzo.
Crea un diagrama de componentes cuando:
- El contenedor es genuinamente complejo. Una API de backend con 15 paquetes, varias capas y límites poco evidentes merece un mapa. Un servicio CRUD de tres endpoints no.
- La estructura encarna un diseño deliberado. Si usas arquitectura hexagonal, CQRS o un esquema de capas limpio, el diagrama de componentes hace explícita la estructura prevista -- y te da algo a lo que apuntar cuando un pull request la viola.
- Varios equipos tocan el mismo contenedor. El código compartido necesita un modelo mental compartido.
- El onboarding es un cuello de botella. Si los nuevos desarrolladores tardan semanas en orientarse en un contenedor, un diagrama de componentes se amortiza con la primera contratación.
Sáltatelo cuando:
- El contenedor es pequeño y su estructura de carpetas se explica por sí sola.
- El contenedor es de terceros (no dibujas los internos de Redis).
- Nadie se va a comprometer a mantenerlo actualizado. Un diagrama de componentes obsoleto es peor que ninguno -- envía con total confianza a los desarrolladores a código que ya no existe.
Esta es exactamente la razón por la que el nivel 3 es el que la mayoría de los equipos o bien omiten o bien automatizan. Generar los componentes a partir de la estructura real del código -- y verificarlos contra ella -- elimina el impuesto de mantenimiento que mata los diagramas dibujados a mano. Más sobre esto a continuación.
Un ejemplo resuelto: dentro de un contenedor de API
Hagámoslo concreto. Toma la plataforma de e-commerce de nuestra guía del modelo C4 y haz zoom en un único contenedor: la API de Pedidos (Go). En el nivel 2, es una caja. En el nivel 3, se abre en componentes.
Los componentes
| Componente | Responsabilidad |
|---|---|
| Auth Middleware | Valida los tokens JWT en las peticiones entrantes, inyecta la identidad del usuario en el contexto de la petición |
| Order Controller | Endpoints REST para crear, leer y cancelar pedidos; validación de peticiones y serialización de respuestas |
| Admin Controller | Endpoints REST para la gestión de pedidos de back-office (reembolsos, cambios manuales de estado) |
| Order Service | Lógica de negocio central: ciclo de vida del pedido, reglas de precios, comprobaciones de stock, orquestación de pagos |
| Order Repository | Capa de acceso a datos; persiste y consulta pedidos vía SQL |
| Payment Client | Envuelve la API de Stripe; gestiona autorización, captura y reembolsos |
| Email Adapter | Envía correos transaccionales (confirmación de pedido, actualizaciones de envío) vía SendGrid |
| Event Publisher | Publica eventos de dominio (OrderPlaced, OrderCancelled) en Kafka |
Las relaciones
[Auth Middleware] --> [Order Controller] : Passes authenticated requests
[Auth Middleware] --> [Admin Controller] : Passes authenticated requests (admin role)
[Order Controller] --> [Order Service] : Delegates business operations
[Admin Controller] --> [Order Service] : Delegates back-office operations
[Order Service] --> [Order Repository] : Reads/writes orders
[Order Service] --> [Payment Client] : Authorizes and captures payments
[Order Service] --> [Email Adapter] : Triggers transactional emails
[Order Service] --> [Event Publisher] : Emits domain events
[Order Repository] --> [Order Database (PostgreSQL)] : SQL
[Payment Client] --> [Payment Gateway (Stripe)] : HTTPS/REST
[Email Adapter] --> [Email Service (SendGrid)] : HTTPS/REST
[Event Publisher] --> [Message Queue (Kafka)] : Publishes events
Fíjate en que la base de datos, Stripe, SendGrid y Kafka aparecen en los bordes. No son componentes de este contenedor -- son contenedores vecinos y sistemas externos -- pero mostrar dónde se originan las llamadas salientes es exactamente lo que hace útil el diagrama.
Qué le dice este diagrama a un nuevo desarrollador
En treinta segundos, un desarrollador que se incorpora a este equipo aprende:
- La ruta de la petición: middleware → controller → service → repository. Hay exactamente un lugar donde vive la lógica de negocio, y no es el controller.
- Los límites: todas las llamadas externas pasan por adaptadores dedicados (
Payment Client,Email Adapter). Si necesitas hablar con Stripe, extiendes el cliente; no importas el SDK en un controller. - Los efectos secundarios: los pedidos producen eventos en Kafka y correos vía SendGrid. Si un correo no se envía, sabes qué dos componentes revisar.
- Dónde añadir código: una nueva funcionalidad de "tarjeta regalo" claramente necesita cambios en el controller, el service y posiblemente un nuevo cliente -- y el diagrama muestra el patrón a seguir.
Ese último punto está infravalorado. Un diagrama de componentes no solo describe la estructura -- la prescribe. Les dice a los contribuyentes qué aspecto tiene "coherente con esta base de código".
Errores comunes con los diagramas de Componentes
Mapear una clase a un componente
El error más frecuente. Si tu contenedor tiene 80 clases y tu diagrama de componentes tiene 80 cajas, has dibujado un diagrama de clases con pasos de más. Los componentes son agrupaciones: OrderController (un componente) podría cubrir cinco clases de handler. Apunta a 5-15 componentes por contenedor. Si pasas de 20, tus abstracciones son demasiado granulares -- o tu contenedor está haciendo demasiado.
Documentar cada contenedor en el nivel 3
La simetría es tentadora: "tenemos 12 contenedores, así que necesitamos 12 diagramas de componentes". Resístete. La mayoría de esos diagramas nunca se leerán ni se actualizarán. Documenta los dos o tres contenedores donde la complejidad de verdad duele, y deja que la estructura de carpetas hable por el resto.
Dejar que el diagrama se pudra
El nivel 3 deriva más rápido que cualquier otro nivel. Un diagrama de componentes dibujado en enero describe un contenedor que probablemente no existe en junio. Cada refactor, cada paquete extraído, cada módulo renombrado ensancha la brecha. Y un diagrama confiadamente erróneo es peor que ningún diagrama: envía a los desarrolladores a cazar componentes que se eliminaron hace dos trimestres. Si no puedes automatizar el mantenimiento, al menos pon "actualizar el diagrama de componentes" en la checklist de pull request de ese contenedor.
Dibujar componentes sin responsabilidades
Una caja etiquetada como OrderManager sin descripción es ruido. Cada componente debería llevar una declaración de responsabilidad de una línea ("Valida los tokens JWT e inyecta la identidad del usuario"). Si no puedes escribir esa frase, el límite del componente probablemente esté mal.
Mostrar detalle de implementación en lugar de estructura
Genéricos, patrones de diseño, utilidades auxiliares -- nada de eso pertenece al nivel 3. Si la parte interesante de un componente es cómo está implementado, ese es un trabajo para el diagrama de Código (o, más a menudo, para el propio código).
Cómo Archyl mantiene precisos los diagramas de Componentes
Todo lo anterior apunta a la misma conclusión: los diagramas de componentes son valiosos, pero mantenerlos a mano es una batalla perdida. Este es precisamente el problema que Archyl fue construido para resolver.
El descubrimiento por IA extrae los componentes del código
En lugar de dibujar los componentes a mano, conectas tu repositorio y ejecutas el descubrimiento por IA. Archyl analiza la estructura de tu código -- paquetes, módulos, capas, convenciones de nombres -- y propone un modelo C4, incluidos los componentes dentro de cada contenedor y las relaciones entre ellos. Un servicio en Go con paquetes handlers/, service/ y repository/ vuelve como exactamente el tipo de diagrama de componentes mostrado en el ejemplo de arriba. Revisas las sugerencias, las aceptas o las ajustas, y tienes un modelo de nivel 3 en minutos.
La detección de drift señala la divergencia
Esta es la parte que mantiene vivo el nivel 3. Como Archyl enlaza los componentes con archivos y directorios reales de tu repositorio, puede comprobar de forma continua si los componentes documentados todavía existen en el código. Cuando alguien elimina un paquete, renombra un módulo o reestructura una capa, la puntuación de drift baja y los componentes afectados se señalan. Tu diagrama de componentes deja de ser una instantánea y se convierte en un contrato monitorizado.
Arquitectura como Código
Si prefieres definiciones explícitas en lugar de descubrimiento, Archyl admite definir tu modelo C4 -- sistemas, contenedores, componentes y relaciones -- en YAML que vive en tu repositorio. Tu diagrama de componentes se versiona, se revisa en pull requests y se renderiza automáticamente. Combinado con la detección de drift, esto te da documentación de nivel 3 con las características de mantenimiento del código.
Preguntas frecuentes
¿Cuál es la diferencia entre un diagrama de componentes C4 y un diagrama de componentes UML?
Un diagrama de componentes UML es una notación formal con interfaces provistas/requeridas, artefactos y estereotipos, centrada en modelar los componentes como unidades empaquetadas. Un diagrama de componentes C4 es el nivel 3 de la jerarquía de zoom de C4: una vista pragmática de cajas y flechas de los componentes dentro de un contenedor específico. C4 no tiene requisitos de notación formal -- su valor viene de la jerarquía coherente (sistema → contenedor → componente → código), no de los símbolos.
¿Es un componente lo mismo que una clase?
No. Un componente C4 es una agrupación cohesiva de código tras una interfaz bien definida -- puede implementarse como una clase, una docena de clases, un paquete o un módulo. Si tu diagrama de componentes tiene una caja por clase, has bajado un nivel de zoom de más.
¿Necesita cada contenedor un diagrama de componentes?
No, e intentar documentar cada contenedor en el nivel 3 es una de las formas más rápidas de abandonar C4. Crea diagramas de componentes solo para los contenedores que son complejos, compartidos entre equipos o centrales para el onboarding. Para el resto, el diagrama de contenedores más una estructura de carpetas legible es suficiente.
¿Cuántos componentes debe mostrar un diagrama de componentes?
Aproximadamente de 5 a 15. Con menos de 5, el diagrama probablemente no te está diciendo nada que el diagrama de contenedores no dijera ya. Con más de 20, o bien los límites de tus componentes son demasiado granulares, o el contenedor en sí debería dividirse.
¿Quieres diagramas de componentes que se mantengan precisos? Prueba Archyl gratis y genera un modelo C4 -- componentes incluidos -- a partir de tu base de código en minutos. O sigue leyendo: ¿Qué es el modelo C4? Guía completa | Guía del diagrama de Contenedores C4 | Guía del diagrama de Código C4 | Diagrama de Componentes en el glosario.