Pelo que 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 apresentar 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 claras, 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 é ainda mais difícil. Se você quiser se aprofundar, Gregor Hohpe tem um capítulo em seu livro The Software Architect Elevator chamado “Diagram-Driven Design” ou, se você é um especialista em vídeo, ele aborda parte do assunto em sua palestra sobre o 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 sobre diagramas na indústria de software é: precisamos criar (ou ajustar) diagramas de acordo com o público-alvo. Parece óbvio, mas às vezes precisamos dizer o óbvio, então vamos dar um exemplo: por favor, não apresente um diagrama de classes UML (Unified Modeling Language) a um executivo sênior que só quer ter uma ideia de como seu aplicativo funciona e se integra ao resto do mundo. Isso significa que usar um diagrama para governar todos eles como 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 em PowerPoint, [Miro] (https://miro.com/), [Draw.io] (https://draw.io/) ou [Excalidraw] (https://excalidraw.com/) também não ajudará muito. Isso tem menos a ver com preferências de ferramentas e mais com um local central para armazenar, redimensionar, pesquisar e documentar diagramas 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 na forma 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, obrigado) a usar. O diagrama como código é uma das várias maneiras que podem ajudá-lo a resolver esse problema. Resumindo, “Diagrama como código” permite que você (e sua organização) gerenciem seus diagramas da mesma forma que manipulam seu código. Você escreve texto seguindo uma sintaxe (por exemplo, codificação), armazena esse artefato em um sistema de controle de versão (como [GitHub] (https://github.com/)) e ao criar ou renderizar o código baseado em texto que você escreveu, o diagrama será gerado! Esse conceito está longe de ser novo, o [PlantUML] (https://plantuml.com/) foi lançado em 2009, mas com cada vez mais equipes adotando o git como a única fonte de verdade para seu trabalho ([GitOps] (https://www.atlassian.com/git/tutorials/gitops), você diz?) a documentação técnica de engenharia de software (que, esperançosamente, também inclua diagramas) está pronta para fazer parte desse movimento. As coisas nunca são claras, simples e fáceis e, claro, existem várias maneiras de implementar o Diagram as Code. Aqui estão alguns que eu testei: ##### PlantUML Eu já mencionei [PlantUML] (https://plantuml.com/) e, após o teste, posso dizer que é muito flexível, você pode passar 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 gerar um diagrama: @startuml Usuário -> (aplicativo de front-end): abrir (Aplicativo de front-end) -> (aplicativo de back-end): chamada @enduml png gerado: ! [UML da planta] (https://byteswithcoffee.com/plantuml/) ##### Sereia [Mermaid] (https://mermaid.js.org/) é outra opção que funciona de forma muito semelhante ao PlantUML, mas a diferença mais interessante (pelo menos para mim) é que, se você estiver familiarizado com o Markdown, não terá problemas em aprender a sintaxe e usá-la, pois basta “codificar” um bloco de sereia em seu arquivo.md e pronto, o diagrama será renderizado para você. O GitHub suporta nativamente a renderização quando você envia um arquivo.md para lá e o Visual Studio Code faz o mesmo quando você usa a visualização prévia. Para casos de uso em que você está documentando coisas usando o Markdown, evoluir para usar o Mermaid em seus diagramas e manter os dois juntos no mesmo arquivo.md é bem simples e elegante! Aqui está um exemplo: ```sereia fluxograma LR usuário (Usuário) -- abrir -->front (aplicativo de front-end) front-- calls -->back (aplicativo de back-end) ``` imagem gerada: ! [Sereia] (https://byteswithcoffee.com/mermaid/) ##### Diagramas (por Mingrammer) Você é desenvolvedor de Python e deseja ter uma opção de diagrama como código usando Python? Seu problema pode ser resolvido com [Diagramas] (https://diagrams.mingrammer.com/)! Ao ler a documentação e os exemplos do site, achei que, nesse caso, se trata mais de ícones de produtos em nuvem e diagramas de arquitetura de sistema/solução e menos sobre suporte genérico de blocos/fluxogramas por *padrão*. Eu digo padrão porque, depois de investigar os problemas do Github, descobri que você pode usar todas as formas do Graphviz para ter formas e formas genéricas, como no exemplo abaixo: a partir de diagramas, importe Diagram, Node, Edge do usuário de importação diagrams.onprem.client 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="aplicativo front-end”, shape="retângulo”, estilo = “arredondado”, labelloc="c”) back = Node (label="aplicativo de back-end”, shape="retângulo”, estilo = “arredondado”, labelloc="c”) usuário >> Edge (label="open”) >> frontal frente >> Edge (label="calls”) >> voltar diag Parece errado escrever um código Python e publicá-lo on-line sem ter *import Pandas as pd* e *import numpy as np* na parte superior. Isso funcionará sem essas duas frases mágicas? Não tenho certeza se nunca vi uma essência do código Python online 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/) ##### Estruturador Simon Brown criou o [modelo C4] (https://c4model.com/) “*como uma forma de ajudar as equipes de desenvolvimento de software a descrever e comunicar a arquitetura de software, tanto durante sessões iniciais de design quanto ao documentar retrospectivamente uma base de código existente*”, de acordo com seu site. Como é um modelo e ganhou força entre desenvolvedores e arquitetos de software, as pessoas começaram a construir coisas em torno do conceito C4. Para provar meu argumento, você pode usar todas as três opções de Diagrama como Código mencionadas acima para gerar diagramas C4: [biblioteca PlantUML C4] (https://plantuml.com/stdlib#062f75176513a666), [Sintaxe Mermaid C4] (https://mermaid.js.org/syntax/c4c.html) e [Pacote Diagrams C4] (https://diagrams.mingrammer.com/docs/nodes/c4). Mas por que 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 em uma forma de diagrama como código. Isso não é coincidência, já que o autor do modelo é a mesma pessoa que escreveu o Structurizr. Simon fez uma boa 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 ressaltar é que o Structurizr funciona de uma maneira diferente. Você escreve código usando uma linguagem de modelagem que pode gerar vários diagramas. Ao trabalhar com um modelo ([Archimate] (https://www.archimatetool.com/) é outro exemplo de linguagem de modelagem), você define os componentes e os relacionamentos apenas uma vez e pode reutilizá-los em diagramas (é uma relação de um para muitos). Não? Ainda está confuso? Vamos tentar um exemplo: se eu criar um componente chamado “Aplicativo Front-End” e usar esse componente em 10 diagramas, se posteriormente mudarmos 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 de front-end” { usuário -> este “aberto” } contêiner “Aplicativo de back-end” { frente -> isso “chama” } } } visualizações { Sistema de software de contexto do sistema { inclua * layout automático ou } sistema de software de contêiner { inclua * layout automático ou } tema padrão } } Imagem gerada: ! [Estruturar] (https://byteswithcoffee.com/structurizr/) ##### Nos bastidores O Spotify entendeu a importância de centralizar um monte de coisas em um único portal interno para desenvolvedores 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 [Modelo do Sistema Spotify] (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. 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 atualmente), é fácil seguir isso e ter alguns de seus diagramas gerados automaticamente ao lado da documentação do serviço. 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. Essas são duas coisas diferentes com resultados e objetivos diferentes, na minha opinião. Ao debater algo com a equipe ou outra pessoa remotamente (sem um quadro branco e marcadores reais), 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 de 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 de fácil manutenção, como software, escolha uma opção que funcione para você e sua equipe e Happy Diagramming as Code para todos!