Structurizr está diseñado para ayudar al modelado con C4 model, cuyo objetivo es la visualización de la arquitectura de nuestro software desde distintos puntos de vista usando un modelo único.
Structurizr para generar diagramas de arquitectura con C4 model
0. Índice de contenidos.
- 1. Introducción.
- 2. Entorno.
- 3. Structurizr DSL: definir modelos, no pintar diagramas.
- 4. Structurizr Lite.
- 5. Structurizr Markdown/AsciiDoc.
- 6. Structurizr ADRs.
- 7. Referencias.
- 8. Conclusiones.
1. Introducción.
Structurizr se basa en la idea de diagramas como código pero separando el modelo de sus formas de visualización. Esto permite crear múltiples diagramas de arquitectura de software a partir de un único modelo.
Su creador es Simon Brown, el también autor de C4 model. Quién pone a disposición de la comunidad una serie de de herramientas para la creación de espacios de trabajo compatibles con Structurizr usando el lenguaje de DSL de Structurizr, bautizándolo como «Diagrams as Code 2.0».
En el siguiente ejemplo Structurizr DSL crea dos diagramas, basado en un único conjunto de elementos y relaciones.
Podéis comprobar cómo por un lado se define el modelo y sus relaciones y, por otro, lado las posibles visualizaciones del mismo, en este caso las dos primeras «C»: system context y container.
Los diagramas que se generan partiendo de la definición de vista son interactivos (por ejemplo, zoom in / out), «incrustables» a través de iframe, e incluyen una clave del diagrama generado automáticamente a modo de leyenda, para entender qué significa cada elemento gráfico del mismo.
Adicionalmente, con Structurizr podemos generar también nuestra documentación en formato Markdown o AsciiDoc e incluir ADRs (Architecture Decision Records) integrados en la documentación.
2. Entorno.
El tutorial está escrito usando el siguiente entorno:
- Hardware: Portátil MacBook Pro 16′ (Apple M1 Pro, 32GB DDR4).
- Sistema Operativo: Mac OS Ventura 13
3. Structurizr DSL: definir modelos, no pintar diagramas
Al escribir código fuente, a menudo hablamos de DRY (Don’t repeat yourself), donde tratamos de evitar la duplicación innecesaria a través de copiar y pegar código. Esa es exactamente la forma en que muchas personas crean sus propios diagramas, copiando y pegando fragmentos de definición de diagramas, lo que los hace prácticamente in-mantenibles.
Structurizr DSL es un proyecto de código abierto que te permite crear un modelo único de nuestra arquitectura de software, y luego visualizarlo desde diferentes ángulos y profundidades, siguiendo el modelo de C4.
La mejor manera de empezar a probarlo es a través de la página que se proporciona donde podemos empezar desde cero o cargar algunos de los ejemplos que proporciona el propio autor:
- https://structurizr.com/dsl?example=getting-started
- https://structurizr.com/dsl?src=https://raw.githubusercontent.com/structurizr/examples/main/dsl/financial-risk-system/workspace.dsl
- https://structurizr.com/dsl?src=https://gist.githubusercontent.com/simonbrowndotje/…
- https://structurizr.com/dsl?example=amazon-web-services
En la parte izquierda vemos el código del espacio de trabajo, los distintos componentes del modelo: personas y sistemas de software y sus relaciones; junto con la definición de vistas y estilos de los mismos componentes.
El diagrama se genera automáticamente en base al código del espacio de trabajo a la derecha y permite hacer zoom en los distintos sistemas de software y contenedores a través de una lupa en los mismos o el desplegable de la parte superior.
Existen distintas posibilidades de exportación del diagrama, tanto en formato binario como en código.
Structurizr graph
Se trata de un gráfico de dependencias interactivo donde puedes analizar que dependencias arrastra un componente, literalmente, porque puedes interactuar con los nodos del grafo.
PlantUML
Se puede exportar el gráfico directamente a PlantUML
C4 PlantUML
Se puede exportar el gráfico a la sintaxis de C4 para PlantUML
Mermaid
Se puede exportar el gráfico a la sintaxis de C4 para Mermaid
Ilograph
Se puede exportar el gráfico a la sintaxis de Ilograph que permite un modo de visualización de todo el sistema en profundidad, como se puede ver a continuación.
4. Structurizr Lite.
Más allá de la generación y visualización online de los diagramas a través de la página de pruebas, existen las siguientes posibilidades para usar Structurizr:
- disponer de tu propio workspace gratuito online, previo registro, el espacio es limitado y solo te permite disponer de un workspace,
- pagar una licencia por el servicio cloud en los servidores propios del fabricante, para tener workspaces ilimitados y despreocuparte por las actualizaciones de la herramienta, con un espacio de almacenamiento superior que la opción gratuita,
- realizar una instalación de la herramienta on premise tanto en cloud como en tus propios servidores de forma gratuita también o con soporte del fabricante bajo licenciamiento
- con las tres opciones anteriores podemos usar una cli para subir el código de nuestros workspaces a la herramienta online; y con la misma cli exportar diagramas a los formatos antes vistos
- la última opción y más sencilla para probar en local la herramienta es Structurizr Lite, que nos permite disponer de un workspace local muy fácilmente:
Para hacer uso de Structurizr Lite en nuestro entorno local podemos levantar un contenedor docker haciendo uso de un fichero de docker-compose como el siguiente:
version: '3.7'
services:
structurizr:
image: structurizr/lite:latest
ports:
- "8080:8080"
volumes:
- "./workspace:/usr/local/structurizr"
Bajo el mismo directorio donde ubiquemos el docker-compose.yml crearemos un directorio workspace para montar un volumen y dentro del directorio crearemos un fichero workspace.dsl.
Dentro del fichero dsl podemos empezar a probar a modelar nuestro sistema de software y crear las visualizaciones; accediendo a través del navegador a http://localhost:8080 tendremos una vista como la siguiente:
5. Structurizr Markdown/AsciiDoc.
Usando Structurizr Lite podemos crear también nuestra propia documentación de arquitectura en formato markdown o asciidoc para incluirla dentro del modelo y mostrarla junto con los diagramas, pudiendo incrustar, así mismo, las visualizaciones dinámicas de los diagramas en la propia documentación.
Para ello, no tenemos más que crear un directorio de docs e ir incluyendo los ficheros de markdown para que sean visibles automáticamente dentro de la herramienta.
Para hacer referencia dentro del modelo a la documentación podemos añadir lo siguiente:
financialRiskSystem = softwareSystem "Financial Risk System" "Calculates the bank's exposure to risk for product X." "Financial Risk System" {
!docs docs
}
6. Structurizr ADRs.
Structurizr Lite nos permite además incluir ADRs (Architecture Decision Records) dentro de la propia documentación, generando también un modo de visualización ad hoc para los mismos.
Al igual que para la documentación, basta con crear un directorio de decisions y dentro del mismo ir incluyendo los ficheros de markdown de las ADRs, con un formato
compatible con adr-tools o creados con dicha herramienta.
# 1. Record architecture decisions
Date: 2023-05-06
## Status
Accepted
## Context
We need to record the architectural decisions made on this project.
## Decision
We will use Architecture Decision Records, as described by Michael Nygard in this article: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
## Consequences
See Michael Nygard's article, linked above.
Para hacer referencia dentro del modelo a los ADRs podemos también añadir lo siguiente:
financialRiskSystem = softwareSystem "Financial Risk System" "Calculates the bank's exposure to risk for product X." "Financial Risk System" {
!docs docs
!adrs decisions
}
Se mostrarán de la siguiente forma:
Esta es la estructura de directorios y los ficheros que hemos ido generando para probar (el fichero de workspace.json lo ha generado la herramienta automáticamente).
7. Referencias.
- https://structurizr.com/
- https://structurizr.com/dsl?example=big-bank-plc
- https://dev.to/simonbrown/getting-started-with-the-structurizr-dsl-34dh
- https://dev.to/simonbrown/getting-started-with-structurizr-lite-27d0
- https://dev.to/simonbrown/visualising-adrs-3klm
- https://dev.to/simonbrown/diagramming-distributed-architectures-with-the-c4-model-51cm
8. Conclusiones.
Una gran herramienta para C4 model, qué mejor herramienta que la de su propio creador, ¿no?
Ahora sólo hace falta analizar las posibilidades de generar el código de los diagramas en base al código fuente, integrarlo en los pipelines de construcción,… en definitiva, sólo hace falta indistrualizarlo 😉
Stay tuned!
