Tanto quanto me lembro, desde o início da minha carreira até hoje, sempre houve a necessidade de colocar em uma página (ou slide) algum tipo de diagrama para explicar um conceito, documentar a arquitetura de software ou fazer um caso. É o famoso *"Uma imagem vale mais que mil palavras"*. 

! [Imagem no mercado] (https://byteswithcoffee.com/picture-worth/)

É muito importante ressaltar que criar abstrações limpas, concisas e bem pensadas e colocá-las em um diagrama não é uma tarefa simples. Ser intencional e transmitir uma mensagem clara com uma página única é ainda mais difícil. Se você quiser se aprofundar mais, Gregor Hohpe tem um capítulo em seu livro The Software Architect Elevator chamado "Diagram-Driven Design" ou, se você é uma pessoa de vídeo, ele aborda parte do assunto em sua palestra AWS re:Invent 2022 - [O elevador do arquiteto: conectando a sala de reuniões e a TI] (https://www.youtube.com/watch?v=goYiaIGebFo).

A primeira e mais importante coisa que me vem à mente quando falo de diagramas na indústria de software é: precisamos criar (ou ajustar) diagramas de acordo com o público-alvo. Parece óbvio, mas às vezes precisamos afirmar o óbvio, então aqui vamos com um exemplo: por favor, não apresente um diagrama de classe UML (Unified Modeling Language) para um executivo sênior que só quer ter uma compreensão de como seu aplicativo funciona e se integra com o resto do mundo. Isso significa que usar um diagrama para governá-los como uma estratégia não funcionará.

Mas, criar vários diagramas para públicos diferentes sem algum nível de consistência e deixá-los em ferramentas como apresentações do PowerPoint, [Miro](https://miro.com/), [Draw.io](https://draw.io/) ou [Excalidraw](https://excalidraw.com/) também não ajudará muito. Isso é menos sobre preferências de ferramentas e mais sobre ter um local central para armazenar, versão, pesquisa e diagramas de documentos com alguma notação consistente. 

A AWS é um bom exemplo do que estou falando aqui com sua [Página de diagramas de arquitetura de referência] (https://aws.amazon.com/architecture/reference-architecture-diagrams) caso você esteja curioso. Você também pode implementar algo assim de muitas maneiras diferentes e a resposta certa para você (e sua organização) mudará com base em como suas equipes estão organizadas, quem é responsável por manter a documentação / diagramas e as ferramentas que você tem permissão (ou, às vezes, obrigação) a usar. Diagrama como código é uma das várias maneiras que podem ajudá-lo a resolver esse problema.

Em suma, "Diagrama como código" permite que você (e sua organização) gerenciem seus diagramas da mesma maneira que você lida com seu código. Você escreve texto seguindo uma sintaxe (como, codificação), armazena esse artefato em um sistema de controle de versão (como, [GitHub](https://github.com/)) e quando você cria ou renderiza o código baseado em texto que você escreveu, o diagrama será gerado! Este conceito está longe de ser novo, [PlantUML] (https://plantuml.com/) foi lançado em 2009, mas com mais e mais equipes se movendo para usar o git como a única fonte de verdade para o seu trabalho ([GitOps](https://www.atlassian.com/git/tutorials/gitops) você diz?) documentação técnica de engenharia de software (que espero que também inclua diagramas) está na mistura para fazer parte deste movimento.

As coisas nunca são simples, simples e fáceis e, claro, existem várias maneiras de implementar o Diagram como Código. Aqui estão alguns que eu testei:

##### PlantUML

Eu já mencionei [PlantUML] (https://plantuml.com/) e depois de testar posso dizer que é muito flexível, você pode ir de diagramas UML básicos para coisas não-UML como um diagrama Archimate. Para executar isso localmente, há algumas etapas que você precisa executar (todas documentadas em seu site) e abaixo está um trecho de como você pode ter um diagrama gerado:

@startuml
    
Usuário -> (Aplicativo Front-End): abrir
    (Aplicativo Front-End) -> (Aplicativo Back-end): chamada

@enduml

png gerado:

! [Planta UML] (https://byteswithcoffee.com/plantuml/)

##### Sereia

[Sereia] (https://mermaid.js.org/) é outra opção que funciona muito semelhante ao PlantUML, mas a diferença mais emocionante (pelo menos para mim) é que, se você estiver familiarizado com o Markdown, você não deve ter problemas em aprender a sintaxe e usá-lo, já que você apenas "codifica" um bloco de sereia em seu arquivo .md e feito o diagrama será renderizado para você. O GitHub oferece suporte nativo à renderização quando você envia um arquivo .md para lá e também o Visual Studio Code faz o mesmo quando você usa a visualização. Para casos de uso em que você está documentando coisas usando Markdown, evoluir para usar Mermaid para seus diagramas e manter ambos juntos no mesmo arquivo .md é bastante simples e limpo! Aqui está um exemplo:


imagem gerada:

! [Sereia] (https://byteswithcoffee.com/mermaid/)

##### Diagramas (por Mingrammer)

Você é um desenvolvedor Python e quer ter uma opção Diagram as Code usando Python? Seu problema pode ser resolvido com [Diagramas](https://diagrams.mingrammer.com/)! Ao ler a documentação e os exemplos que o site tem, senti que, neste caso, é mais sobre ícones de produtos em nuvem e diagramas de arquitetura de sistema / solução e menos sobre blocos genéricos / suporte a fluxograma por *padrão*. Eu digo padrão porque depois de algumas escavações em seus problemas do Github eu descobri que você pode usar todas as formas Graphviz, a fim de ter formas genéricas e formas como no exemplo abaixo:

de diagramas importar Diagrama, Nó, Borda
    from diagrams.onprem.client import Usuário

com Diagram(filename="user_front_and_back", outformat="png", show=False, direction="LR") como diag:

usuário = Usuário(label="Usuário")
        front = Node(label="Front-End App", shape="retângulo", style="arredondado", labelloc="c")
        back = Node(label="Aplicativo Back-End", shape="retângulo", style="arredondado", labelloc="c")

usuário >> Edge(label="open") >> frente
        borda frontal >>(label="chamadas") >> para trás

Fig

Parece errado escrever um código Python e publicá-lo on-line sem ter o *import Pandas as pd* e *import numpy as np* na parte superior. Será que isso vai funcionar sem essas 2 frases mágicas? Não tenho certeza nunca vi uma essência de código Python on-line sem eles 👀. Ok, desculpe, foi uma piada de mau gosto... vamos voltar... aqui vai a imagem que foi gerada ao executar o código:

! [Diagramas] (https://byteswithcoffee.com/diagrams/)

##### Structurizr

Simon Brown criou o [modelo C4](https://c4model.com/) "*como uma maneira de ajudar as equipes de desenvolvimento de software a descrever e comunicar a arquitetura de software, tanto durante sessões de design iniciais quanto ao documentar retrospectivamente uma base de código existente*" de acordo com seu site. Como é um modelo e ganhou força com desenvolvedores de software e arquitetos, as pessoas começaram a construir coisas em torno do conceito C4. Para provar meu ponto, você pode usar todas as três opções mencionadas de Diagrama como Código acima para gerar diagramas C4: [Biblioteca C4 PlantUML](https://plantuml.com/stdlib#062f75176513a666), [Sintaxe C4 de Sereia](https://mermaid.js.org/syntax/c4c.html) e [Pacote de diagramas C4](https://diagrams.mingrammer.com/docs/nodes/c4).

Mas por que eu comecei a falar sobre C4 na parte [Structurizr] (https://structurizr.com/) do post? Bem, porque o Structurizr foi especialmente projetado para suportar o modelo C4 de forma Diagrama como Código. Isso não é coincidência, uma vez que o autor do modelo é a mesma pessoa que escreveu Structurizr. Simon fez uma bela apresentação falando sobre suas perspectivas sobre [Diagrama como Código 2.0](https://www.youtube.com/watch?v=Za1-v4Zkq5E) se você estiver interessado.

Outra coisa a salientar é que o Structurizr funciona de uma forma diferente. Você escreve código usando uma linguagem de modelagem e que pode gerar vários diagramas. Ao trabalhar com um modelo ([Archimate](https://www.archimatetool.com/) é outro exemplo de uma linguagem de modelagem), você define os componentes e os relacionamentos apenas uma vez e pode reutilizá-los em diagramas (é um relacionamento de um para muitos). Não? Ainda confuso? Vamos tentar um exemplo: Se eu criar um componente chamado "Aplicativo Front-End" e usar esse componente em 10 diagramas se mais tarde alterarmos esse componente para "Aplicativo Web", preciso alterá-lo apenas uma vez e todas as minhas 10 visualizações serão atualizadas. 

Código:

espaço de trabalho {

modelo {
        usuário = pessoa "Usuário"
        softwareSystem = softwareSystem "Sistema de Software" {
            front = contêiner "Aplicativo Front-End" {
                usuário -> este "aberto"
            }
            container "Aplicativo de back-end" {
                frente -> isso "chama"
            }
        }
    }

visualizações {
        systemContext softwareSystem {
            incluir*
            autolayout lr
        }

container softwareSystem {
            incluir*
            autolayout lr
        }

tema padrão
    }

}

Imagem gerada:

! [Structurizr] (https://byteswithcoffee.com/structurizr/)

##### Bastidores

O Spotify entendeu a importância de centralizar um monte de coisas em um único Portal Interno do Desenvolvedor e decidiu investir/criar [Backstage] (https://backstage.io/). Sua abordagem à documentação/visualização da arquitetura de software evoluiu em torno disso. O que eles fizeram exatamente na parte do Diagrama? Eles criaram o [Spotify System Model] (https://backstage.io/docs/features/software-catalog/system-model) (que é derivado do modelo C4) e automatizaram a renderização de diagramas de arquitetura usando a estrutura Backstage que eles tinham em vigor. Cada equipe/esquadrão adiciona as informações necessárias para seus respectivos serviços usando o arquivo YAML do catálogo de serviços e o Backstage faz o resto. É uma abordagem interessante especialmente para destacar dependências. Se você estiver usando o Backstage (e muitas empresas estão adotando o Backstage hoje em dia), isso é mais óbvio de seguir e ter alguns de seus diagramas gerados automaticamente ao lado da documentação dos serviços. Confira [este link](https://roadie.io/blog/modelling-software-backstage/) para obter mais detalhes.

Um comentário final para concluir este post é: documentar as abstrações / diagramas intencionais (como um código ou não) é um jogo completamente diferente dos exercícios de brainstorming. São duas coisas diferentes, com resultados e objectivos diferentes, na minha opinião. Ao fazer um brainstorming de algo com a equipe ou outra pessoa remotamente (sem um quadro branco de palavras reais e marcadores), prefiro [Draw.io] (https://draw.io/) ou [Excalidraw] (https://excalidraw.com/) porque eles são fáceis de usar com formas/setas de arrastar e soltar e têm recursos específicos em torno da colaboração que aceleram a discussão em que você está.

Em resumo, se você quiser diagramas que possam ser controlados por versão, automatizados e sustentáveis, como software, escolha uma opção que funcione para você e sua equipe e Happy Diagramming as Code todos!