O que é o C4 Model?
O C4 Model é uma técnica de documentação visual de arquitetura de software que enxerga um sistema em quatro níveis progressivos de detalhe: Contexto, Contêineres, Componentes e Código. Cada nível é como dar um zoom no mapa: você começa vendo o país, depois a cidade, depois o bairro, depois a rua.
A grande ideia é substituir dezenas de diagramas UML dispersos por uma hierarquia consistente que qualquer pessoa técnica consegue ler em minutos. O modelo é gratuito, aberto e ferramenta-agnóstico: você pode desenhar em quadro branco, em ferramenta visual, ou (recomendado) como código versionado.
Os 4 níveis do C4 Model
Nível 1 — Diagrama de Contexto
Mostra o sistema como uma caixa preta no meio do mundo. Quem usa? Com quais sistemas externos conversa? É o diagrama que você mostra pro time de negócio, pro board, pra qualquer não-engenheiro que precisa entender onde o software vive.
Regra prática: se o diagrama de contexto exige que alguém abra a legenda para entender, ele já falhou.
Nível 2 — Diagrama de Contêineres
Abre a caixa preta. Aqui aparecem as aplicações que compõem o sistema: front-end SPA, API REST, worker de fila, banco de dados, cache. Um contêiner é qualquer unidade que pode ser deployada de forma independente.
Esse é o nível mais valioso do C4 para o dia-a-dia: onboarding de novos devs, planejamento de mudanças e revisões de segurança geralmente vivem aqui.
Nível 3 — Diagrama de Componentes
Abre um contêiner específico e mostra suas peças internas: controllers, services, repositories, adapters. Útil quando um contêiner é grande o suficiente para justificar arquitetura interna documentada.
Nível 4 — Código
Diagramas de classe/UML gerados diretamente do código. Simon Brown recomenda não desenhar esse nível à mão: gere sob demanda a partir do código-fonte, se precisar.
Quando usar C4 Model (e quando não usar)
Use quando:
- Você precisa explicar o sistema para stakeholders não-técnicos (nível 1).
- Está desenhando um sistema novo e quer alinhar o time em containers.
- Precisa de documentação de arquitetura para auditoria (SOC2, ISO 27001, LGPD).
- Quer padronizar a documentação entre múltiplas squads da mesma empresa.
Talvez não valha a pena quando:
- Seu sistema é um monólito simples com 1-2 contêineres.
- O time é pequeno (2-3 pessoas) e a comunicação síncrona já resolve.
C4 Model como código: por que versionar seus diagramas
O problema clássico do C4 desenhado em ferramenta visual: em 6 meses o diagrama está desatualizado. A produção mudou, o diagrama ficou. Isso é o que a comunidade chama de architecture drift.
A solução é tratar o diagrama como código: você descreve os contêineres e relações em um arquivo declarativo, versiona no Git junto com o código-fonte, e o diagrama é renderizado automaticamente. Mudou de banco? PR no diagrama. Revisão obrigatória.
Foi exatamente esse problema que o Excahub nasceu para resolver. A sintaxe ExcaFlow deixa você descrever seu sistema em nível de contêiner (C4 nível 2), renderiza o canvas automaticamente e ainda gera README, dicionário de dados e mapa de dependências a partir do mesmo arquivo. Cada commit é uma versão auditável da sua arquitetura.
Perguntas frequentes sobre C4 Model
C4 Model substitui UML?
Substitui na prática, sim. UML tem 14+ tipos de diagrama que quase ninguém domina. C4 tem 4 níveis com notação livre. Você pode desenhar C4 usando qualquer estilo visual, inclusive elementos UML se fizer sentido.
Qual a diferença entre C4 e Arc42?
Arc42 é um template de documento (12 seções: contexto, restrições, decisões, riscos, etc). C4 é uma notação visual. Times maduros usam os dois juntos: Arc42 como estrutura do documento e C4 para os diagramas dentro dele.
Preciso desenhar os 4 níveis?
Não. A maioria dos times para no nível 2 (contêineres). O nível 3 aparece só em contêineres críticos. O nível 4 raramente vale o esforço manual.
Onde posso criar diagramas C4?
Você pode usar ferramentas visuais (arrastar-e-soltar), ou ferramentas de diagram-as-code que geram o C4 automaticamente a partir de um arquivo texto. A vantagem da segunda abordagem é que o diagrama vive no Git, entra em PR e não fica desatualizado.