C4 Model na prática: Context Diagram (Parte 1)

C4 Model na prática: Context Diagram (Parte 1)

Arquitetura
Repositório de exemplos: todos os diagramas desse post estão em github.com/wander4747/c4model

No post anterior apresentei o C4 Model e as quatro camadas que ele propõe. Agora começa a parte prática.

Vou entrar em cada diagrama separadamente, com exemplos reais em PlantUML. Vamos começar pelo Context Diagram: o mais alto nível e, na maioria dos casos, o mais útil pra comunicação fora do time de engenharia.

O que é o Context Diagram

O Context Diagram responde uma pergunta simples: quem usa esse sistema e com o que ele se comunica?

Você não explica como o sistema funciona por dentro. Não aparece tecnologia, não aparece infraestrutura. O sistema é uma caixa preta. O diagrama mostra:

  • Usuários (pessoas ou grupos) que interagem com o sistema
  • Sistemas externos com os quais o sistema se integra
  • Relações entre eles: quem envia dados pra quem, quem depende de quem

É o diagrama que funciona numa reunião com produto, com stakeholder, com alguém que acabou de entrar na empresa. Ninguém precisa saber o que é uma API REST pra entender um Context Diagram bem feito.

Configurando o ambiente

Os exemplos desse post usam PlantUML com a biblioteca C4-PlantUML. Você pode rodar localmente ou via web.

Web (sem instalação)

A forma mais rápida é usar o editor online do PlantUML: plantuml.com/plantuml

Cole o código, veja o diagrama na hora. Sem instalar nada.

VSCode

  1. Instale a extensão PlantUML (jebbs.plantuml)
  2. Abra qualquer arquivo .puml e use Alt+D pra visualizar o diagrama

A biblioteca C4 é incluída diretamente no código via URL, então não precisa de configuração extra pra começar. Se quiser rodar offline com arquivos locais, adicione no .vscode/settings.json:

{
  "plantuml.jarArgs": ["-DRELATIVE_INCLUDE=."]
}

A extensão também suporta snippets do C4-PlantUML. Copie o arquivo .vscode/C4.code-snippets do repositório C4-PlantUML pro seu projeto e você terá autocomplete pras macros. Veja as instruções completas em:

https://github.com/plantuml-stdlib/C4-PlantUML/tree/master#snippets-for-visual-studio-code

JetBrains (IntelliJ, GoLand, etc.)

  1. Instale o Graphviz no sistema operacional
  2. Instale o plugin PlantUML Integration no IDE

Para ter autocomplete com os templates C4:

  1. Baixe o arquivo intellij/c4_live_template.zip do repositório C4-PlantUML
  2. Vá em File → Manage IDE Settings → Import Settings
  3. Selecione o arquivo .zip
  4. Marque Live templates e clique em OK
  5. Reinicie o IDE

Depois disso, em qualquer arquivo .puml, digite c4_ e os templates aparecem no autocomplete. Veja as instruções completas em:

https://github.com/plantuml-stdlib/C4-PlantUML/tree/master#live-templates-for-intellij

As macros do Context Diagram

A biblioteca disponibiliza quatro macros principais. Vamos ver cada uma com detalhe.

Person

Person(alias, "Label", "Description")

Representa um usuário humano que interage com o sistema. Pode ser um cliente, um administrador, um operador: qualquer perfil de pessoa real.

  • alias: identificador interno, sem espaços. Usado pra referenciar esse elemento nas relações.
  • "Label": nome exibido no diagrama. Curto e direto.
  • "Description": texto secundário, menor. Explica quem é essa pessoa com uma frase.
Person(reader, "Reader", "Pessoa que lê os posts do blog")

Use um Person por tipo de usuário, não por indivíduo. “Customer” em vez de “João” ou “Maria”.

System

System(alias, "Label", "Description")

Representa o sistema que você está documentando. É a caixa central do diagrama, o foco de toda a conversa.

  • Renderizado com borda azul, sinalizando que pertence ao seu escopo.
  • Não coloca detalhes técnicos aqui. Nada de “API REST em Go” ou “banco PostgreSQL”. Isso fica no Container Diagram.
System(blog, "Blog", "Blog com posts sobre desenvolvimento de software")

System_Ext

System_Ext(alias, "Label", "Description")

Representa um sistema externo: qualquer sistema com o qual o seu se comunica, mas que está fora do seu controle. APIs de terceiros, serviços de pagamento, provedores de identidade, etc.

  • Renderizado com borda cinza, indicando que está fora do escopo.
  • A distinção visual entre System e System_Ext é intencional: deixa claro quais dependências você controla e quais você não controla.
System_Ext(sendgrid, "SendGrid", "Serviço de envio de e-mails")

Rel

Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")

Define uma relação entre dois elementos. A seta vai de from pra to.

  • from: alias do elemento de origem
  • to: alias do elemento destino
  • "Label": descreve o que acontece nessa relação. Use verbos no presente: “envia”, “consulta”, “autentica”.
  • "Technology": opcional. Protocolo ou tecnologia usada (ex: "HTTPS", "OAuth 2.0"). Aparece em itálico abaixo do label.
Rel(reader, blog, "Lê posts")
Rel(blog, sendgrid, "Envia notificações via", "HTTPS")

A direção da seta importa. Rel(A, B, ...) significa que A inicia a comunicação com B.

Exemplo completo: Blog

@startuml blog
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

Person(reader, "Reader", "Pessoa que lê os posts do blog")
Person(author, "Author", "Pessoa que escreve os posts")

System(blog, "Blog", "Blog com posts sobre desenvolvimento de software")

Rel(reader, blog, "Lê posts")
Rel(author, blog, "Escreve e publica posts")

@enduml

A primeira linha do diagrama inclui a biblioteca C4-PlantUML direto do GitHub. Não precisa instalar nada: o PlantUML busca o arquivo na hora de renderizar.

O resultado: dois atores, um sistema, duas relações. Qualquer pessoa entende em menos de um minuto o que esse sistema faz e quem usa.

O que colocar e o que deixar de fora

Coloca:

  • Todos os usuários que interagem diretamente com o sistema (por tipo, não por indivíduo)
  • Sistemas externos com os quais há troca de dados
  • A direção e o propósito das relações

Não coloca:

  • Tecnologia interna (banco de dados, linguagem, framework)
  • Múltiplos ambientes (dev, staging, prod)
  • Subcomponentes do seu sistema (isso é nível de Container)

A regra prática: se alguém de produto ou de negócio não consegue ler e entender em menos de um minuto, tem informação a mais.

O que vem a seguir

No próximo post vou entrar no Container Diagram, onde você abre o sistema e mostra as peças técnicas que o compõem: APIs, bancos de dados, aplicações frontend, filas de mensagem.

Os exemplos desse post estão no repositório github.com/wander4747/c4model, na pasta context/.

Context Diagram parece simples, e é. Mas a simplicidade é o ponto. Um diagrama que qualquer pessoa entende em um minuto vale mais que um diagrama tecnicamente perfeito que ninguém abre.

Tags: c4model arquitetura diagramas plantuml documentação