Neste artigo, irei guiá-lo passo a passo para criar documentação visual dinâmica e interativa usando ferramentas de Diagrama como Código. Em vez de imagens estáticas, geraremos diagramas de forma programática, garantindo que estejam sempre atualizados e fáceis de manter.

? Diagrama como código

Diagrama como código é uma abordagem que permite criar diagramas por meio de código em vez de ferramentas gráficas tradicionais. Em vez de construir diagramas manualmente, você pode escrever código em um arquivo de texto para definir a estrutura, os componentes e as conexões dos seus diagramas.

Esse código é então traduzido em imagens gráficas, tornando-o mais fácil de integrar e documentar em projetos de software, onde é especialmente útil para criar e atualizar diagramas arquitetônicos e de fluxo de forma programática.

O que são diagramas?

Diagramas é uma ?biblioteca Python que implementa a abordagem Diagrama como Código, permitindo criar diagramas de infraestrutura arquitetônica e outros tipos de diagramas por meio de código. Com Diagramas, você pode definir facilmente componentes de infraestrutura em nuvem (como AWS, Azure e GCP), elementos de rede, serviços de software e muito mais, tudo com apenas algumas linhas de código.

? Benefícios do diagrama como código

• ? Representação de Diagramas como Código: Crie e atualize diagramas diretamente do código, garantindo manutenibilidade em projetos ágeis.
• ? Documentação automatizada: Gere recursos visuais a partir do código, mantendo os diagramas alinhados com a arquitetura atual.
• ? Controle de alterações: acompanhe as modificações do diagrama ao longo do tempo.
• ? Clareza aprimorada: melhore a compreensão de sistemas complexos com recursos visuais claros e compartilhados.
• ✏️ Personalizável: represente infraestruturas de nuvem, fluxos de trabalho ou pipelines de dados com recursos visuais flexíveis e personalizados.

Tutorial

? Instalação da Biblioteca

No momento, eu estava usando a versão '0.23.4' para este tutorial.

!pip install diagrams=='0.23.4'

? Diagramas: Nós

A biblioteca permite criar diagramas de arquitetura de forma programática, usando nós para representar diferentes componentes e serviços de infraestrutura.

Tipos de nós

Os nós nos diagramas representam componentes de diferentes provedores de serviços em nuvem, bem como outros elementos arquitetônicos. Aqui estão as principais categorias de nós disponíveis:

• ☁️ Provedores de nuvem: AWS (Amazon Web Services), Azure, GCP, IBM Cloud, Alibaba Cloud, Oracle Cloud, DigitalOcean, entre outros.
• ? On-Premise: Representa a infraestrutura fisicamente localizada nas dependências da empresa.
• ? Kubernetes (K8S): Sistema de orquestração de contêineres para automatizar a implantação, escalonamento e gerenciamento de aplicativos em contêineres (representados pela roda de um navio, simbolizando controle e navegação).
• ?️ OpenStack: plataforma de software de código aberto para criação e gerenciamento de nuvens públicas e privadas.
• ? Genérico: Nós genéricos que podem representar qualquer componente não coberto especificamente por nós específicos do provedor (ferramentas cruzadas, representando diferentes ferramentas em uma categoria).
• ☁️ SaaS (Software as a Service): Representa aplicações entregues como serviço pela internet, como Snowflake, serviços de chat (Slack, Teams, Telegram, entre outros), segurança (ex., Okta ) ou redes sociais (telefone e nuvem riscados para o conceito SaaS).
• ? Personalizado: permite que os usuários personalizem seus diagramas usando ícones PNG armazenados em uma pasta específica. Isto é útil para representar componentes de infraestrutura não cobertos pelos nós padrão (ferramentas personalizadas riscadas).

? Linguagens de programação

A biblioteca Diagramas permite que você use diferentes nós para representar várias linguagens de programação. Esses nós são úteis para indicar em seus diagramas se alguma parte de sua arquitetura utiliza scripts ou componentes desenvolvidos em uma linguagem de programação específica.

A seguir, mostraremos todos os idiomas disponíveis na biblioteca. Se algum idioma estiver faltando, você pode adicionar nós personalizados fazendo upload do logotipo correspondente em uma pasta específica.

# Create the diagram object
with diagrams.Diagram("Programming Languages", show=False, filename="languages"):
    # Get all the languages available in this library
    languages = [item for item in dir(diagrams.programming.language) if item[0] != '_']

    # Divide the representation in two lines
    mid_index = len(languages) // 2
    first_line = languages[:mid_index]
    second_line = languages[mid_index:]

    # Add nodes in the first row
    prev_node = None

    for language in first_line:
        current_node = eval(f"diagrams.programming.language.{language}(language)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

    # Add nodes in the second row
    prev_node = None

    for language in second_line:
        current_node = eval(f"diagrams.programming.language.{language}(language)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

Image("languages.png")

☁️AWS (Amazon Web Services)

Podemos usar nós Amazon, que são organizados em diversas categorias, como:

• Analytics e negócios: aws.analytics, aws.business
• Computação e armazenamento: aws.compute, aws.storage, aws.cost
• Banco de dados e DevTools: aws.database, aws.devtools
• Integração e gerenciamento: aws.integration, aws.management
• Aprendizado de máquina e dispositivos móveis: aws.ml, aws.mobile
• Redes e segurança: aws.network, aws.security
• Outros: aws.blockchain, aws.enduser, aws.engagement, aws.game, aws.general, aws.iot, aws.media, aws.migration, aws.quantum, aws.robotics, aws. satélite

A seguir, representaremos uma dessas categorias para visualizar os nós disponíveis em aws.database.

from diagrams import Diagram
from IPython.display import Image
import diagrams.aws.database as aws_database


database_components = []
for item in dir(aws_database):
    if item[0] != '_':
        if not any(comp.startswith(item) or item.startswith(comp) for comp in database_components):
            database_components.append(item)


with Diagram("AWS Database", show=False, filename="aws_database"):
    mid_index = len(database_components) // 2
    first_line = database_components[:mid_index]
    second_line = database_components[mid_index:]


    prev_node = None
    for item_database in first_line:
        current_node = eval(f"aws_database.{item_database}(item_database)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node


    prev_node = None
    for item_database in second_line:
        current_node = eval(f"aws_database.{item_database}(item_database)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

Image("aws_database.png")

☁️ Caso de uso

Agora, vamos criar um blueprint simples que corresponda à importação de um conjunto de dados e ao treinamento de um modelo de aprendizado de máquina na AWS.

from diagrams import Diagram, Cluster
from diagrams.aws.storage import S3
from diagrams.aws.analytics import Glue, Athena
import diagrams.aws.ml as ml
from diagrams.aws.integration import StepFunctions
from diagrams.aws.compute import Lambda
from diagrams.aws.network import APIGateway
from IPython.display import Image

with Diagram("AWS Data Processing Pipeline", show=False):

    lambda_raw = Lambda('Get Raw Data')
    # Buckets de S3
    with Cluster("Data Lake"):
        s3_rawData = S3("raw_data")
        s3_stage = S3("staging_data")
        s3_data_capture = S3("data_capture")


    athena = Athena("Athena")
    s3_rawData >> athena
    s3_stage >> athena
    s3_data_capture >> athena

    #  Step Functions Pipeline
    with Cluster("Data Processing Pipeline"):
        step_functions = StepFunctions("Pipeline")

        # Glue Jobs in Step Functions
        with Cluster("Glue Jobs"):
            data_quality = Glue("job_data_quality")
            transform = Glue("job_data_transform")
            dataset_preparation = Glue("job_dataset_model")

        # Define Step Functions Flows
        step_functions >> data_quality >> transform >> dataset_preparation
        s3_rawData >> data_quality

    # SageMaker for model training and deployment
    with Cluster("SageMaker Model Deployment"):
        train_model = ml.SagemakerTrainingJob("job_train_model")
        eval_model = ml.SagemakerGroundTruth("job_evaluate_model")
        endpoint = ml.SagemakerModel("model_enpoint")

    # API Gateway and Lambda for the endpoint
    api_gateway = APIGateway("API_gateway")
    lambda_fn = Lambda("invoke_endpoint")

    # Connection
    lambda_raw >> s3_rawData
    s3_stage >> train_model >> eval_model >> endpoint
    endpoint >> lambda_fn >> api_gateway
    endpoint >> s3_data_capture
    dataset_preparation >> train_model


Image("aws_data_processing_pipeline.png")

Repositório

Abaixo está o link para todo o código, se você achar útil, pode deixar uma estrela ⭐️ e me seguir para receber notificações de novos artigos. Isso me ajudará a crescer na comunidade de tecnologia e a criar mais conteúdo.

Se você quiser ver como implementar um site de documentação usando esse pipeline você pode ler o artigo que publiquei no link a seguir

? Referências

1. Diagramas: https://diagrams.mingrammer.com/