Diagrams as Code: Keep Your Architecture Docs Alive Inside the Repo

Diagramas de código são uma solução que permite que as definições de arquitetura sejam mantidas junto ao código-fonte, podendo ser revisadas através de Pull Requests e nunca ficar obsoleta. Ao contrário de diagramas em imagem, os diagramas de código são textuais, portanto podem ser versionados, revisados e executados automaticamente.

O uso de diagramas de código também elimina a necessidade de usar ferramentas externas para editar ou renderizar os diagramas, o que acelera o processo de revisão e reduz aprobção de alterações.

Um dos principais benefícios de usar diagramas de código é a facilidade com que os desenvolvedores podem atualizar conteúdos relacionados à arquitetura do sistema. Ao incorporar as definições de diagramas diretamente no repositório do projeto, as alterações causadas por mudanças de código também são refletidas nos diagramas, permitindo assim uma visão completa das dependências e do fluxo de dados.

Uma das maneiras mais populares de criar diagramas de código é usando Mermaid, uma linguagem de diagramas que pode ser renderizada nativamente por plataformas como GitHub e GitLab. Além disso, outras linguagens de diagramas como PlantUML e Structurizr DSL também podem ser utilizadas, dependendo das necessidades específicas da equipe.

Para integrar diagramas de código em um workflow de desenvolvimento, é recomendado adicionar as definições de diagramas em arquivos com a extensão .mmd e incluir um processo de validação durante a fase de CI/CD. Isso garante que todos os diagramas sejam revisados e validados antes de serem integrados ao código principal. Além disso, os diagramas podem ser gerados automaticamente a partir de informações disponíveis no código, como arquivos de configuração do Docker Compose ou scripts de build, garantindo que a arquitetura permaneça sincronizada com o código fonte.