arc42 vs modelo C4: diferenças e como combiná-los

Alguém na sua equipe propõe o arc42 para a documentação de arquitetura. Outra pessoa diz que a equipe já usa C4. A discussão que vem depois geralmente parte do princípio de que é preciso escolher um, e essa é a primeira premissa a abandonar.

Comparar arc42 e C4 é um pouco como comparar o roteiro de um relatório com os gráficos que vão dentro dele. O arc42 é um template: doze seções que dizem o que documentar sobre uma arquitetura, dos objetivos de qualidade aos riscos. O C4 é um modelo e uma notação: quatro níveis de diagramas que dizem como desenhar a estrutura de um sistema de software. Eles se sobrepõem em alguns pontos e combinam bem. Este guia mostra o que cada um cobre, o que o arc42 pede que o C4 não desenha, o que o C4 acrescenta ao arc42 e um mapeamento seção por seção de qual diagrama C4 vai onde.

A resposta em uma linha

O arc42 é um template para documentação de arquitetura. O modelo C4 é uma forma de desenhar diagramas de arquitetura de software. A maioria das equipes que usa os dois coloca diagramas C4 dentro das seções do arc42.

O próprio FAQ do arc42 descreve a relação assim. À pergunta "E quanto ao arc42 e ao C4?", ele responde que o modelo C4 "tem muitas semelhanças com algumas seções do arc42, mas omite certas partes (por exemplo, requisitos de qualidade, conceitos transversais, riscos e algumas outras)" (FAQ do arc42, B-17). O mesmo FAQ lista o modelo C4 de Simon Brown entre as alternativas ao arc42 (A-6), o que é verdade se você só precisa de diagramas, e enganoso se você precisa de tudo o mais que um documento contém.

As doze seções do arc42

Antes de mapear qualquer coisa, ajuda ter as seções à sua frente com os números exatos. Elas vêm da documentação do arc42, versão 9.0 do template (julho de 2025, segundo a página de download):

Há mais uma coisa sobre a qual o arc42 é explícito: você não preenche tudo. O FAQ responde a "quais partes são essenciais?" com "Por favor, não preencha tudo. Documente apenas o que seus stakeholders precisam", porque tudo o que você escreve "pode exigir esforço de manutenção no futuro" (B-1). Esse conselho importa para a combinação mais abaixo. Um documento arc42 enxuto com bons diagramas C4 em três seções vale mais do que um completo que ninguém atualiza.

O que o arc42 cobre e o C4 não

O C4 trata de estrutura e, por meio dos diagramas suplementares, de runtime e deployment. Ele não diz nada sobre as partes de uma arquitetura que não são caixas. Em termos de arc42, estas seções não têm nenhum equivalente no C4:

• Seção 1, Introdução e objetivos. Por que o sistema existe, quem se importa com ele e os três a cinco objetivos de qualidade que orientam todas as decisões seguintes. Um diagrama de contexto C4 mostra quem usa o sistema. Ele não consegue dizer que "um checkout precisa terminar em menos de dois segundos" importa mais do que "a UI de administração é bonita".
• Seção 2, Restrições. "Precisa rodar na plataforma Kubernetes da empresa", "precisa ser escrito em Java", "os dados não podem sair da UE". As restrições explicam escolhas que um diagrama apenas exibe.
• Seção 4, Estratégia da solução. O punhado de escolhas fundamentais (monólito primeiro, event sourcing para o ledger, comprar o motor de busca) resumido em um só lugar.
• Seção 8, Conceitos transversais. Autenticação, tratamento de erros, logging, padrões de persistência, internacionalização. Eles atravessam todas as caixas, então nenhuma caixa sozinha consegue mostrá-los.
• Seção 10, Requisitos de qualidade. Cenários de qualidade concretos: estímulo, resposta, medida.
• Seção 11, Riscos e dívida técnica. O que você sabe que é frágil e o que você adiou.
• Seção 12, Glossário. As palavras que o negócio usa, definidas uma única vez.

São exatamente as seções que o FAQ do arc42 cita quando diz que o C4 "omite certas partes". Se a sua documentação de arquitetura é feita só de diagramas C4, essas são as perguntas que um novo arquiteto ou um auditor ainda terá depois de lê-la.

O que o C4 acrescenta ao arc42

O arc42 deliberadamente não prescreve uma notação. A seção 5 pede uma "coleção hierárquica de caixas-pretas e caixas-brancas", a seção 3 sugere "todo tipo de diagrama que mostre o sistema como uma caixa-preta", e a seção 6 aceita de tudo, de uma lista numerada de passos a diagramas de sequência, BPMN ou máquinas de estado (seção 5, seção 3, seção 6). Essa flexibilidade é um ponto forte do template, e também é onde os documentos arc42 mais variam: cada autor desenha de um jeito.

O C4 preenche essa lacuna com duas coisas:

1. Um zoom consistente. A visão de blocos de construção do arc42 já tem níveis: o Nível 1 é "a descrição caixa-branca do sistema como um todo, junto com as descrições caixa-preta de todos os blocos de construção contidos", e o Nível 2 "dá zoom em alguns blocos de construção do nível 1" (seção 5). Os níveis do C4 dão a esses passos de zoom um significado fixo (sistema, container, componente, código), então um leitor que conhece C4 sabe o que está vendo antes mesmo de ler os rótulos.
2. Um pequeno vocabulário compartilhado. Pessoa, software system, container, componente, relacionamento, cada um com um nome, uma descrição e normalmente uma tecnologia. É notação suficiente para tornar os diagramas comparáveis entre equipes, e pouca o bastante para que ninguém precise de treinamento.

Há também um benefício prático. Se os diagramas C4 vêm de um modelo e não de uma ferramenta de desenho, o mesmo elemento aparece com o mesmo nome nas seções 3, 5, 6 e 7. O arc42 não opina sobre como conseguir isso, mas é o que faz as seções concordarem entre si.

Tabela de mapeamento: qual diagrama C4 vai em qual seção do arc42

Este mapeamento é nosso, derivado das definições das seções do arc42 e das definições dos diagramas C4. O FAQ do arc42 aponta para exemplos da comunidade que usam a combinação (por exemplo, o repositório de exemplo arc42 + C4 do bitsmuggler) em vez de prescrever um, e as equipes variam nos detalhes indicados na última coluna.

As seções que não estão na tabela (1, 2, 4, 8, 10, 11, 12) são texto e tabelas, não diagramas C4. Isso não é uma lacuna de nenhum dos métodos; é a divisão do trabalho.

Exemplo completo

Veja como fica a combinação para o sistema de e-commerce do nosso guia completo do modelo C4: uma single-page app em React, um API gateway, serviços em Go para pedidos, produtos e usuários, bancos PostgreSQL, Kafka e um notification service. É um esqueleto arc42 enxuto com os diagramas C4 no lugar, não um documento completo.

1. Introdução e objetivos
   - Propósito: clientes navegam e compram produtos; a equipe do depósito gerencia o estoque
   - Objetivos de qualidade: (1) o checkout termina em menos de 2 s no p95
                             (2) nenhum pedido é confirmado sem uma autorização de pagamento bem-sucedida
                             (3) um novo serviço pode ser adicionado sem alterar os existentes

2. Restrições
   - Roda na plataforma Kubernetes da empresa; Go para os serviços de backend

3. Contexto e escopo
   - Contexto de negócio: diagrama C4 System Context
     [Customer], [Warehouse Staff] -> [E-Commerce Platform]
     -> [Stripe], [FedEx API], [SendGrid]
   - Contexto técnico: tabela de parceiro / protocolo / dados trocados

4. Estratégia da solução
   - Um banco de dados por serviço; notificações assíncronas via Kafka

5. Visão de blocos de construção
   - Nível 1: diagrama C4 Container (SPA, API Gateway, serviços Order/Product/User,
     três bancos PostgreSQL, Kafka, Notification Service)
   - Nível 2: diagrama C4 Component apenas do Order Service
     (Order Handler, Order Service, Order Repository, Payment Client,
     Inventory Client)

6. Visão de runtime
   - "Cliente faz um pedido": diagrama dinâmico C4, 10 passos numerados

7. Visão de deployment
   - Produção: diagrama de deployment C4
   - Staging: apenas as diferenças em relação à produção

8. Conceitos transversais
   - Autenticação no gateway; chaves de idempotência em POST /orders;
     logging estruturado com um request ID

9. Decisões de arquitetura
   - ADR-001 Um banco de dados por serviço
   - ADR-002 Kafka para eventos de pedido em vez de chamadas síncronas
   - ADR-003 Autorizar o pagamento antes de gravar o pedido

10. Requisitos de qualidade
   - Cenário: 500 checkouts por minuto durante uma promoção, p95 abaixo de 2 s

11. Riscos e dívida técnica
   - O estoque é reservado antes do pagamento; ainda não há compensação quando o pagamento falha

12. Glossário
   - Pedido, Reserva, Autorização, Atendimento

Repare onde ficam os diagramas: seções 3, 5, 6 e 7. Todo o resto são algumas linhas de texto. Repare também como o risco da seção 11 e o ADR-003 da seção 9 se referem à mesma coisa que o diagrama dinâmico da seção 6 mostra. É nessa referência cruzada que um documento que combina arc42 e C4 mostra o seu valor: o diagrama mostra a ordem dos passos, o ADR diz por quê, e o risco diz o que ainda está errado.

Para o próprio diagrama dinâmico, o guia do diagrama dinâmico C4 percorre exatamente esse cenário passo a passo. Para a seção 9, o guia completo de architecture decision records cobre o formato que o arc42 recomenda e como manter um índice.

Se as doze seções do arc42 parecem mais do que a sua equipe precisa, o nosso template de documentação de arquitetura de software é um roteiro em markdown mais curto, construído com as mesmas ideias, com uma seção que explica como ele se relaciona com o arc42.

Mantendo os dois atualizados

arc42 e C4 compartilham o mesmo ponto fraco: ambos são excelentes no dia em que são escritos. O próprio FAQ do arc42 avisa que cada seção que você preenche é manutenção com a qual você se comprometeu (B-1). Alguns hábitos que funcionam:

• Mantenha os diagramas fora do corpo do documento sempre que possível. Referencie ou incorpore diagramas gerados a partir de um modelo em vez de colar capturas de tela. A captura de tela de um diagrama de containers fica desatualizada no dia em que um container é renomeado. Um diagrama renderizado a partir do modelo só fica tão desatualizado quanto o modelo.
• Coloque as seções que mudam rápido perto do código. As seções 5, 6 e 9 mudam com o código. As seções 1, 2 e 10 mudam com o negócio. Guardar o primeiro grupo no repositório (o arc42 oferece templates em Markdown e AsciiDoc para isso) significa que os pull requests podem atualizá-las.
• Escreva ADRs para frente, nunca os edite. Uma decisão substituída ganha um novo ADR. A seção 9 vira um histórico em vez de uma história reescrita.
• Dê a cada seção um dono e uma data de revisão. Um documento sem dono é um documento que ninguém atualiza.
• Confira as seções estruturais contra o código. As seções 3 e 5 descrevem coisas que existem no código, então podem ser verificadas automaticamente. As seções 1, 8 e 10 não podem; elas precisam de uma revisão humana, com periodicidade definida.

Esse último ponto é onde o archyl entra, e só para parte do problema. O archyl guarda o modelo C4, não um documento arc42. Sua descoberta por IA propõe sistemas, containers, componentes e relacionamentos a partir de um repositório para você aprovar, os ADRs se ligam aos elementos C4 que afetam, e um drift score verifica se os elementos documentados ainda existem no código. Isso cobre as seções mais carregadas de diagramas (3, 5, 6, 9). Ele não escreve seus objetivos de qualidade, seus conceitos transversais nem sua lista de riscos, e não há exportação para arc42; as seções de texto continuam no seu documento arc42, com links para o modelo.

FAQ

O arc42 é melhor que o C4?

Nenhum é melhor, porque eles não fazem o mesmo trabalho. O arc42 é um template de documentação que cobre objetivos, restrições, estrutura, runtime, deployment, decisões, qualidade e riscos. O C4 é uma forma de desenhar a estrutura de maneira consistente. Se você precisa de um documento de arquitetura completo, use o arc42 (ou algo com formato parecido). Se você precisa de diagramas consistentes, use o C4. A maioria das equipes que precisa dos dois usa diagramas C4 dentro do arc42.

Dá para usar arc42 e C4 juntos?

Sim, e é comum. O arc42 não prescreve uma notação, então os diagramas C4 se encaixam diretamente nas suas seções: o diagrama de contexto na seção 3, os diagramas de containers e de componentes na seção 5, os diagramas dinâmicos na seção 6 e os diagramas de deployment na seção 7.

Onde o diagrama de containers C4 entra no arc42?

Na seção 5, Visão de blocos de construção, no Nível 1: a visão caixa-branca do sistema inteiro. Os diagramas de componentes entram no Nível 2 para os containers que precisam deles. Se o seu sistema é um monólito modular, os blocos de construção do Nível 1 podem ser módulos em vez de containers, e o encaixe é menos preciso.

O arc42 exige UML?

Não. O arc42 sugere notações em várias seções (a seção 3, por exemplo, menciona um diagrama de deployment UML para o contexto técnico), mas deixa a escolha com você. C4, UML e simples caixas e setas são todos usados com ele.

Onde ficam os ADRs no arc42?

Na seção 9, Decisões de arquitetura. O próprio arc42 recomenda um ADR para cada decisão importante, na estrutura de Michael Nygard, e permite documentar uma decisão localmente no bloco de construção que ela afeta, se isso ficar mais legível.

O arc42 é gratuito?

Sim. O template é gratuito e open source, com licença CC BY-SA 4.0, e está disponível em doze idiomas e em formatos como AsciiDoc, Markdown, Word e Confluence (página de download).

Quer que a metade C4 do seu documento arc42 continue fiel ao código? Experimente o archyl grátis e gere o modelo a partir do seu repositório. Continue lendo: O que é o modelo C4? Um guia completo | Architecture Decision Records: o guia completo | Guia do diagrama dinâmico C4 | Template de documentação de arquitetura de software.