Introdução ao Modelo C4 para Arquitetura de Software
Ainda me lembro da sessão de whiteboard que me fez repensar tudo sobre diagramas de arquitetura. Estávamos fazendo onboarding de uma nova desenvolvedora, e passei 45 minutos desenhando caixas e setas tentando explicar nossa plataforma de e-commerce. No final, ela parecia mais confusa do que quando começamos. O diagrama tinha tudo — microsserviços, bancos de dados, filas de mensagem, APIs externas — tudo amontoado com notação inconsistente e sem hierarquia clara.
Naquela noite, encontrei o modelo C4 de Simon Brown, e foi um daqueles momentos de "por que eu não pensei nisso?". A ideia é enganosamente simples: ao invés de amontoar tudo em um único diagrama, você cria múltiplos diagramas em diferentes níveis de zoom. Como o Google Maps, você começa com a visão ampla para ver o panorama geral e depois faz zoom progressivamente para ver mais detalhes.
Os Quatro Níveis do C4
O "C4" representa quatro níveis de abstração, cada um respondendo perguntas diferentes:
Nível 1: Contexto do Sistema
Esta é a visão de 10.000 metros de altitude. Todo o seu sistema é uma única caixa, e você mostra:
- Quem usa seu sistema (pessoas ou papéis)
- Com quais sistemas externos você integra
Só isso. Sem detalhes internos, sem escolhas tecnológicas, sem bancos de dados. Apenas "aqui está nosso sistema, aqui está quem o usa, e aqui está com o que ele se comunica."
Quando desenhei pela primeira vez um diagrama de Contexto do Sistema para nossa plataforma, ele coube em um único slide. Nosso CEO conseguiu entender. Isso nunca tinha acontecido antes com meus diagramas de arquitetura.
O que torna este nível poderoso: ele te força a pensar sobre fronteiras. O que está dentro do seu sistema versus o que está fora? O que você controla versus do que depende? Essas perguntas parecem óbvias, mas já vi equipes lutando para respondê-las claramente.
Nível 2: Diagrama de Container
Agora fazemos zoom de um nível. Um "container" na terminologia C4 não é um container Docker — é qualquer unidade implantável que executa código ou armazena dados:
- Aplicações web
- Apps mobile
- Serviços backend
- Bancos de dados
- Filas de mensagens
- Armazenamento de arquivos
Este diagrama mostra a arquitetura técnica de alto nível. Você pode ver as principais escolhas tecnológicas (frontend React, backend Go, banco de dados PostgreSQL) e como os dados fluem entre eles.
Acho este nível mais útil para:
- Planejar infraestrutura e deploys
- Discutir escolhas tecnológicas com a equipe
- Explicar o sistema para novos desenvolvedores backend ou frontend
Uma coisa que aprendi: tenha cuidado com a granularidade aqui. Se você tem 30 microsserviços, não mostre todos os 30 como containers separados. Agrupe serviços relacionados ou crie múltiplos diagramas de Container para diferentes áreas do seu sistema.
Nível 3: Diagrama de Componentes
Aqui fazemos zoom em um único container. Componentes são os principais blocos de construção estruturais dentro daquele container — pense em serviços, repositórios, controllers ou módulos.
Para nosso backend Go, um diagrama de Componentes poderia mostrar:
- Handlers HTTP
- Serviços de lógica de negócio
- Interfaces de repositório
- Clientes de API externa
Sou honesto: não crio diagramas de Componentes para cada container. Apenas para os complexos que novos desenvolvedores têm dificuldade de entender. Para um serviço CRUD simples, o próprio código é a documentação.
Nível 4: Diagrama de Código
O nível mais profundo mostra elementos reais de código — classes, interfaces, funções. O próprio Simon Brown diz que este nível é opcional e frequentemente gerado automaticamente a partir do código.
Na prática, raramente crio diagramas de Código manualmente. Quando faço, é para algoritmos ou padrões particularmente complexos que se beneficiam de explicação visual. Na maioria das vezes, se você precisa desse nível de detalhe, deveria estar lendo o código real.
Por Que o C4 Funcionou Para Nossa Equipe
Antes do C4, nossa documentação de arquitetura era uma bagunça. Tínhamos:
- Diagramas Visio de 2019 que ninguém atualizava
- Fotos de whiteboard em canais aleatórios do Slack
- Arquivos README com arte ASCII que meio que explicavam as coisas
- Conhecimento tribal que ia embora quando as pessoas saíam
O modelo C4 nos deu um framework que realmente funciona. Eis por quê:
É simples o bastante para lembrar
Quatro níveis. Só isso. Sem necessidade de memorizar 14 tipos diferentes de diagrama UML ou discutir se algo deveria ser um "componente" ou um "módulo" no sentido UML.
Diferentes públicos, diferentes diagramas
Nosso CEO olha o diagrama de Contexto do Sistema. Nossos arquitetos discutem o diagrama de Container. Nossos desenvolvedores trabalham com diagramas de Componentes. Cada um recebe o nível certo de detalhe para suas necessidades.
Ele se mantém atualizado
Como os diagramas C4 são relativamente simples, não é doloroso atualizá-los. Quando adicionamos uma nova integração externa, atualizar o diagrama de Contexto do Sistema leva 5 minutos. Compare isso com atualizar um diagrama UML detalhado com cada classe e método.
É agnóstico de ferramenta
Começamos com draw.io, migramos para Miro para colaboração, e agora usamos Archyl para diagramação assistida por IA. O modelo C4 funciona com qualquer ferramenta porque é sobre os conceitos, não sobre a notação.
Erros Comuns Que Cometi (Para Que Você Não Cometa)
Erro 1: Mostrar muitos detalhes cedo demais
Meu primeiro diagrama de Container tinha 47 caixas. Era preciso mas inútil. Agora sigo uma regra: se seu diagrama não cabe em uma tela, você está no nível de zoom errado.
Erro 2: Esquecer os relacionamentos
Um diagrama com caixas mas sem setas é apenas um inventário. Os relacionamentos — quem chama quem, que dados fluem para onde — são frequentemente mais importantes que as próprias caixas. Rotule suas setas. Descreva os protocolos e formatos de dados.
Erro 3: Não atualizar após mudanças
O melhor diagrama é inútil se descreve o sistema de dois anos atrás. Resolvemos isso fazendo atualizações de diagrama parte do nosso checklist de PR para mudanças arquiteturais. Não é perfeito, mas ajuda.
Erro 4: Complicar demais a notação
Passei uma semana projetando ícones personalizados e esquemas de cores para nossos diagramas C4. Perda total de tempo. Caixas simples com labels claros funcionam bem. Foque no conteúdo, não na estética.
Começando
Se você é novo no C4, aqui está o que eu sugeriria:
Comece com o Contexto do Sistema. Reserve 30 minutos para desenhar seu sistema como uma única caixa, cercada pelos usuários e sistemas externos. Isso sozinho já tem valor.
Adicione um diagrama de Container. Escolha seu sistema mais complexo e decomponha-o em unidades implantáveis. Mostre como eles se comunicam.
Pare aí por agora. Não tente documentar tudo de uma vez. Deixe os diagramas provarem seu valor antes de investir mais tempo.
Torne colaborativo. Compartilhe os diagramas com sua equipe. Receba feedback. Documentação de arquitetura não deveria ser uma atividade solo.
Como Usamos C4 no Archyl
Ao construir o Archyl, obviamente usamos nosso próprio produto. Nossa documentação de arquitetura usa C4 em toda parte:
- O diagrama de Contexto do Sistema mostra o Archyl conectando-se a vários provedores git, serviços de IA e sistemas de pagamento
- Diagramas de Container decompõem o backend Go e o frontend React
- Diagramas de Componentes detalham o serviço de descoberta e o mecanismo de renderização de diagramas
O que é poderoso é vincular esses diagramas a outra documentação. Um Architecture Decision Record sobre escolher PostgreSQL ao invés de MongoDB linka diretamente ao container do banco de dados no nosso diagrama de Container. Fluxos de usuário referenciam os componentes específicos que atravessam.
Essa documentação interconectada é o que estamos construindo no Archyl — a capacidade de ver sua arquitetura não como diagramas isolados, mas como um grafo de conhecimento conectado.
Conclusão
O modelo C4 não é revolucionário em seus conceitos. Níveis de abstração e decomposição hierárquica existem há muito tempo. O que Simon Brown fez brilhantemente foi empacotar essas ideias em um framework simples e memorável que realmente é usado.
Se sua documentação de arquitetura é uma bagunça de arquivos Visio desatualizados e fotos de whiteboard, experimente o C4. Comece pequeno, com apenas um diagrama de Contexto do Sistema. Você pode se surpreender com quanta clareza um único diagrama bem pensado pode trazer.
Este é parte da nossa série sobre documentação de arquitetura. A seguir: Como a IA pode descobrir automaticamente sua arquitetura e Por que a documentação importa mais do que você pensa.