Uma das tarefas mais complicadas (e chatas) de documentação de um sistema é a criação de fluxogramas e diagramas. Arrastar manualmente caixinhas e setas é maçante, além de não ter nenhuma possibilidade de automação.

Neste artigo vou comentar sobre Diagrams, uma biblioteca utilizadas para criar diagramas via código, o que pode facilitar e acelerar muito esta tarefa.

A Importância da Documentação Visual

Antes de mergulhar nas especificidades dos bibliotecas apresentadas, é essencial entender por que a documentação visual é tão crítica.

Os sistemas de software são inerentemente complexos, geralmente envolvendo vários componentes, serviços, bancos de dados e redes que interagem de maneiras intrincadas. A documentação baseada em texto, embora necessária, geralmente falha em capturar a imagem completa ou transmitir os relacionamentos entre diferentes partes de um sistema de forma eficaz.

Diagramas visuais, por outro lado, podem fornecer uma visão geral clara, destacar dependências e facilitar para as partes interessadas em todos os níveis entender a arquitetura, os fluxos de trabalho e os processos envolvidos.

Os diagramas podem servir a vários propósitos, como:

• Diagramas de arquitetura: ilustram o design de alto nível de um sistema, mostrando componentes, serviços e suas interações.
• Diagramas de fluxo de trabalho: representam o fluxo de dados ou processos dentro de um sistema, facilitando a compreensão de como diferentes partes funcionam juntas.
• Diagramas de entidade-relacionamento (ERDs): visualizam esquemas de banco de dados, mostrando tabelas, campos e relacionamentos entre entidades.
• Diagramas de rede: mapeie a topologia física ou lógica de uma rede, destacando conexões entre servidores, roteadores e outros dispositivos.

Considerando esses diversos casos de uso, fica claro que a documentação visual é uma ferramenta indispensável para desenvolvedores, arquitetos e outras partes interessadas. No entanto, criar e manter esses diagramas pode ser desafiador sem as ferramentas certas.

Biblioteca Diagrams

Visão geral

A biblioteca Diagrams é uma ferramenta Python de código aberto projetada para criar diagramas de infraestrutura programaticamente. Introduzido pela Mingrammer, o Diagrams visa ajudar os desenvolvedores a visualizar arquiteturas de nuvem, sistemas locais e outras configurações complexas de infraestrutura. A biblioteca aproveita o Graphviz, uma poderosa ferramenta de visualização de gráficos, para gerar os diagramas. Ao usar o código Python, os desenvolvedores podem definir e renderizar diagramas, facilitando a integração da geração de diagramas em seus fluxos de trabalho existentes.

Recursos

A biblioteca Diagrams é particularmente adequada para criar diagramas de infraestrutura. Alguns de seus principais recursos incluem:

• Ampla gama de provedores suportados - o Diagrams suporta uma vasta gama de provedores de nuvem, incluindo AWS, Azure, GCP, Kubernetes e muito mais. Isso torna possível criar diagramas detalhados de infraestrutura de nuvem com o mínimo de esforço.
• Nós e arestas personalizáveis - os usuários podem personalizar a aparência de nós e arestas, permitindo um controle refinado sobre a apresentação visual dos diagramas.
• Abordagem programática - sendo uma biblioteca Python, diagramas podem ser gerados dinamicamente com base no código. Isso é particularmente útil para gerar diagramas atualizados como parte de pipelines de CI/CD.
• Integração com outras ferramentas - Diagrams podem ser integrados com outras ferramentas Python, permitindo automação e dimensionamento em projetos complexos.

Exemplo 1

Existem alguns passos de configuração antes de usar a biblioteca.

1. Instalar o Python, no mínimo a versão 3.10
2. Faça o download do Graphviz do site oficial. Eu prefiro baixar o pacote ZIP e adicionar o caminho ao PATH manualmente, mas também existe o pacote EXE para instalação automática.
3. Em um terminal Python, execute o comando pip install diagrams para instalar a biblioteca.

Aqui está um exemplo simples de como criar um diagrama de arquitetura de nuvem usando Diagrams:

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

with Diagram("Simple Web Service Architecture", show=False):
    ELB("Load Balancer") >> EC2("Web Server") >> RDS("Database")

Salve o trecho acima em um arquivo test_diagram.py por exemplo. Para gerar o gráfico, basta executar o comando python test_diagram.py, e uma imagem será gerada no mesmo diretório do script.

O gráfico gerado será parecido com o seguinte:

Exemplo 2

Neste exemplo maior, combinaremos algumas técnicas de modularização, tanto criação de arestas como segregação de nós em grupos baseados na afinidade:

from diagrams import Diagram, Edge, Cluster
from diagrams.azure.compute import VMLinux
from diagrams.azure.analytics import EventHubs

from diagrams.onprem.client import Client
from diagrams.programming.framework import React

REST_EDGE_COLOR='blue'
EH_EDGE_COLOR='darkgreen'

def create_rest_edge(label: str):
    return Edge(xlabel=label, color=REST_EDGE_COLOR)

def create_eventhub_edge(label: str):
    return Edge(xlabel=label, color=EH_EDGE_COLOR, style='dashed')

with Diagram("Web Service with Task", show=False):
    with Cluster('Clients'):
        desktop=Client('desktop')
        web=React('web client')

    with Cluster('backend'):
        webserver=VMLinux('app server')
        taskserver=VMLinux('task server')
        eventhub=EventHubs('app.task.processing')

    # Bidirecional connetions, using ">>" and "<<"
    desktop >> create_rest_edge('request') << webserver
    web >> create_rest_edge('request') << webserver

    # Unidirecional connections
    webserver >> create_eventhub_edge('task') >> eventhub
    eventhub >> create_eventhub_edge('task') >> taskserver

Neste diagrama, vemos que os elementos podem ser agrupados em Clusters, melhorando a visualização e deixando mais claro a organização do projeto como um todo.

Também mostramos os tipos de elementos da nuvem Azure, diferentemente do exemplo anterior com elementos da AWs. Note também a customização das linhas, com a exibição de labels e cores diferentes, assim como representar conexões bidirecionais, utilizando "»" e "«" de cada lado da linha no código.

Esta é uma pequena amostra dos recursos da biblioteca. Para mais informações, consulte a documentação oficial em https://diagrams.mingrammer.com/.

Benefícios

A biblioteca Diagrams oferece vários benefícios para criar e manter documentação visual:

• Automação: os diagramas podem ser gerados automaticamente como parte de um processo de build da aplicação, garantindo que a documentação esteja sempre atualizada. Isso reduz o risco de diagramas desatualizados causarem confusão ou erros.
• Reprodutibilidade: como os diagramas são gerados a partir do código, eles podem ser versionados, revisados ​​e atualizados junto com a base de código. Isso garante que os diagramas evoluam com o sistema.
• Escalabilidade: para sistemas grandes e complexos, a diagramação manual pode ser demorada e propensa a erros. A abordagem programática do Diagrams permite a geração de diagramas escaláveis ​​e consistentes, cujas alterações podem ser persistidas facilmente por meio de versionamento de código.

Limitações

Embora a biblioteca Diagrams seja poderosa, ela tem algumas limitações:

• Curva de aprendizado: para desenvolvedores não familiarizados com Python ou Graphviz, pode haver uma curva de aprendizado associada ao uso eficaz do Diagrams.
• Limitado à infraestrutura: o Diagrams é altamente especializado para visualização de infraestrutura. Embora isso o torne excelente para os casos de uso pretendidos, ele pode não ser adequado para outros tipos de diagramas, como fluxogramas, diagramas de sequência ou ERDs.
• Layout: existem formas limitadas para ajustar e alinhar os nós. Em gráficos muito grandes e cujos nós tem muitas conexões, a tendência é que a estrutura toda fique confusa.

Conclusão

Diagrams é uma biblioteca muito versátil e ágil ao objetivo que ela se propõe. Vencida a etapa inicial de aprendizado, a velocidade que se ganha comparado com ferramentas drag-and-drop possibita uma enorme agilidade na criação e principalmente na atualização de estrutura de sistemas.

Na segunda parte, falaremos sobre o Mermaid, uma biblioteca que ajuda a criar outros tipos de diagramas mais voltados para a parte de UML, como diagramas de sequência, de classe e outros.