O Que é o Modelo C4? Um Guia Completo para Equipes de Software

Diagramas de arquitetura de software têm um problema de reputação. São abstratos demais para serem úteis ou detalhados demais para serem mantidos. Você provavelmente já viu ambos: o diagrama de uma única caixa rotulada "O Sistema" que não diz nada, e o extenso diagrama UML com 200 classes que diz tudo exceto o que você realmente precisa saber.

O modelo C4, criado por Simon Brown, resolve isso emprestando uma ideia da cartografia. Mapas funcionam em múltiplos níveis de zoom. Você começa com um mapa-múndi para se orientar, depois faz zoom em um país, depois uma cidade, depois uma rua. Cada nível mostra a quantidade certa de detalhe para as perguntas que você está fazendo. O modelo C4 aplica esse mesmo princípio à arquitetura de software.

Neste guia, vamos percorrer tudo que você precisa saber sobre o modelo C4: o que cada nível representa, quando usá-lo, armadilhas comuns e como equipes modernas implementam C4 na prática.

O Que Significa C4?

C4 representa os quatro níveis de abstração que o modelo define:

1. Context (Contexto) -- O panorama geral. Como seu sistema se encaixa no mundo.
2. Containers -- Os blocos técnicos de alto nível do seu sistema.
3. Components (Componentes) -- A estrutura interna de cada container.
4. Code (Código) -- Os detalhes reais de implementação.

Cada nível responde perguntas diferentes para públicos diferentes. Um product manager se preocupa com o Contexto. Um engenheiro de plataforma se preocupa com os Containers. Um desenvolvedor trabalhando em um serviço específico se preocupa com os Componentes. Ninguém realmente precisa do nível de Código desenhado à mão -- mais sobre isso adiante.

O poder do C4 não está em nenhum diagrama individual. Está na hierarquia. Todo elemento em um nível se decompõe em um diagrama no nível seguinte. Uma caixa rotulada "Backend API" no diagrama de Container se torna seu próprio diagrama de Componentes mostrando os módulos internos. Isso cria uma visão navegável e "zoomável" da sua arquitetura.

Nível 1: Diagrama de Contexto do Sistema

O diagrama de Contexto do Sistema é o ponto de partida para qualquer modelo C4. Ele responde uma pergunta: como seu sistema se encaixa no ambiente mais amplo?

O Que Ele Mostra

• Seu sistema de software como uma única caixa no centro
• As pessoas (atores, papéis, personas) que o utilizam
• Os sistemas externos com os quais ele se integra
• Os relacionamentos entre todos eles

O Que Ele Não Mostra

• Estrutura interna do seu sistema
• Escolhas tecnológicas
• Bancos de dados, filas ou infraestrutura
• Detalhes de deployment

Um Exemplo Real

Imagine que você está documentando uma plataforma de e-commerce. Seu diagrama de Contexto do Sistema mostraria:

[Cliente] --> [Plataforma E-Commerce] : Navega produtos, faz pedidos
[Equipe do Armazém] --> [Plataforma E-Commerce] : Gerencia estoque
[Plataforma E-Commerce] --> [Gateway de Pagamento (Stripe)] : Processa pagamentos
[Plataforma E-Commerce] --> [Provedor de Frete (FedEx API)] : Cria envios
[Plataforma E-Commerce] --> [Serviço de Email (SendGrid)] : Envia notificações

Cinco usuários e sistemas externos. Uma caixa para toda a sua plataforma. Só isso.

Por Que Este Nível Importa

O diagrama de Contexto do Sistema força clareza sobre fronteiras. O que você possui? Do que você depende? Quem são seus usuários? Essas perguntas parecem óbvias, mas equipes regularmente têm dificuldade em respondê-las de forma consistente.

Este diagrama também é o que você mostra para stakeholders não técnicos. Seu CEO pode olhá-lo e entender o que o sistema faz, quem o utiliza e de quais serviços terceiros ele depende. Tente fazer isso com um diagrama de classes UML.

Dicas para um Bom Diagrama de Contexto do Sistema

• Mantenha em uma página. Se não couber, sua fronteira de sistema pode estar errada.
• Rotule cada relacionamento com uma frase verbal: "envia emails via", "processa pagamentos através de", "lê estoque de."
• Inclua todos os sistemas externos, mesmo os que você dá como garantidos (DNS, CDN, monitoramento).
• Não inclua detalhes internos. Resista à tentação.

Nível 2: Diagrama de Container

O diagrama de Container faz zoom no seu sistema e mostra seus blocos técnicos de alto nível. Na terminologia C4, um "container" é qualquer unidade separadamente implantável ou executável -- não necessariamente um container Docker.

O Que Conta como Container

• Uma aplicação web (React SPA, app Next.js)
• Uma aplicação mobile (app iOS, app Android)
• Um serviço de API backend (API Go, servidor Node.js)
• Um banco de dados (PostgreSQL, MongoDB, Redis)
• Um message broker (Kafka, RabbitMQ)
• Um sistema de armazenamento de arquivos (S3, MinIO)
• Uma função serverless (AWS Lambda, Cloud Functions)

Cada container roda em seu próprio processo ou tem seu próprio armazenamento de dados. Esse é o fator diferenciador. Dois pacotes Go implantados juntos fazem parte do mesmo container. Dois serviços Go implantados independentemente são containers separados.

Um Exemplo Real

Fazendo zoom na nossa plataforma de e-commerce:

[Single-Page Application (React)] --> [API Gateway (Kong)] : Faz chamadas API (HTTPS/JSON)
[API Gateway] --> [Order Service (Go)] : Roteia requisições
[API Gateway] --> [Product Service (Go)] : Roteia requisições
[API Gateway] --> [User Service (Go)] : Roteia requisições
[Order Service] --> [Order Database (PostgreSQL)] : Lê/escreve pedidos
[Product Service] --> [Product Database (PostgreSQL)] : Lê/escreve produtos
[User Service] --> [User Database (PostgreSQL)] : Lê/escreve usuários
[Order Service] --> [Message Queue (Kafka)] : Publica eventos de pedidos
[Notification Service (Go)] --> [Message Queue] : Consome eventos de pedidos

Agora você pode ver as escolhas tecnológicas, os padrões de comunicação e os armazenamentos de dados. Um arquiteto pode discutir se deve unificar os bancos de dados de Pedidos e Produtos. Um engenheiro de DevOps pode planejar a topologia de deployment. Um novo desenvolvedor pode entender onde o frontend React termina e o backend Go começa.

Dicas para um Bom Diagrama de Container

• Inclua a tecnologia entre parênteses: "Order Service (Go)", "Database (PostgreSQL)".
• Mostre o protocolo de comunicação nos relacionamentos: "HTTPS/JSON", "gRPC", "AMQP".
• Se você tem mais de 15-20 containers, crie múltiplos diagramas de Container para diferentes subsistemas.
• Inclua bancos de dados e filas. Eles também são containers.
• Não desça abaixo do nível de container aqui. Módulos internos pertencem ao diagrama de Componentes.

Nível 3: Diagrama de Componentes

O diagrama de Componentes faz zoom em um único container e mostra seus blocos internos de construção estrutural. Componentes são as principais abstrações dentro de um container -- pense em pacotes, módulos, serviços ou camadas.

O Que Conta como Componente

• Um handler ou controller HTTP
• Um serviço de lógica de negócio
• Um repositório ou camada de acesso a dados
• Um cliente de API externa
• Um processador de jobs em background
• Um middleware ou interceptor

Componentes são agrupamentos lógicos, não necessariamente arquivos individuais. O componente OrderHandler pode ser implementado em vários arquivos, mas conceitualmente é uma coisa só: a parte do sistema que lida com requisições HTTP relacionadas a pedidos.

Um Exemplo Real

Fazendo zoom no container Order Service:

[Order Handler] --> [Order Service] : Delega lógica de negócio
[Order Service] --> [Order Repository] : Persiste pedidos
[Order Service] --> [Payment Client] : Valida pagamento
[Order Service] --> [Inventory Client] : Verifica disponibilidade de estoque
[Order Repository] --> [Order Database (PostgreSQL)] : Consultas SQL
[Payment Client] --> [Payment Gateway (Stripe)] : HTTPS/REST
[Inventory Client] --> [Product Service] : gRPC

Um desenvolvedor entrando nessa equipe pode ver imediatamente como o Order Service está estruturado: requisições entram pelo handler, a lógica de negócio vive no service, o acesso a dados passa pelo repository e chamadas externas passam por clients dedicados.

Quando Criar Diagramas de Componentes

Nem todo container precisa de um diagrama de Componentes. Crie um quando:

• O container é complexo o suficiente para que um novo desenvolvedor tenha dificuldade em navegar nele
• Há padrões de design importantes (arquitetura hexagonal, CQRS) que o diagrama pode tornar explícitos
• Múltiplas equipes contribuem para o mesmo container e precisam de um entendimento compartilhado da sua estrutura

Pule o diagrama de Componentes quando:

• O container é simples (um serviço CRUD com três endpoints)
• A estrutura do código é óbvia pela organização de pastas
• O container é uma ferramenta de terceiros (Redis, Kafka) onde você não controla os internos

Nível 4: Diagrama de Código

O nível de Código mostra os detalhes reais de implementação: classes, interfaces, funções e seus relacionamentos. Isso é essencialmente um diagrama de classes UML ou um diagrama de entidade-relacionamento.

A Verdade Sobre o Nível 4

O próprio Simon Brown desaconselha criar diagramas de Código manualmente. Eis por quê:

• Eles mudam com muita frequência. Todo refatoramento os invalida.
• São caros de manter. Desenhar diagramas de classes à mão é tedioso.
• Duplicam informação que já existe no código.
• IDEs modernas podem gerá-los sob demanda.

Se você precisa de diagramas no nível de Código, gere-os a partir do seu código-fonte usando ferramentas que suportam sua linguagem. Não os desenhe à mão.

Quando Diagramas de Código Realmente Ajudam

Existem exceções:

• Algoritmos complexos que se beneficiam de uma explicação visual
• Design patterns (Strategy, Observer, State Machine) onde a estrutura é a parte interessante
• Superfícies de API pública onde você quer documentar os contratos
• Materiais de entrevista ou onboarding onde você está ensinando padrões

Na prática, a maioria das equipes usa três níveis do C4 (Contexto, Container, Componente) e deixa o nível de Código para visualizações geradas pela IDE.

Os Diagramas Suplementares

Além dos quatro níveis principais, Simon Brown define vários diagramas suplementares que complementam a hierarquia C4:

Diagrama de Paisagem do Sistema

Um diagrama de Contexto do Sistema com zoom ainda mais amplo. Ele mostra todos os sistemas de software em uma empresa e como eles se relacionam. Útil para arquitetos enterprise que gerenciam um portfólio de sistemas.

Diagrama de Deployment

Mapeia containers para infraestrutura. Mostra quais containers rodam em quais servidores, em quais regiões de cloud, atrás de quais load balancers. Essencial para equipes de DevOps e plataforma.

Diagrama Dinâmico

Mostra como elementos colaboram em tempo de execução para atender um caso de uso específico. Similar a um diagrama de sequência UML mas usando notação C4. Útil para documentar fluxos complexos como "o que acontece quando um usuário faz um pedido."

Modelo C4 vs. Outras Abordagens

C4 vs. UML

UML define 14 tipos de diagrama. A maioria das equipes usa 2-3 deles, e frequentemente de forma inconsistente. C4 te dá 4 níveis com propósitos claros. É mais simples de aprender, mais simples de usar e mais simples de manter.

Dito isso, C4 e UML não são mutuamente exclusivos. Você pode usar diagramas de classes UML no Nível 4, ou diagramas de sequência UML como diagramas Dinâmicos. C4 fornece a hierarquia; UML fornece notações específicas quando você precisa delas.

C4 vs. Arc42

Arc42 é um template para documentação de arquitetura. Ele cobre muito mais do que apenas diagramas: requisitos de qualidade, restrições, riscos, visões de deployment e mais. C4 foca especificamente em diagramas hierárquicos. Muitas equipes usam ambos: Arc42 como estrutura de documentação e C4 como abordagem de diagramação dentro dele.

C4 vs. "Só Use um Whiteboard"

Whiteboards são ótimos para exploração e brainstorming. São terríveis para documentação. Diagramas de whiteboard são apagados, fotografados mal e nunca atualizados. C4 fornece a estrutura para transformar explorações de whiteboard em documentação duradoura.

Erros Comuns ao Adotar C4

Tentar Mostrar Tudo de Uma Vez

O ponto central do C4 é a revelação progressiva. Se seu diagrama de Container mostra classes individuais, você colapsou a hierarquia. Cada diagrama deve mostrar elementos em um único nível de zoom.

Ignorar Relacionamentos

Caixas sem setas são um inventário, não arquitetura. Os relacionamentos -- quem chama quem, que protocolo usam, que dados fluem entre eles -- são frequentemente mais valiosos que as próprias caixas. Sempre rotule seus relacionamentos.

Tornar uma Atividade de Uma Pessoa Só

Documentação de arquitetura é um esporte coletivo. Se apenas uma pessoa cria e mantém os diagramas, eles refletirão o entendimento (ou mal-entendido) dessa pessoa. Revise diagramas C4 em equipe, idealmente como parte do seu processo de revisão de arquitetura.

Não Vincular a Outra Documentação

Um diagrama C4 ganha poder quando conectado a outros artefatos. Vincule containers aos seus runbooks de deployment. Vincule componentes aos seus Architecture Decision Records (ADRs). Vincule sistemas externos à sua documentação de API. Diagramas isolados são menos valiosos que diagramas conectados.

Deixar Diagramas Ficarem Desatualizados

O maior assassino de qualquer abordagem de documentação é a desatualização. Um diagrama que descreve a arquitetura do ano passado é pior que nenhum diagrama porque desinforma ativamente. Incorpore atualizações de diagramas no seu fluxo de trabalho -- faça delas parte de checklists de pull request, sprint reviews ou reuniões de arquitetura.

Como o Archyl Implementa o Modelo C4

O Archyl foi construído em torno do modelo C4 como um conceito de primeira classe. Veja como cada nível se mapeia para funcionalidades na plataforma:

Contexto do Sistema no Archyl

Quando você cria um projeto no Archyl, você define sistemas e seus relacionamentos com atores externos. A visão de Contexto do Sistema é renderizada automaticamente a partir do seu modelo -- sem necessidade de desenho manual. Adicione um sistema, adicione um ator externo, desenhe um relacionamento, e o diagrama se atualiza em tempo real.

Diagrama de Container no Archyl

Dentro de cada sistema, você define containers com suas stacks tecnológicas. O Archyl renderiza o diagrama de Container e permite que você navegue para dentro de qualquer container para ver seus componentes. Relacionamentos entre containers mostram os protocolos de comunicação e fluxos de dados.

Diagrama de Componentes no Archyl

Dentro de cada container, você define componentes. O Archyl os mapeia para código real através da funcionalidade de Code Elements, que vincula componentes a arquivos e diretórios específicos no seu repositório. Essa conexão entre diagrama e código é o que habilita a detecção de drift.

Descoberta com IA

O que diferencia o Archyl de uma ferramenta de desenho é que você não precisa construir o modelo manualmente. Conecte seu repositório, execute a descoberta por IA, e o Archyl gera um rascunho do modelo C4 a partir do seu codebase. A IA identifica sistemas, containers, componentes e relacionamentos analisando a estrutura do seu código, arquivos de configuração e grafos de dependência.

Você revisa as sugestões, aceita ou modifica, e tem um modelo C4 em minutos ao invés de semanas.

Detecção de Drift

Uma vez que seu modelo C4 existe, o Archyl verifica continuamente se ele ainda reflete a realidade. O drift score indica qual porcentagem da sua arquitetura documentada realmente existe no codebase. Se alguém renomeia um serviço ou exclui um componente, o drift score cai, e você sabe que sua documentação precisa de atualização.

Essa é a lacuna que a maioria das ferramentas C4 não cobre. Criar diagramas é a parte fácil. Mantê-los precisos é a parte difícil. A detecção de drift do Archyl fecha essa lacuna.

Começando com C4: Uma Abordagem Passo a Passo

Se sua equipe é nova no modelo C4, aqui está um caminho prático de adoção:

Semana 1: Contexto do Sistema

Reúna sua equipe para um workshop de uma hora. Desenhe seu sistema como uma única caixa. Identifique cada papel de usuário e sistema externo. Desenhe os relacionamentos. Você ficará surpreso com quanto debate esse exercício simples gera -- e quanta alinhamento ele cria.

Semana 2: Diagrama de Container

Pegue a caixa do sistema do seu diagrama de Contexto e quebre-a em containers. Quais são as unidades implantáveis? Quais bancos de dados existem? Quais message brokers ou caches estão em jogo? É aqui que você torna as escolhas tecnológicas visíveis.

Semana 3-4: Diagramas de Componentes para Containers Chave

Escolha os dois ou três containers mais complexos. Quebre cada um em componentes. É aqui que novos desenvolvedores vão passar a maior parte do tempo, então priorize os containers mais difíceis de entender.

Continuidade: Manter e Evoluir

A criação inicial é a parte fácil. A disciplina de manter os diagramas atualizados é o que separa equipes que obtêm valor do C4 das que o abandonam após um mês. Automatize o que puder. Use ferramentas que detectam drift. Faça revisões de diagramas parte do seu fluxo de desenvolvimento.

Por Que o C4 Funciona

O modelo C4 não é tecnicamente revolucionário. Decomposição hierárquica e níveis de abstração existem na ciência da computação desde os anos 1960. O que Simon Brown fez foi empacotar essas ideias em um framework simples e memorável com regras claras e notação mínima.

Funciona porque:

• É fácil de aprender. Quatro níveis. Caixas e setas. Nenhuma certificação UML necessária.
• Escala. De um projeto de fim de semana a uma plataforma enterprise, os mesmos quatro níveis se aplicam.
• Atende múltiplos públicos. Executivos, arquitetos e desenvolvedores cada um recebe o diagrama que fala sua linguagem.
• É agnóstico de ferramenta. Você pode usar um whiteboard, uma ferramenta de desenho, um formato baseado em texto ou uma plataforma dedicada como o Archyl.
• Foca nas coisas certas. Estrutura e relacionamentos, não detalhes de implementação.

Se a documentação de arquitetura da sua equipe consiste em arquivos Visio desatualizados, fotos de whiteboard no Slack e conhecimento tribal, o modelo C4 é o caminho mais prático para algo melhor.

Pronto para construir seu modelo C4? Experimente o Archyl gratuitamente e gere seu primeiro diagrama de arquitetura a partir do código em minutos. Ou explore mais: Descoberta de Arquitetura com IA | Architecture as Code: Defina Seu Modelo C4 em YAML | Architecture Drift Score.