C4 Model + C4-PlantUML

#architecture #design #microservices #braziliandevs

C4 Model

O C4 Model é uma forma de desenhar e documentar a arquitetura de um software. Ele foi criado pelo Engenheiro Simon Brown. O nome C4 deriva do modelo 4+1 que significa fazer uso de multiplas visões concorrentes, onde cada uma esta sob uma perspectiva diferente. Neste sentido temos 4 níveis: Context, Containers, Component and Code.

Porque usar C4 Model?

Ajuda a documentação da arquitetura de um software de forma clara, padronizada e eficiente
Cada um dos níveis oferece visões diferentes e isso ajuda a publicos diferentes a entender o software.

C4-PlantUML

O C4-PlantUML é uma ferramenta que permite a criação de diagramas C4 Model usando uma linguagem de programação simples e intuitiva de código aberto e independente de plataforma. Segue um exemplo:



@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
' uncomment the following line and comment the first to use locally
' !include C4_Context.puml

LAYOUT_WITH_LEGEND()

title System Context diagram for Internet Banking System

Person(customer, "Personal Banking Customer", "A customer of the bank, with personal bank accounts.")
System(banking_system, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")

System_Ext(mail_system, "E-mail system", "The internal Microsoft Exchange e-mail system.")
System_Ext(mainframe, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")

Rel(customer, banking_system, "Uses")
Rel_Back(customer, mail_system, "Sends e-mails to")
Rel_Neighbor(banking_system, mail_system, "Sends e-mails", "SMTP")
Rel(banking_system, mainframe, "Uses")
@enduml

Por que usar o C4-PlantUml?

Os diagramas podem ser facilmente atualizados e mantidos por meio de seu código fonte, bem como versionados juntamente ao projeto
Os diagramas são gerados automaticamente a partir do código e isso força a padronização e consistencia, facilitando a comunicação entre todos os envolvidos do projeto

Na pratica

Uma recomendação de organização para seu projeto seria adicionar na raiz do projeto o arquivo C4Context.puml. Este arquivo terá o codigo fonte do diagrama de contexto.

Você pode utilizar um plugin para o IntelliJ para ajudar a criar os diagramas:

Feito isso é so salvar a imagem final do diagrama em uma pasta em seu projeto e usando o readme.md documentar seu projeto fazendo uso do diagrama criado.

Conclusão

O C4 Model pode ser bem util para criar um diagrama de arquitertura rico e eficiente que pode atender a diferentes publicos. Esse recurso combinado ao C4 PlantUML permite que os diagramas fiquem versionados junto ao código fonte do projeto, fazendo com que a documentação evolua da mesma maneira que o código fonte.