C4 Model: uma forma de documentar arquitetura de software

Se você já tentou documentar a arquitetura de um sistema, provavelmente passou por um desses cenários:

• Criou um diagrama bonito no Draw.io, Figma ou sei la o que e ficou desatualizado antes de terminar o sprint
• Fez um fluxo tão detalhado que ninguém teve paciência de ler
• Tentou explicar o sistema pra um stakeholder e ele ficou perdido no meio do segundo slide

Esse é um problema recorrente. E o C4 Model é uma das respostas mais práticas que eu já encontrei pra ele.

O que é o C4 Model?

C4 Model é um framework criado por Simon Brown pra descrever arquitetura de software através de diagramas hierárquicos.

A ideia central é simples: nível de abstração importa. Você não explica o mesmo sistema da mesma forma pra um gerente de produto e pra um desenvolvedor que vai mexer no código. Um precisa entender o contexto geral. O outro precisa entender como os componentes internos se conectam.

O C4 resolve isso dividindo a documentação em 4 camadas. Cada camada responde uma pergunta diferente, com um nível diferente de detalhe.

O nome C4 vem exatamente das 4 camadas: Context, Container, Component e Code.

As 4 camadas (visão geral)

1. Context: O sistema no mundo

Responde: “O que é esse sistema e quem interage com ele?”

É o diagrama mais alto nível. Mostra o sistema como uma caixa preta, os usuários que interagem com ele e os sistemas externos com os quais ele se comunica. Ideal pra onboarding, apresentações pra stakeholders, ou pra qualquer conversa onde você precisa alinhar o propósito do sistema sem entrar em detalhe técnico.

2. Container: Como o sistema é composto tecnicamente

Responde: “Quais são as peças que compõem esse sistema?”

Aqui você abre a caixa. Aparecem as aplicações, APIs, bancos de dados, filas de mensagem, serviços… Ainda não é o nível de código, mas já é técnico o suficiente pra um engenheiro entender como as partes se conectam. É o diagrama mais útil no dia a dia pra times de engenharia.

3. Component: Organização interna de um container

Responde: “Como um serviço específico é organizado por dentro?”

Você entra dentro de um container e mostra seus módulos internos: controllers, services, repositories, handlers… Útil quando o time precisa entender como uma parte específica do sistema está estruturada, principalmente em sistemas com alta complexidade interna.

4. Code: O nível do código

Responde: “Como esse componente é implementado?”

É o nível mais granular: classes, interfaces, dependências. Normalmente representado com diagramas UML. Na prática, esse nível quase sempre é gerado automaticamente pelas ferramentas de IDE ou documentação: raramente vale o esforço de manter manualmente.

Por que faz sentido usar?

Algumas coisas que me convenceram:

Reduz ambiguidade em revisões de arquitetura. Quando todo mundo usa a mesma linguagem e estrutura de diagrama, as discussões ficam mais objetivas. Você discute a arquitetura em si, não o formato do diagrama.

Facilita comunicação entre perfis diferentes. O diagrama de Context funciona numa reunião com produto. O de Container funciona numa revisão técnica. Você não precisa criar dois documentos completamente separados: é o mesmo sistema, em camadas diferentes.

Escala com o crescimento do sistema. Você não precisa atualizar todos os níveis toda vez que algo muda. Uma mudança pontual num serviço geralmente afeta só o nível de Component, não o de Context.

O que vem a seguir

Nos próximos posts, vou entrar em cada um dos diagramas na prática. Vou mostrar exemplos reais, as ferramentas que uso pra criar e manter esses diagramas.

Se você quer entender de onde saíram os exemplos que vou usar, o repositório com os diagramas está disponível em github.com/wander4747/c4model.

C4 Model não é bala de prata. É uma convenção útil. E como toda convenção, o valor real aparece quando o time inteiro segue, não só quem escreveu a documentação.