Modelo C4 explicado com um exemplo realista

O modelo C4 é fácil de explicar e igualmente fácil de aplicar errado. Muitos times acabam com um diagrama gigante que mistura usuários, microsserviços, classes Java e caixas de nuvem, exatamente o que o C4 quer evitar. Este guia percorre um exemplo completo de diagrama do modelo C4: um sistema inventado, desenhado nos níveis 1, 2 e 3, para você ver o que entra em cada diagrama, quem o lê e onde aparecem os erros mais comuns.

O modelo C4 em um minuto

O modelo C4, criado por Simon Brown, descreve a arquitetura de software como um conjunto de diagramas com zoom. Cada nível responde a uma pergunta diferente para um público diferente.

No C4, um "container" é qualquer coisa que roda ou armazena dados por conta própria: uma aplicação web, uma API, um worker, um banco de dados, uma fila de mensagens ou um tópico. Não é especificamente um contêiner Docker. O C4 define abstrações, não formas nem cores, então a notação fica por sua conta. A referência oficial está em c4model.com.

O sistema de exemplo: Folio, uma livraria online

Para manter tudo concreto, vamos usar um sistema inventado. A Folio é uma livraria online fictícia, não uma empresa real, que vende livros impressos e e-books.

• Clientes navegam pelo catálogo, compram livros e baixam e-books.
• A equipe de back-office gerencia catálogo, estoque e preços.
• A Folio depende de três sistemas externos: um provedor de pagamentos, um serviço de envio de e-mail e o sistema de fulfillment de um parceiro logístico.

Nível 1: diagrama de contexto (System Context)

O diagrama de contexto mostra a Folio como uma única caixa e tudo ao redor. Nenhum detalhe interno.

• Customer (Person): navega e compra livros.
• Back-office Staff (Person): gerencia catálogo, estoque e preços.
• Folio (Software System, no escopo): permite comprar livros impressos e e-books.
• Payment Provider (Software System, externo): autoriza e captura pagamentos com cartão.
• Email Service (Software System, externo): entrega e-mails de pedido e de envio.
• Fulfilment System (Software System, externo, do parceiro logístico): separa, embala e envia pedidos impressos.

Cada relação recebe um rótulo que diz a intenção:

• Customer → Folio: "Navega e compra livros usando"
• Back-office Staff → Folio: "Gerencia catálogo e estoque usando"
• Folio → Payment Provider: "Recebe pagamentos com cartão usando"
• Folio → Email Service: "Envia e-mails de pedido usando"
• Folio → Fulfilment System: "Envia pedidos impressos para"

Para quem: product managers, pessoas recém-chegadas, revisores de segurança, outros times. Se alguém precisa de mais do que uma olhada rápida para entender, o diagrama está cheio demais. Protocolos e tecnologias geralmente ficam fora deste nível.

Nível 2: diagrama de contêineres

Dê zoom na Folio. Pessoas e sistemas externos continuam onde estão; a Folio vira uma boundary em volta dos seus contêineres.

Agora as relações trazem intenção e protocolo:

• Web Storefront → API Application: "Lê o catálogo, cria pedidos [JSON/HTTPS]"
• API Application → Main Database: "Lê e grava [SQL/TCP]"
• API Application → Payment Provider: "Cria e captura pagamentos [HTTPS]"
• API Application → Order Events Queue: "Publica eventos OrderPaid [AMQP]"
• Order Worker → Order Events Queue: "Consome eventos OrderPaid [AMQP]"
• API Application → E-book Store: "Assina links de download para arquivos de e-book [HTTPS]"
• Order Worker → Fulfilment System: "Envia pedidos impressos [JSON/HTTPS]"
• Order Worker → Email Service: "Envia e-mails de confirmação [HTTPS]"

Para quem: engenheiros, arquitetos e SREs. No dia a dia, costuma ser o diagrama C4 mais útil: o que você projeta numa design review ou entrega para quem acabou de entrar no time. Repare no que não aparece: Pods, VPCs, load balancers. O lugar deles é o diagrama de implantação.

Nível 3: diagrama de componentes

Dê zoom em um único contêiner, a API Application. Nem todo contêiner precisa de um diagrama de componentes; desenhe onde o interior merece explicação.

• Catalogue Controller (controller REST Spring MVC): endpoints de busca e detalhe do livro.
• Checkout Controller (controller REST Spring MVC): endpoints de carrinho e checkout.
• Order Service (service Spring): valida carrinhos, cria pedidos, publica eventos.
• Payment Gateway Client (component Spring): encapsula a API do provedor de pagamentos.
• Order Repository (Spring Data JPA): persiste pedidos.
• Catalogue Repository (Spring Data JPA): lê livros, preços e estoque.

As relações seguem a mesma regra do nível 2, por exemplo Order Service → Payment Gateway Client "Solicita a captura do pagamento" e Order Repository → Main Database "[SQL/TCP]".

Para quem: os devs donos daquele contêiner. Diagramas de componentes são os que ficam desatualizados mais rápido.

Nível 4, Code: não desenhe à mão. Gere diagramas de classes pela sua IDE quando precisar.

Dicas de notação para diagramas C4 legíveis

• Toda caixa tem quatro coisas: nome, tipo de elemento, tecnologia e uma responsabilidade em uma linha.

API Application
[Container: Java, Spring Boot]
Provides catalogue, ordering and account functionality via a JSON/HTTPS API.

• Rotule toda relação com a intenção e, a partir do nível 2, com o protocolo. Uma seta que só diz "Usa" não informa nada.
• Uma direção por seta, descrita do ponto de vista da origem.
• Adicione uma legenda explicando formas, cores, estilos de linha e siglas. Uma linha tracejada não significa nada até você dizer o que ela significa.
• Dê um título a cada diagrama com tipo e escopo, por exemplo "Diagrama de contêineres: Folio".
• Desenhe a boundary do sistema no escopo, para ficar claro o que é seu e o que você chama.

Erros comuns

1. Pular direto para os componentes. Sem visão de contexto e de contêineres, ninguém sabe onde um componente vive nem por que ele existe.
2. Misturar níveis. Uma Person, um Pod e uma classe Java no mesmo diagrama: nenhum fica bem explicado.
3. Setas sem rótulo. Sem intenção nem protocolo, o leitor precisa adivinhar, e cada um adivinha diferente.
4. Desenhar o nível Code à mão. Fica desatualizado no dia seguinte.
5. Infraestrutura no diagrama de contêineres. Namespaces, sub-redes e tipos de instância vão no diagrama de implantação.

Diagramas complementares: implantação e dinâmico

O C4 também define visões de apoio. Duas são especialmente úteis:

• Diagrama de implantação (deployment): mapeia os contêineres na infraestrutura. Na Folio, poderia ser a API Application e o Order Worker rodando como Deployments em um cluster Kubernetes, o PostgreSQL como banco gerenciado e o E-book Store em object storage. É aqui que entram os detalhes de Kubernetes e nuvem.
• Diagrama dinâmico: mostra um fluxo específico em passos numerados, por exemplo "Cliente compra um e-book": 1) o Storefront envia o checkout, 2) a API captura o pagamento, 3) a API publica OrderPaid, 4) o worker envia o e-mail com o link de download.

Como montar este exemplo de diagrama do modelo C4 no Archboard

O Archboard tem um pack C4 Model com nós Person, Software System, Container, Component e Database, além de boundaries. São nós de primeira classe com portas, não formas genéricas, então as relações conectam porta a porta.

1. Entre com Google ou GitHub e crie um diagrama.
2. Nível 1: coloque dois nós Person (Customer, Back-office Staff), um nó Software System para a Folio e três nós External System para os sistemas de pagamento, e-mail e fulfillment. Conecte as portas e rotule cada ligação com a intenção.
3. Nível 2: adicione uma boundary para a Folio e coloque nós Container para Web Storefront, Admin Portal, API Application, Order Worker, Order Events Queue e E-book Store, mais um nó Database para a Main Database. Preencha nome, tecnologia e responsabilidade e rotule as ligações com intenção e protocolo.
4. Nível 3: adicione uma boundary para a API Application e coloque os nós Component dentro dela.
5. Legenda e notas: use um bloco Markdown ou uma Table dos elementos Core para a legenda, e um Frame para manter cada nível na sua própria área do canvas infinito.
6. Visão de implantação ao lado: as visões C4 podem ficar no mesmo canvas que os packs Kubernetes e Cloud. Desenhe um frame Namespace com nós Deployment, Service e Ingress para a API Application e o Order Worker, logo ao lado da visão de contêineres que eles implementam.

Como o Archboard é um canvas, você desenha cada visão de forma deliberada: decide o que entra em cada nível, e os nós C4 ficam no mesmo board ao lado dos nós dos packs Kubernetes e Cloud. Assim, a visão de implantação fica logo ao lado da visão de contêineres.

No plano Free, um diagrama comporta 15 nós de diagrama mais 150 notas, textos, figurinhas e tópicos de mapa mental, o que basta para um nível C4 por diagrama em um sistema como a Folio. O Pro remove os limites de nós e diagramas se você quiser todos os níveis em um único canvas. Mais sobre fluxos de trabalho com C4: caso de uso C4.

Template gratuito

O exemplo de visão de contêineres C4 é um diagrama público que você pode copiar para o seu espaço de trabalho com Usar este exemplo. Use-o para o layout das boundaries e depois rotule cada ligação com intenção e protocolo, como descrito acima.

Perguntas frequentes

Preciso dos quatro níveis? Não. A maioria dos times tira o maior valor dos diagramas de contexto e de contêineres. Adicione diagramas de componentes de forma seletiva e gere visões de código só se precisar.

Um container do C4 é um contêiner Docker? Não. É qualquer unidade executada ou implantada separadamente, incluindo bancos de dados e SPAs. Pode rodar em Docker ou não.

Onde ficam os detalhes de Kubernetes? No diagrama de implantação. O diagrama de contêineres fica focado em responsabilidades e comunicação.

Comece grátis — um assento, sem cartão de crédito