Arquitectura viva: C4 + flujos reproducibles

Qué es

Una página por proyecto que muestra cómo fluye la información: qué piezas existen, en qué máquina corre cada una y por dónde pasa una petición o un archivo. Tiene dos ideas detrás. La primera es el diagrama de contenedores del modelo C4: cada caja es algo que se despliega por separado (un proceso, una base de datos, un script programado, el navegador de quien visita) y cada línea es una llamada real, con su protocolo y lo que viaja por ella. La segunda es el flujo reproducible: un caso de uso escrito como una secuencia de esas llamadas, que la página anima paso a paso sobre el mismo diagrama.

Por qué un flujo enseña más que un diagrama estático

Un diagrama de cajas y flechas dice qué está conectado con qué, pero no en qué orden ni para qué. Quien lo lee tiene que reconstruir la historia en su cabeza, y casi siempre la reconstruye mal. Un flujo la cuenta: entra algo, pasa por estas piezas en este orden, sale un resultado y queda un rastro (un archivo, un log, un commit). Al reproducirlo, la llamada que cumple cada paso se enciende y el resto se apaga, así que se ve de una vez qué partes del sistema participan en ese caso y cuáles no.

Cómo se lee una página

1. Contenedores. Actores a la izquierda, almacenes y servicios externos a la derecha. El color dice de quién es la pieza: propia del proyecto, propia pero de otro repo, o externa. Una caja con borde punteado existe fuera del proyecto. Un clic en una caja muestra qué hace, en qué máquina corre y sus entradas y salidas.
2. Reproducir flujo. Los botones sobre el diagrama animan cada caso de uso. A la derecha aparecen los pasos numerados; el que está activo corresponde a la llamada encendida.
3. Las demás pestañas existen solo si aportan: secuencias UML, datos (entidad-relación o estructura de carpetas), despliegue (hoy y al escalar) y decisiones con la alternativa descartada.

La regla que la hace confiable

Cada llamada del diagrama corresponde a código que se puede señalar: un archivo y una función. Lo que no está en el código no se dibuja; se anota como “por confirmar” en las notas del proyecto. Antes de publicarse, un script verifica que cada flujo use solo llamadas que existen, que cada llamada una cajas que existen y que los conteos coincidan con el manifiesto, y audita la página en busca de datos personales: un solo hallazgo detiene la publicación.

Ejemplo real

La arquitectura de esta misma Landing tiene diez contenedores y tres flujos. “Una tarea delegada a la Mac y su merge” recorre seis llamadas: el PC manda la tarea por ssh, la Mac crea un worktree limpio desde GitHub, corre las pruebas y devuelve una rama, el PC la revisa y fusiona, y el push dispara el build. En un diagrama estático esas seis flechas parecen un enredo; reproducido, es una historia de seis pasos.

Error típico

Dibujar la arquitectura que uno quisiera tener y no la que el código implementa. La señal es una flecha que nadie sabe en qué archivo vive. La otra cara del mismo error es llenar todas las pestañas aunque no apliquen: un sitio estático no tiene núcleo hexagonal ni modelo entidad-relación, y fingirlos solo agrega ruido.

Para saber más

• El modelo C4 (Simon Brown): https://c4model.com
• Índice de arquitecturas