Uma das definições usadas para abordar arquitetura de software é a de que ela é responsável por definir as partes de um projeto, além da estratégia tecnológica. E, como toda estratégia, é fundamental que haja um processo contínuo de revisão e atualização. Esse foi o motivo que, aqui no time Open Source da Zup, nos fez desenvolver um C4-model.
Ter a visualização da arquitetura do seu projeto é crucial em diversos aspectos, pois te ajuda a responder questões como: de que maneira o meu sistema pode se integrar internamente ou a outros sistemas? Ou, então, como garantir a segurança entre minhas aplicações? E assim por diante.
Um dos clássicos livro de arquitetura, Just Enough Software Architecture: A Risk-Driven Approach, menciona que para se fazer um software com sucesso é preciso lidar com três frentes:
- Partição: a arte de dividir o problema em pequenos pedaços em busca de compreender um todo.
- Conhecimento: a capacidade de não apenas explicar o que está por trás da arquitetura, como ela funciona, mas principalmente o porquê dela ser usada e quais foram as decisões necessárias até se chegar a esse resultado final.
- Abstração: Uma definição de arquitetura de software é difícil de definir com precisão, assim, usar abstrações auxiliam no entendimento e na resolução de problemas complexos.
Outro livro referência na área, chamado Fundamentals of Software Architecture: An Engineering Approach, afirma que a análise constante da arquitetura é um dos requisitos esperados por quem atua com arquitetura dentro de tecnologia.
Diante das alternativas disponíveis no mercado para documentar arquitetura de software, qual delas pode ser uma boa escolha?
Artigo escrito por Otávio Santana e Barbara Rossalli.
O que é o C4-model?
Documentar a arquitetura de um projeto, muitas vezes, é um processo minucioso e que exige tempo, conhecimento de ferramentas e técnicas para diagramação e documentação.
Na prática, o maior desafio dentro de uma documentação de arquitetura de software é evitar dois cenários:
- Documentações de arquitetura muito complexas e que, por consequência, tendem a ficar confusas e obsoletas, perdendo o seu propósito. Em outras palavras: documentações que demandam tempo e se tornam, em pouco tempo, inutilizáveis.
- Documentações “pobres” com pouca informação ou informações falhas.
Em ambos os casos, o resultado final é que elas acabam mais atrapalhando do que ajudando.
O C4-model é um formato de documentação criado pelo engenheiro Simon Brown entre 2006 e 2011 e que tem por base os modelos de documento 4+1 e UML.
Ele surgiu com o intuito de ajudar a resolver o problema de documentação de arquiteturas falhas e difíceis de entender e de se manter. O C4-model traz uma visão mais clara da arquitetura documentada e abrange vários níveis relevantes para as várias “personas” envolvidas.
Os níveis do C4-model
O C4-model é dividido em quatro tipos de diagramas, em que cada um possui um nível diferente de detalhes e público-alvo. A ideia é que cada nível se aprofunde mais nos detalhes e informações do nível anterior.
Uma melhor alusão seria com um Google Maps, no qual se pode dar um zoom para diminuir ou ampliar o desenho arquitetural. Se em um mapa, por exemplo, temos Continente, País, Estado e Cidade, no C4-model temos:
- Contexto.
- Container.
- Componente.
- Código.
A seguir, vamos entender melhor cada um dos níveis:
Nível 1: Contexto
É o primeiro passo do nosso desenho. A ideia é mostrar as interações de forma macro, sem muitos detalhes, dando enfoque às comunicações e dependências entre sistemas e usuários que compõem e interagem com o software.
É um diagrama que pode (e deve) ser consumido por todas as “personas” do projeto, tanto técnico quanto de negócio, e que interagem direta ou indiretamente com o sistema.
Nível 2: Container
O segundo nível mostra o sistema com mais detalhes, descrevendo os seus containers (não confundir com o Docker) e como eles se comunicam/interagem. Nesse nível, é dada ênfase à arquitetura e tecnologias utilizadas.
A ideia é mostrar como o sistema é (ou será) construído de forma macro. Um container pode ser uma aplicação web, um database, um sistema de arquivos, entre outros. É um diagrama a ser consumido pela equipe técnica, que interage direta ou indiretamente com o sistema (profissionais de desenvolvimento, suporte etc).
Nível 3: Componente
Ao chegar ao terceiro nível, damos mais um passo nos detalhes em comparação ao Container, desta vez com a descrição das partes que compõem esses containers. Neste nível, aparecem informações sobre as interações, responsabilidades e tecnologias utilizadas de maneira mais detalhada que nos níveis anteriores.
Um sistema, provavelmente, terá mais de um diagrama de componente. É um diagrama a ser consumido pela equipe técnica de desenvolvimento, que é recomendado somente em casos que geraram valor para equipe e que haja um comprometimento para mantê-lo.
Nível 4: Código
No último nível, o C4-model mostra – a nível de código – como cada componente é implementado e, para isso, usa o diagrama de classes do UML.
De modo geral, este nível de detalhe não é recomendado e, por isso, é uma visão opcional mesmo. Além disso, atualmente existem várias ferramentas que geram esse tipo de diagrama de forma automática.
Por que adotamos o C4-model para arquitetura dos nossos projetos?
Dentro do time Open Source da Zup, a tecnologia e a arquitetura de cada projeto são vistas de forma estratégica, pois entendemos que ter um visão clara do que estamos construindo – tanto a nível técnico quanto de negócios – contribui para evolução do produto e criação de roadmap assertivo.
Um bom produto tecnológico é fundamentado em uma boa arquitetura e sua respectiva documentação. Por isso, com o C4 Model conseguimos ter essa visão de forma ágil e agregando valor ao projeto.
Além disso, utilizar esse modelo nos permite compartilhar o conhecimento arquitetural do projeto com a comunidade de forma simplificada, porém com propósito e valor. Evitando, assim, os extremos já mencionados.
Como nós utilizamos o C4-model
No time, defendemos que a documentação de arquitetura precisa ficar próxima do código e é responsabilidade de todos os integrantes do time. Assim como o código, em si, o nosso C4-model está dentro de um repositório Git.
Isso garante todos os benefícios de um versionamento. Aliás, essa prática de converter para código está presente, inclusive, nas nossas outras documentações (o que também é conhecido por docs as code).
Para facilitar a visualização e manutenção do C4-model, adotamos o modelo de um repositório único por projeto, com disponibilização via S3 e deploy utilizando GitHub Actions.
Qual ferramenta usamos?
Adotamos o desenho arquitetural como código com o C4-Builder. Um ponto importante é que ele possui diversas formas de configuração e exportação. Porém, dentre as configurações existentes, optamos por utilizar via markdown, uma vez que é a ferramenta que:
- já utilizamos para as nossas documentações;
- o nosso time de Technical Writers recomenda;
- é doc as a code, estando alinhado com nossos propósitos e diretrizes;
- possui um actions para GitHub Actions, ferramenta utilizada em nosso pipeline, o que facilita a integração e utilização da ferramenta.
Como alinhamos o C4-model com a documentação?
Assim como nossas documentações técnicas, nossos modelos de C4-model são disponibilizados online via site com referência em um menu na documentação oficial.
É responsabilidade do time de Engenharia, junto com o time de Technical Writing, manter em dia o C4-model a cada atualização em que for necessário atualizar, também, a documentação da arquitetura.
Você pode conferir o C4-model de cada projeto:
Quer conhecer mais sobre o C4 Model? Então assista a esse Office Hours que fizemos sobre o tema:
C4-model: peça-chave para a evolução de um projeto
Uma boa documentação de software é o coração de qualquer projeto Open Source e é, no geral, a porta de entrada para os projetos de código aberto. Com a arquitetura isso não é uma exceção, afinal, ter uma estratégia e um mapa disso facilitam a evolução do projeto e suas possibilidades que, considerando o mundo de computação em nuvens, vai para o infinito e além.
E aí, o que achou do C4-model? Já implementa ou está pensando em adotar? Conta para a gente nos comentários!
