Diagram as a Code com c4builder

Como configurar e trabalhar com c4builder e transformar seus diagramas em código?

c4builder é uma ferramenta que permite que permite criar e manter projetos de arquitetura de software como texto (ou código). Dessa forma é possível utilizar versionamento, issues, commits para trabalhar no seu projeto de arquitetura e nunca mais ouvir que arquiteto só desenha caixinha.

Como configurar?

Primeiro será necessário instalar o c4builder via npm:

sudo npm install -g c4builder

Caso ocorra erro na instalação é provável que tenha relação com a versão do node (precisa da versão 14+) e é bem provável que o erro ocorra na instalação do pacote "puppeteer". Se ocorrer, basta usar o nvm para instalar outras versões do node ou apenas atualizar pra última versão estável (caso isso não seja um problema pra você):

npm cache clean -f

sudo npm install -g n

sudo n stable 

Também recomendo instalar a extensão "PlantUML" é essa extensão tem como requisitos o java e o graphviz para conseguir gerar e visualizar os diagramas no vscode:

sudo apt install graphviz

Vamos começar

Agora que tudo está configurado, usaremos o cli do c4builder para criar nosso projeto:

c4builder new


Feito isso, basta abrir o vscode na pasta do projeto e executar:
c4builder site


Responda ou apenas deixe as opções padrão (você poderá alterar qualquer dessas configurações no arquivo .c4builder na raiz do projeto) e assim que aparecer a URL da documentação, acesse no browser:


Agora basta criar seus diagramas no vscode.

Algumas informações rápidas podem ser úteis:

  • Para ver o preview enquanto trabalha nos diagramas, use o botão direito dentro do vscode no arquivo .puml e clique em "preview current diagram"
  • Caso o preview não funcione no vscode, verifique se não falta nomear a marcação @startuml
  • Person, System, System_Ext, Container e outros são funções para criar os elementos do diagrama
  • Rel é a função que usamos para relacionar os elementos
  • Os elementos usam principalmente 3 parâmetros: identificação, nome e descrição. A identificação é o que usamos para criar as relações no método Rel.
  • As relações criadas pela função Rel utilizam 3 parâmetros: identificação origem, identificação destino e descrição da intenção no relacionamento


Veja o exemplo abaixo onde vou criar um elemento de uma pessoa, um site e uma api e criar o relacionamento entre eles:

@startuml main
!include https://raw.githubusercontent.com/adrianvlupu/C4-PlantUML/latest/C4_Context.puml

LAYOUT_WITH_LEGEND()

Boundary(vpn, "Rede interna da empresa") {
Person(usuário, "Usuário do site", "Pessoa que navega no site para se divertir.")
System(site, "Aplicativo web", "Permite que o usuário seja feliz.")
}

System_Ext(serviço, "Serviço de API", "Fornece as informações divertidas para aplicações consumirem.")

Rel(usuário, site, "Utiliza")
Rel(site, serviço, "Consome dado de")
@enduml



Documentação: https://adrianvlupu.github.io/C4-Builder/#/    

Exemplo: https://rcelebrone.github.io/Git-Branch-Based-Environment-Model/#/ (https://github.com/rcelebrone/Git-Branch-Based-Environment-Model)