Diagrama C4

Arquitectura de software por niveles.

Definición

El diagrama C4 dibuja una arquitectura de software en un único nivel de zoom: cada caja lleva su tipo —persona, sistema, contenedor, almacén, componente— con silueta propia y su tecnología debajo, y un límite marca qué es del sistema y qué es externo. Se lee siguiendo las flechas y buscando la llamada que cruza el límite sin pasar por la puerta prevista. Sirve para documentar y revisar arquitecturas.

Editar con tus datos SVG Spec JSON

La app pide cupo al PMS por fuera de la única API que lo cachea

Datos: category · label · group · source · target · x · y · series · order
Buena para: Enseñar qué piezas tiene un sistema, con qué están hechas y quién llama a quién.
Evítala cuando: Cuando quieres mezclar niveles, por ejemplo contenedores y componentes, en la misma lámina: la pieza falla.
Se lee bien: Entre 2 y 12 elementos; dibuja hasta 21
Datos que faltan: Se niega a dibujar y dice qué valor falta.
Accesibilidad: Lector de pantalla: tabla de datos · respeta «reducir movimiento»

Forma de los datos

Qué columnas pide

Columna	Tipo	Para qué
`category`	string	El tipo C4 de la fila, y lo único que distingue las DOS clases de fila de esta tabla: los seis tipos de elemento («persona», «sistema», «contenedor», «almacen», «componente», «codigo») o la palabra «relacion» si la fila es una flecha. Un tipo desconocido FALLA con la lista. Y es además lo que DERIVA el nivel de la lámina: mezclar un contenedor con un componente falla nombrando las dos filas.
`label`	string	El nombre del elemento, que es además su CLAVE: es lo que las relaciones escriben en «Desde» y «Hasta». Dos elementos con el mismo nombre fallan. En una fila de relación es el rótulo de la flecha —qué viaja por ella—, y ahí se admite también en «Descripcion», pero nunca en las dos a la vez.
`group` · opcional	string	El límite al que pertenece el elemento. Vacío = fuera de todo límite, o sea EXTERNO, y entonces la caja lo dice en su sello. OPCIONAL: sin ningún límite declarado la lámina dibuja el grafo sin marco y sin la palabra «externo», porque sin frontera no hay dentro ni fuera que afirmar. Un límite tiene que ser un bloque rectangular completo de la rejilla: si dentro de su rectángulo cae algo que no es suyo, falla nombrando a los dos.
`source` · opcional	string	El nombre del elemento del que sale la flecha. Sólo se lee en las filas de tipo «relacion», y ahí es obligatorio.
`target` · opcional	string	El nombre del elemento al que entra la flecha. Sólo se lee en las filas de tipo «relacion», y ahí es obligatorio.
`x` · opcional	number	La columna lógica del elemento, entero ≥ 0. OPCIONAL: sin ella la coloca la retícula compartida del kit. Va EN PAREJA con «Fila»: media coordenada falla, porque declarar sólo una planta el elemento encima de otro sin que nada lo diga.
`y` · opcional	number	La fila lógica del elemento, entero ≥ 0. OPCIONAL y en pareja con «Columna».
`series` · opcional	string	La tecnología del elemento («Node 20 · Fastify») o el protocolo de la relación («JSON/HTTPS»). Se pinta entre corchetes, en cuerpo menudo, bajo el nombre. OPCIONAL, y es lo SEGUNDO que cede cuando el lienzo no da: después de la descripción y antes de tocar el nombre, que es lo único que identifica la caja. Es el rol canónico más cercano —el vocabulario no tiene una palabra para «con qué está hecho»— y por eso lleva esta nota.
`order` · opcional	string	Una línea de qué hace el elemento, bajo su ficha técnica. OPCIONAL, y es lo PRIMERO que cede cuando el lienzo no da: la pieza baja su techo de líneas —2, 1, 0—, después suelta la tecnología y sólo entonces toca el nombre. Es el rol canónico más cercano; el vocabulario no tiene «detalle».

Tamaños

Ancha por necesidad

Esta pieza necesita anchura para que cada rótulo quepa entero. El motor prefiere decirlo a apretarla.

A menos de 480 px sus rótulos no caben sin pisarse o recortarse, y el motor no la publica así. En el móvil se ve la versión ancha, a tamaño legible y sin recortar, dentro de un marco que se desliza.

Cuándo usarla

Tres preguntas antes de elegirla

¿Hablas de piezas de software?

Si el modelo es de datos —tablas, claves, cardinalidades—, usa el diagrama entidad-relación.

Sí: quédate con diagrama c4

No: usa Diagrama entidad-relación

¿Importa la estructura, no el orden de los mensajes?

Si hay que explicar quién habla con quién y en qué orden, el diagrama de secuencia lo dibuja.

Sí: quédate con diagrama c4

No: usa Diagrama de secuencia

¿Las piezas se conectan entre sí con flechas?

Si la arquitectura se explica como niveles que se apoyan unos en otros, las capas apiladas bastan.

Sí: quédate con diagrama c4

No: usa Capas apiladas

Código

La misma pieza, con tus datos

import { getPreset, renderComposition } from 'visx-render/node';

const spec = await getPreset('concept-c4');
spec.data.rows = misFilas; // category, label
const { svg, warnings } = await renderComposition(spec);

También en React con Chart y prepareComposition. Guía para desarrolladores →

Dudas

¿Por qué falla si mezclo contenedores y componentes?

Porque el nivel de la lámina sale de los tipos que declaras, y mezclar dos niveles hace el mapa ilegible. La pieza nombra las dos filas que chocan.

¿Y si no declaro ningún límite?

Dibuja el grafo sin marco y sin la palabra «externo»: sin frontera no hay dentro ni fuera que afirmar.

¿Una flecha más larga significa más tráfico?

No. Todas las cajas miden lo mismo y la longitud de una flecha sólo depende de la colocación.

¿Qué hace si faltan datos?

Se niega a dibujar y dice qué valor falta.

¿Cómo se ve en el móvil?

A menos de 480 px el motor no la compone sin pisar o cortar rótulos, y lo dice. En el móvil se ve la versión ancha, a tamaño legible, dentro de un marco que se desliza.

Relacionadas

Otras formas de responder «cómo funciona algo»

Guía para elegir: cómo funciona algo →