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 do software ou fazer um caso. É o famoso Uma imagem vale mais que mil palavras É 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 um pager é 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 cobre parte do assunto em sua palestra AWS re:Invent 2022 - [O arquiteto elevador: conectando a sala de reuniões e TI](https://www.youtube.com/watch?v=goYiaIGebFo). A primeira e mais importante coisa que me vem à cabeça quando se fala em 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 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 entender como seu aplicativo funciona e se integra com o resto do mundo. Isso significa que usar um diagrama para governar todos como estratégia não funcionará eixá-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 vai ajudar muito. Isso tem menos a ver com preferências de ferramentas e mais com ter um local central para armazenar, criar versões, 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 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, obrigado) a usar. 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) gerencie seus diagramas da mesma forma que você lida com seu código. Você escreve o 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ê constrói ou renderiza o código baseado em texto, 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 seu trabalho ([GitOps](https: //www.atlassian.com/git/tutorials/gitops) você diz?) documentação técnica de engenharia de software (que esperamos que também inclua diagramas) está na mistura 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 testei: ##### PlantUML 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 executá-lo 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 Front-End): abrir (Aplicativo Front-End) -> (Aplicativo Back-end): chamada @enduml png gerado: ! [Planta UML] (https://byteswithcoffee.com/plantuml/) ##### Mermaid [Mermaid](https://mermaid.js.org/) é outra opção que funciona muito semelhante ao PlantUML, mas a diferença mais interessante (pelo menos para mim) é que, se você estiver familiarizado com o Markdown, não deverá ter problemas para aprender o sintaxe e usá-la, já que você acabou de codificar um bloco de sereia em seu arquivo .md e pronto, 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 o Markdown, evoluindo para usar o Mermaid para seus diagramas e mantendo os dois juntos no mesmo arquivo .md é bastante simples e organizado! Aqui está um exemplo: ```Mermaid 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ê é um desenvolvedor Python e quer 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 que o site possui, 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*. Digo padrão porque depois de pesquisar alguns problemas no Github, descobri que você pode usar todas as formas Graphviz para ter formas genéricas e formas 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 online sem ter *importar Pandas como pd* e *importar numpy como np* no topo. Isso funcionará sem essas 2 frases mágicas? Não tenho certeza se nunca vi uma essência do código Python online sem eles 👀. Ok desculpa foi uma piada de mal gosto... vamos voltar... aí 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 forma de ajudar as equipes de desenvolvimento de software a descrever e comunicar a arquitetura de software, tanto durante as 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 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 todos os três diagramas mencionados como opções de código 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 no [Structurizr ](https://structurizr.com/) parte 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, pois o autor do modelo é a mesma pessoa que escreveu o Structurizr. Simon fez uma bela apresentação falando sobre suas perspectivas sobre [Diagram as Code 2.0](https://www.youtube.com/watch?v=Za1-v4Zkq5E) se você estiver interessado. Outra coisa a destacar é que o Structurizr funciona em uma maneira diferente. Você escreve código usando uma linguagem de modelagem e isso 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 nos diagramas (é um para muitos relacionamento). Não? Ainda confuso? Vamos tentar um exemplo: Se eu criar um componente chamado Front-End App e utilizar este componente em 10 diagramas se posteriormente mudarmos este componente para Web App preciso alterar apenas uma vez e todas as minhas 10 views 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/) ##### Backstage O Spotify entendeu a importância de centralizar um monte de coisas em um único portal interno de desenvolvedores e decidiu investir/criar [Backstage](https://backstage.io/). Sua abordagem para documentação/visualização de 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 eles tinham no lugar. 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 as dependências. Se você estiver usando o Backstage (e muitas empresas estão adotando o Backstage hoje em dia), é fácil 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 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 são fáceis de usar com formas/setas de arrastar e soltar e possuem recursos específicos de colaboração que aceleram a discussão em que você está. Em resumo, se você deseja diagramas que podem ser controlados por versão, automatizados e mantidos como software, escolha uma opção que funcione para você e sua equipe e boa diagramação como código para todos!