Diagramas como código y cómo mantener la documentación al día

Qué significa diagramas como código

Diagramas como código significa escribir un diagrama como un archivo de texto breve en un lenguaje pequeño y dejar que una herramienta lo organice y lo dibuje. En lugar de arrastrar cajas sobre un lienzo, escribes ordering -> db: SQL y la herramienta produce la imagen. El archivo de texto vive en el repositorio de código y se trata como código: se versiona, se revisa, lo comprueban las compilaciones automáticas y lo publica el pipeline.

Es una parte de la documentación como código (docs as code), la práctica, promovida por la comunidad Write the Docs, de producir documentación con las mismas herramientas y el mismo flujo de trabajo que el software: gestores de incidencias, control de versiones (normalmente Git), lenguajes de marcado de texto plano como Markdown o AsciiDoc, revisión de código y pruebas automáticas. Las secciones anteriores produjeron el material: vistas y diagramas C4, UML donde importa la precisión, ADR y una estructura arc42. Esta sección trata de mantener ese material exacto durante toda la vida del sistema, que es donde fracasa la mayor parte de la documentación de arquitectura. Las razones de ese fracaso se expusieron en por qué y cuánto documentar: wikis desactualizadas, grandes documentos sin responsable y diagramas que ya no coinciden con el sistema.

Por qué poner los diagramas en texto

Control de versiones. Un diagrama en texto tiene historial. Puedes ver quién lo cambió, cuándo y por qué, y comparar dos versiones cualesquiera línea a línea; una imagen binaria o un archivo en el formato de una herramienta de dibujo solo muestra que algo cambió. También puedes crear ramas: el diagrama de un cambio propuesto vive en la misma rama que el código que lo implementa.

Revisión en pull requests. Cuando un desarrollador añade una nueva dependencia entre servicios, el cambio en el diagrama aparece en el mismo pull request que el código, como una diferencia de texto legible. Los revisores pueden preguntar si esa nueva flecha es deseada, lo que supone una revisión de arquitectura en el momento en que resulta más barata.

Coherencia. La herramienta aplica las mismas formas, fuentes y reglas de disposición a todos los diagramas, de modo que los diagramas dibujados por veinte personas siguen pareciendo un solo conjunto. Con un lenguaje de modelado (más adelante), el mismo elemento aparece con el mismo nombre y la misma descripción en todas las vistas.

Generación. El texto puede producirse con programas. Los diagramas pueden generarse a partir del propio código (grafos de dependencias), de la infraestructura como código (diagramas de despliegue), de las especificaciones de API o de un modelo central, y luego comprobarse automáticamente con el sistema.

Los compromisos son reales. La disposición automática es cómoda, pero a veces fea, y pelearse con un motor de disposición para colocar una caja puede llevar más tiempo que dibujarla; la mayoría de las herramientas ofrecen indicaciones como la dirección o la agrupación, no posiciones exactas. Los lenguajes de texto tienen una curva de aprendizaje para quienes no programan, como los responsables de producto. Y un buen boceto en una pizarra durante una discusión de diseño sigue siendo la forma más rápida de pensar; los diagramas como código son para los diagramas que piensas conservar.

Cuatro lenguajes, un ejemplo

Cuatro lenguajes dominan el panorama. Cada ejemplo de abajo describe una parte de la misma plataforma de reparto de comida.

PlantUML, creado por Arnaud Roques y lanzado por primera vez en 2009, es el más antiguo de los cuatro. Cubre todos los diagramas UML habituales (de secuencia, de componentes, de despliegue, de estados, de actividades, de clases) y muchos otros, y usa Graphviz para organizar la mayoría de los tipos de diagrama. La biblioteca C4-PlantUML añade las formas de C4. Sus diagramas de secuencia son especialmente buenos, lo que lo convierte en una opción natural para los escenarios de ejecución de Lo esencial de UML.

@startuml
title Place an order (happy path)
actor Customer
participant "Customer app" as App
participant "Ordering service" as Ord
participant "Payment provider" as Pay
queue "Order events topic" as MB

Customer -> App : Tap "Pay"
App -> Ord : POST /orders (HTTPS)
Ord -> Pay : Authorise payment
Pay --> Ord : Authorised
Ord ->> MB : OrderPlaced (async)
Ord --> App : 201 Created
@enduml

Mermaid, creado por Knut Sveidqvist en 2014, está escrito en JavaScript y se renderiza en el navegador. Su mayor ventaja es su alcance: GitHub renderiza los bloques de Mermaid de los archivos Markdown desde febrero de 2022, y GitLab y muchas herramientas de wiki y de toma de notas hacen lo mismo, así que un diagrama en un README no necesita ningún paso de compilación. Admite diagramas de flujo, de secuencia, de clases, de estados y de entidad-relación, entre otros, y tiene soporte experimental para C4. Su control de la disposición es limitado en los diagramas grandes.

flowchart LR
    app["Customer app<br/>Kotlin, Swift"]
    gw["API gateway"]
    ord["Ordering service<br/>Java"]
    db[("Order database<br/>PostgreSQL")]
    topic[["Order events<br/>Kafka topic"]]
    disp["Dispatch service<br/>Go"]
    notif["Notification service<br/>Node.js"]

    app -->|HTTPS/JSON| gw
    gw -->|HTTPS/JSON| ord
    ord -->|SQL| db
    ord -->|publishes OrderPlaced| topic
    disp -->|consumes| topic
    notif -->|consumes| topic

Structurizr DSL, creado por Simon Brown junto con el modelo C4, es de otra naturaleza. No describe un diagrama; describe un modelo (personas, sistemas de software, contenedores, componentes y las relaciones entre ellos) y después define vistas de ese modelo. Cada elemento se define una sola vez, con su nombre, su descripción y su tecnología, y aparece en todas las vistas que lo incluyen. Las relaciones entre contenedores se deducen automáticamente en el nivel del sistema, así que la vista de contexto no necesita flechas aparte. El DSL también puede adjuntar documentación en Markdown y una carpeta de ADR al workspace, y sus herramientas pueden exportar las vistas a PlantUML, Mermaid, D2 y otros formatos.

workspace "Food delivery" {
    model {
        customer = person "Customer" "Orders food from local restaurants."
        payments = softwareSystem "Payment provider" "Takes card payments." "External"
        platform = softwareSystem "Food-delivery platform" {
            app = container "Customer app" "Ordering and tracking." "Kotlin, Swift"
            gateway = container "API gateway" "Authenticates and routes requests." "Managed API gateway"
            ordering = container "Ordering service" "Accepts and tracks orders." "Java"
            db = container "Order database" "Orders and their states." "PostgreSQL" "Database"
            orderEvents = container "Order events" "Order lifecycle events." "Kafka topic" "Topic"
            dispatch = container "Dispatch service" "Assigns couriers." "Go"
        }
        customer -> app "Places and tracks orders using"
        app -> gateway "Makes API calls to" "JSON/HTTPS"
        gateway -> ordering "Routes requests to" "JSON/HTTPS"
        ordering -> db "Reads from and writes to" "SQL/TCP"
        ordering -> payments "Takes card payments using" "JSON/HTTPS"
        ordering -> orderEvents "Publishes order events to" "Kafka"
        dispatch -> orderEvents "Consumes order events from" "Kafka"
    }
    views {
        systemContext platform "Context" {
            include *
            autoLayout lr
        }
        container platform "Containers" {
            include *
            autoLayout lr
        }
        styles {
            element "Database" {
                shape cylinder
            }
            element "Topic" {
                shape pipe
            }
        }
    }
}

D2 (Declarative Diagramming), cuyo código abrió Terrastruct en 2022, es el más reciente. Busca un resultado limpio y moderno y una sintaxis legible, admite contenedores anidados (escritos con llaves y referenciados con nombres separados por puntos) y ofrece varios motores de disposición a elegir: dagre y ELK vienen incluidos y son gratuitos, y TALA, diseñado para diagramas de arquitectura de software, es un motor comercial aparte.

direction: right

customer: Customer {shape: person}
payments: Payment provider

platform: Food-delivery platform {
  app: Customer app
  ordering: Ordering service
  db: Order database {shape: cylinder}
  events: Order events topic {shape: queue}
  dispatch: Dispatch service

  app -> ordering: Places order (HTTPS)
  ordering -> db: SQL
  ordering -> events: Publishes OrderPlaced
  dispatch -> events: Consumes OrderPlaced
}

customer -> platform.app: Places orders using
platform.ordering -> payments: Authorise (HTTPS)

Herramientas de dibujo y herramientas de modelado

La diferencia entre Structurizr y los otros tres es un caso de la distinción entre herramientas de dibujo y de modelado presentada en la Sección 4.3. Una herramienta de dibujo (diagrams.net, Excalidraw, Visio, una pizarra en línea, y también PlantUML, Mermaid y D2) conoce formas, líneas y texto. Una caja con la etiqueta Servicio de pedidos en un diagrama no tiene ninguna conexión con la caja que lleva la misma etiqueta en otro. Si renombras el servicio, tienes que buscar y corregir a mano cada diagrama; si lo escribes mal una vez, tienes, hasta donde sabe la herramienta, dos servicios.

Una herramienta de modelado (Structurizr, Archi para modelos ArchiMate, Sparx Enterprise Architect para UML y SysML, Capella) mantiene un modelo: un repositorio de elementos y relaciones con propiedades. Los diagramas son vistas del modelo. Si renombras un elemento, cambian todas las vistas. El modelo puede consultarse (¿qué contenedores dependen del intermediario de mensajes?), comprobarse (ningún componente de la app del cliente puede llamar a la base de datos) y compararse con el sistema en ejecución. El precio es más estructura por adelantado y, con las herramientas comerciales pesadas, licencias, formación y una tendencia a modelar mucho más de lo que nadie lee.

Una regla práctica: usa herramientas de dibujo, de texto o gráficas, para bocetos, explicaciones puntuales y diagramas que se sostienen por sí solos, como un único diagrama de secuencia en un ADR. Usa un modelo cuando los mismos elementos aparezcan en muchos diagramas, cuando contribuyan varios equipos o cuando quieras comprobar la documentación con el código. Muchos equipos combinan ambos: un modelo de Structurizr para la estructura C4 y PlantUML o Mermaid para unos pocos diagramas de secuencia y de estados.

Generar la documentación en el pipeline

Una vez que la documentación es texto en el repositorio, el pipeline de integración continua del Capítulo 0 puede compilarla y comprobarla como si fuera código. Un pipeline típico renderiza todos los diagramas (y hace fallar la compilación ante un error de sintaxis), comprueba los enlaces, genera un sitio de documentación estático con un generador como MkDocs, Antora o Docusaurus, y lo publica cuando los cambios llegan a la rama principal. Así, los lectores siempre ven la documentación que coincide con el código de main, y nadie tiene que acordarse de exportar una imagen y subirla a una wiki.

Se pueden añadir más comprobaciones a medida que el equipo madura: un corrector ortográfico y un linter de estilo de redacción (Vale es popular), una comprobación de que cada ADR tiene un estado válido, un aviso cuando la fecha de última revisión de una página es más antigua que su intervalo de revisión, y comprobaciones de arquitectura que comparan las dependencias documentadas con las reales del código, que son una forma de función de aptitud (fitness function). Algunos equipos generan partes de la documentación a partir del propio sistema: grafos de dependencias a partir de la compilación, la referencia de la API a partir de las especificaciones OpenAPI, diagramas de despliegue a partir de la infraestructura como código.

name: architecture-docs
on:
  pull_request:
    paths: ["docs/**"]
  push:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # assumes plantuml, d2, lychee and mkdocs are available on the runner
      - name: Render diagrams (fails on syntax errors)
        run: |
          plantuml -tsvg docs/diagrams/*.puml
          for f in docs/diagrams/*.d2; do d2 "$f" "${f%.d2}.svg"; done
      - name: Check links
        run: lychee --offline docs/
      - name: Build site (warnings such as broken links fail the build)
        run: mkdocs build --strict
      - name: Publish
        if: github.ref == 'refs/heads/main'
        run: ./scripts/publish-docs.sh

Mantener la documentación al día

Las herramientas no mantienen la documentación fiel a la realidad; los hábitos sí. Cinco hábitos marcan la diferencia.

Responsabilidad. Cada documento tiene un responsable con nombre, normalmente el equipo dueño del código que describe. En GitHub y GitLab, un archivo CODEOWNERS puede convertir a ese equipo en revisor obligatorio de los cambios bajo su carpeta docs/. Los documentos que son de todos no los mantiene nadie.

Revisión con los cambios de código. Una plantilla de pull request que pregunta ¿Cambia esto una interfaz, una dependencia, un despliegue o una decisión? Si es así, ¿qué documento o ADR has actualizado? detecta la mayor parte de la deriva en el momento en que se produce. Algunos equipos van más allá y bloquean la fusión de funcionalidades que carecen de documentación, una práctica que menciona la guía de Write the Docs.

Fechas de última revisión. Un pequeño encabezado en cada página registra su responsable, la fecha en que se comprobó por última vez con la realidad y cada cuánto debe revisarse. Los lectores pueden juzgar hasta qué punto fiarse de ella, y el pipeline puede señalar las páginas con la revisión vencida. Una página que dice última revisión: 2023 es honesta; una página que describe en silencio el sistema de 2023 es una trampa.

Enlazar documentación y código. Las páginas apuntan al código que describen (rutas, módulos), los comentarios del código apuntan a los ADR y los mensajes de commit citan los registros que implementan. Los enlaces en ambas direcciones dejan claro a qué documentos podría afectar un cambio.

Eliminar el material obsoleto. Una documentación errónea es peor que ninguna, porque los lectores actúan según ella. Cuando una página ya no describe el sistema y nadie va a corregirla, elimínala o muévela a un archivo histórico claramente señalado. Los ADR son la excepción: son registros de la historia, así que se reemplazan o se declaran obsoletos, no se eliminan. Esta es la idea de la documentación viva que Cyrille Martraire desarrolló en su libro de 2019 con ese título: una documentación que evoluciona al mismo ritmo que el sistema, idealmente porque gran parte de ella se deriva del propio sistema.

---
title: "Ordering service: building block view (level 2)"
owner: "@ordering-team"
last_reviewed: 2026-09-14
review_every: 6 months
code: src/ordering/
decisions: [ADR-0007, ADR-0012]
---