Tu diagrama de arquitectura miente: probé las dos formas de escribirlo como código

El diagrama de arquitectura de casi todo sistema en producción está desactualizado. No por descuido: porque vive en un PNG que alguien dibujó una vez, mientras el código siguió cambiando. Nadie abre una herramienta visual para mover una caja cuando mete un microservicio a las once de la noche.

Esta semana apareció en Habr un desarrollador ruso contando que se cansó de tener la arquitectura repartida en diez documentos y se construyó su propio editor C4. Fui a probarlo y me topé con la razón por la que este blog existe: es un servicio web cerrado, sin repositorio, sin opción de autoalojar. No hay nada que instalar, versionar ni medir. Así que probé lo que sí se puede.

El problema real

C4 propone documentar en cuatro niveles de zoom: contexto, contenedores, componentes y código. La idea es buena y tiene años. El problema nunca fue el modelo, sino dónde vive el diagrama.

Si vive en una herramienta visual, pasa esto:

• Se dibuja una vez, cuando el proyecto arranca.
• El código cambia. La imagen no.
• Nadie puede revisar el cambio de arquitectura, porque un PNG no tiene diff.
• A los ocho meses el diagrama es una pieza de arqueología que engaña a quien entra nuevo.

La alternativa es escribir el modelo como texto que vive en el repositorio, junto al código, y dejar que el diagrama se genere solo.

Camino 1: Structurizr

Structurizr es la herramienta canónica de “models as code” para C4: se define el modelo una vez en un DSL y de ahí salen todas las vistas. Empecé por la imagen de Docker.

docker run --rm -p 8080:8080 -v $(pwd)/workspace:/usr/local/structurizr structurizr/lite

Lo primero que apareció al arrancar fue un aviso, no el servidor:

Structurizr Lite will not receive any further updates - please migrate to the new consolidated tooling for new features, bug fixes, and security updates.

Structurizr Lite está descontinuado. Sin correcciones ni parches de seguridad. Buena parte de los tutoriales que aparecen al buscar siguen recomendando exactamente esa imagen. La sucesora es structurizr/structurizr local.

Las dos imágenes son pesadas: 402 MB la vieja y 725 MB la nueva, con 114 s y 141 s de descarga. En el VPS donde lo intenté primero, ya cargado con otros contenedores, se me fue el tiempo entre descargas y arranques de JVM. Ahí cometí un error de medición que vale la pena admitir: conté como “arranque” un tiempo que incluía volver a bajar la imagen porque yo mismo la había borrado antes. Repetí la prueba con la imagen ya en caché: el contenedor arranca y queda corriendo, pero el servidor web nunca llegó a responder en esa máquina. Culpo al VPS, no a la herramienta: 8 GB con media docena de contenedores encima peleando por la memoria.

La ruta buena: el CLI

Para generar diagramas no hace falta el servidor web. El CLI oficial hace el trabajo, y ahí los números cambian por completo. En una máquina con Java 21:

./structurizr.sh validate -workspace workspace.dsl
./structurizr.sh export -workspace workspace.dsl -format plantuml/c4plantuml -output ./out

Un segundo. Y el validate es exactamente el gate de validación del que hablo más abajo: si el modelo tiene una relación hacia algo que no existe, falla ahí y no llega al repositorio.

Aquí aparece lo que Structurizr da y una librería de macros no puede dar: un modelo en vez de tres dibujos. Escribí un sistema real (Agatha, que guarda archivos como video en YouTube) en un solo DSL de 66 líneas, declaré tres vistas al final, y de ahí salieron los tres niveles en una sola pasada de un segundo.

El contenedor core se declara una sola vez, con sus componentes adentro. La vista de contexto lo esconde, la de contenedores lo dibuja como caja cerrada y la de componentes lo abre. Si mañana renombro el códec BCH, cambia en las tres a la vez. Y si escribo una relación hacia un elemento que no existe, validate la caza antes del commit.

El archivo completo está aquí: workspace.dsl.

Camino 2: C4-PlantUML

C4-PlantUML es una librería de macros sobre PlantUML, no una aplicación que se instala. El modelo se escribe en texto y se renderiza contra cualquier servidor de PlantUML.

Escribí los mismos tres niveles de Agatha, esta vez como tres archivos separados, y los rendericé contra un servidor público. Los tres SVG salieron en segundos y no instalé nada. El costo aparece después, y no en el rendimiento.

Nivel 1 · Contexto

Quién usa el sistema y con qué habla. Sin detalles internos.

Nivel 2 · Contenedores

Las piezas desplegables y cómo se comunican.

Nivel 3 · Componentes

El interior del núcleo: por dónde pasa un archivo hasta volverse video.

Los tres archivos suman 68 líneas (contexto, contenedores, componentes). El DSL de Structurizr que produjo las tres vistas de arriba tiene 66. Prácticamente el mismo texto, y ahí está el punto: no se paga en líneas, se paga en duplicación. El componente Códec BCH aparece escrito una vez en el DSL y dos veces entre estos archivos, con su descripción copiada a mano. La tercera vez que alguien lo renombre en un solo archivo, los diagramas empiezan a contradecirse entre sí.

Los cuatro gates que se desbloquean

Estos cuatro no dependen de qué herramienta elijas, sino de que el modelo sea texto versionado.

1. Creación. El modelo vive junto al código. Se edita en el mismo editor, en la misma rama, en el mismo commit que el cambio que lo motivó. No hay que abrir otra aplicación ni acordarse después.

2. Revisión. Este es el grande. Un cambio de arquitectura se ve así en un pull request:

-    api -> postgres "consulta"
+    api -> cache "consulta"
+    cache -> postgres "si falla"

Tres líneas. Cualquiera en el equipo entiende qué cambió, quién lo hizo y cuándo, y puede aprobarlo o rechazarlo antes de que exista en el código. Un PNG no admite esa conversación; solo se acepta.

3. Validación. Si el modelo no parsea, el proceso falla. La documentación deja de ser algo que puede pudrirse en silencio y pasa a ser algo que se rompe ruidosamente, que es justo lo que uno quiere.

4. Una sola fuente de verdad. Este es el único gate donde las dos herramientas no empatan. Los tres diagramas de Structurizr salen del mismo archivo, así que renombrar un contenedor lo actualiza en todas las vistas. Con C4-PlantUML son tres ediciones manuales, y basta una distracción para que el nivel 3 diga algo que el nivel 2 ya no dice.

Mi opinión

Structurizr tiene el mejor modelo conceptual, y además es el camino serio para una empresa: defines el sistema una vez, las vistas se derivan solas y el validate te avisa si una relación apunta a algo que no existe. Usando el CLI en vez del servidor web, el costo desaparece: un segundo para exportar todo. Lo que sí molesta es que la variante más documentada esté descontinuada y que las imágenes de Docker pesen casi un gigabyte para lo que un JAR resuelve.

C4-PlantUML no tiene modelo unificado. Cada diagrama es un archivo y la consistencia entre niveles la sostienes tú, a mano. A cambio funciona de inmediato, se renderiza en segundos contra un servidor público, y el resultado se ve exactamente como el estándar C4 manda.

Conclusión: para un proyecto personal, C4-PlantUML y listo. Para una empresa, Structurizr con el CLI: un modelo único con validación automática es justo lo que evita que la documentación se contradiga a sí misma cuando la tocan diez personas. Lo que no haría en ningún caso es levantar el servidor web solo para generar imágenes.

Y sobre el editor visual que originó todo esto: puede ser excelente, pero no se puede autoalojar ni versionar, y eso lo deja fuera de la única propiedad que hace útil a la arquitectura como código.

Cuándo lo usaría

• En cualquier repositorio con más de dos servicios: el nivel de contenedores paga solo.
• Cuando entra gente nueva al equipo. Un diagrama que se genera del repositorio es un diagrama en el que se puede confiar.
• No lo usaría para una presentación bonita a dirección. Para eso, una herramienta visual gana.

---

Disparador: Cómo dejé de partir la arquitectura en diez documentos (Habr, en ruso).