System Design
Explica cómo representar componentes, responsabilidades, interfaces y dependencias para comunicar la estructura interna sin bajar al detalle de clases o infraestructura.
Un diagrama de componentes explica cómo se divide internamente una aplicación o servicio, qué responsabilidad tiene cada módulo y mediante qué interfaces colaboran.
El nivel de componentes se sitúa entre el contenedor desplegable y las clases concretas. Su propósito es mostrar unidades internas significativas, no cada archivo.
Sin límites internos claros, una aplicación puede convertirse en un bloque donde controllers, servicios, repositorios y workers dependen entre sí sin dirección. El diagrama hace visibles responsabilidades, dependencias y puntos de cambio.
Container: Order API
├─ HTTP Adapter
├─ Application Use Cases
├─ Order Domain
├─ Persistence Adapter
└─ Outbox PublisherCada componente debe poder describirse con una responsabilidad concreta y relaciones con propósito.
Una carpeta no se convierte automáticamente en componente.
C4Component
title Componentes internos de Order API
Container_Boundary(api, "Order API") {
Component(http, "Order HTTP Adapter", "HTTP", "Recibe comandos y transforma respuestas")
Component(app, "Order Use Cases", "Application", "Coordina creación y cancelación")
Component(domain, "Order Domain", "Domain", "Protege estados e invariantes")
Component(repo, "PostgreSQL Order Repository", "Adapter", "Persiste pedidos")
Component(outbox, "Outbox Publisher", "Worker", "Publica eventos confirmados")
}
ContainerDb(db, "PostgreSQL", "Database", "Pedidos y outbox")
Container_Ext(broker, "Broker", "Messaging", "Eventos de integración")
Rel(http, app, "Ejecuta casos")
Rel(app, domain, "Crea y modifica")
Rel(app, repo, "Carga y guarda")
Rel(repo, db, "SQL")
Rel(outbox, db, "Lee pendientes")
Rel(outbox, broker, "Publica")El diagrama no dice cómo se despliega la API ni en qué región; esas preguntas pertenecen a otras vistas.
Una relación debe indicar qué capacidad se usa, no solo una flecha. Ejemplo: “guarda pedidos mediante OrderRepository” comunica más que “depende de”.
Las dependencias deberían apuntar hacia contratos estables. Si el dominio importa directamente un SDK de pagos o un framework web, el detalle externo invade el núcleo.
Esto no obliga a utilizar una arquitectura específica; obliga a justificar dónde se encuentra el acoplamiento.
Dos componentes pueden ejecutarse dentro del mismo proceso. Separarlos conceptualmente no significa crear microservicios. La extracción remota debe justificarse por ownership, escalado, seguridad o ciclo de vida, no por el dibujo.
Si tiene muchas responsabilidades y dependencias, subdivídelo por capacidades coherentes.
Si cada archivo aparece como componente, el diagrama pierde utilidad.
Suele indicar límites mal definidos, eventos internos mal usados o responsabilidad compartida.
Un diagrama aspiracional debe marcarse como futuro; de lo contrario, engaña durante soporte y cambios.
Utils, Manager o Common.Para explicar internamente un contenedor, preparar refactorizaciones, revisar ownership o mostrar cómo se implementa una capacidad. Para el panorama general usa C4 Context o Container; para orden temporal usa Sequence.
Diagramas C4 organiza contexto, contenedores, componentes y código en niveles coherentes.