O diagrama de Container C4 (nível 2 do modelo C4) mostra os blocos de construção implantáveis do seu sistema: apps web, APIs, bancos de dados, filas. Este guia explica o que é um diagrama de container, o que pertence a ele, um exemplo completo resolvido, erros comuns e como mantê-lo em sincronia com o seu código.

Diagrama de Container C4: guia completo com exemplos

Se você for desenhar apenas um diagrama de arquitetura para o seu sistema, que seja o diagrama de container. Ele é o nível 2 do modelo C4 e, na prática, é o mais usado dos quatro níveis -- porque mapeia diretamente sobre as coisas que as equipes de engenharia de fato constroem, implantam e operam: apps web, APIs, bancos de dados, message brokers.

Este guia cobre tudo o que você precisa para criar um bom diagrama de container C4: o que ele é (e o que não é -- não, um container C4 não é um container Docker), o que pertence a ele, um exemplo completo resolvido para um produto SaaS típico, os erros que arruínam a maioria dos diagramas de container e como criar um manualmente ou gerá-lo a partir do seu código.

Se você é totalmente novo no modelo C4, comece pelo nosso guia completo do modelo C4 e depois volte para cá.

O que é um diagrama de Container C4?

O diagrama de container é o nível 2 do modelo C4, criado por Simon Brown. Ele dá zoom na única caixa que representa o seu sistema no diagrama de Contexto de Sistema e revela os blocos de construção técnicos de alto nível que existem dentro dela.

Na terminologia C4, um container é qualquer unidade que pode ser implantada ou executada separadamente: algo que executa código ou armazena dados, roda no seu próprio processo (ou tem o seu próprio ciclo de vida de armazenamento) e poderia, em princípio, ser implantado de forma independente do resto do sistema.

Essa definição abrange coisas como:

Uma single-page application (React, Vue, Angular) rodando no navegador do usuário
Uma aplicação web do lado do servidor (Next.js, Rails, Django)
Uma aplicação mobile (app iOS, app Android)
Um serviço de API backend (API em Go, servidor Node.js, serviço Spring Boot)
Um banco de dados (PostgreSQL, MongoDB, MySQL)
Um cache (Redis, Memcached)
Um message broker ou fila (Kafka, RabbitMQ, SQS)
Um worker em segundo plano ou processo de job agendado
Um armazenamento de arquivos ou blobs (bucket S3, MinIO)
Uma função serverless (AWS Lambda, Cloud Functions)

O teste decisivo é simples: ele roda no seu próprio processo ou mantém os seus próprios dados? Dois pacotes Go compilados em um único binário pertencem ao mesmo container. Dois serviços implantados de forma independente são dois containers -- mesmo que compartilhem um repositório.

Para uma definição de referência concisa, veja a entrada de diagrama de container no nosso glossário.

Um container C4 não é um container Docker

Este é, de longe, o ponto de confusão mais comum, então vamos resolvê-lo explicitamente.

O modelo C4 é anterior à adoção mainstream do Docker, e a palavra "container" no C4 significa algo mais amplo: um bloco de construção em nível de runtime do seu sistema. A sobreposição com o Docker é coincidente e parcial:

Um container C4 pode rodar dentro de um container Docker. A sua API em Go provavelmente roda.
Um container C4 pode rodar como um processo de SO comum, uma aba de navegador, um app mobile ou um serviço de nuvem gerenciado. Nenhum desses é um container Docker.
Um único container Docker poderia até hospedar múltiplos containers C4 (um app mais um banco de dados embutido em uma imagem de dev), embora isso seja incomum.

Dito de outra forma: containers Docker são uma tecnologia de empacotamento e implantação. Containers C4 são uma abstração arquitetural. Uma SPA React rodando no Chrome é um container C4 e nunca será um container Docker. Uma instância PostgreSQL no RDS é um container C4 e o Docker não está nem por perto.

Quando você rotula uma caixa de "container" em um diagrama C4, você está dizendo "esta é uma parte do meu sistema que pode ser executada ou implantada separadamente" -- nada mais.

O que pertence a um diagrama de container

Um bom diagrama de container mostra exatamente três categorias de informação:

1. Os próprios containers

Toda unidade implantável ou executável dentro da fronteira do seu sistema, cada uma rotulada com seu nome, sua responsabilidade e sua escolha de tecnologia: "Order Service (Go)", "Session Cache (Redis)", "Web App (React SPA)". O rótulo de tecnologia não é decoração -- é metade do valor do diagrama. É o que permite a um novo engenheiro ou a uma equipe de plataforma raciocinar sobre o sistema sem abrir doze repositórios.

2. As relações e os protocolos

Setas entre containers, cada uma rotulada com o que flui e como: "lê/escreve pedidos (SQL)", "publica eventos (AMQP)", "faz chamadas de API (HTTPS/JSON)". Protocolos de comunicação importam neste nível porque guiam preocupações operacionais -- políticas de rede, orçamentos de latência, semântica de retry, modos de falha.

3. O contexto imediato

Os usuários e sistemas externos do seu diagrama de contexto, mantidos nas bordas para que o leitor consiga ver como as requisições entram e saem do sistema. Você não os redocumenta em detalhe; eles são âncoras.

Para quem é este diagrama?

O público do diagrama de container é técnico: desenvolvedores entrando na equipe, arquitetos tomando decisões estruturais e engenheiros de operações/plataforma planejando implantações, monitoramento e capacidade. É o nível onde conversas como "esses dois serviços deveriam compartilhar um banco de dados?" ou "o que quebra se o Redis cair?" de fato acontecem. Stakeholders não técnicos deveriam estar olhando o diagrama de contexto.

O que NÃO pertence

Módulos, classes ou pacotes internos -- esses ficam no diagrama de component (nível 3)
Detalhes de infraestrutura como load balancers, VPCs, nós Kubernetes -- esses pertencem a um diagrama de implantação
Toda micro-interação -- se uma relação não é arquiteturalmente significativa, deixe-a de fora

Exemplo de diagrama de container: um produto web SaaS

Vamos construir um exemplo completo de diagrama de container para um produto SaaS fictício -- a "InvoiceHub", uma ferramenta de faturamento baseada na web. Esse formato (SPA + API + banco de dados + cache + worker + fila) descreve uma enorme parcela dos produtos web do mundo real, então você provavelmente pode adaptá-lo diretamente.

Os containers

Container	Tecnologia	Responsabilidade
Web Application	React SPA	A UI que os clientes usam para criar e enviar faturas
API Application	Go (Fiber)	Lógica de negócio, autenticação, API REST consumida pela SPA
Database	PostgreSQL	Sistema de registro para contas, faturas, pagamentos
Cache	Redis	Armazenamento de sessões e cache de caminho quente de resumos de faturas
Message Queue	RabbitMQ	Desacopla o trabalho lento (renderização de PDF, e-mails) das requisições de API
Background Worker	Go	Consome mensagens da fila: renderiza PDFs, envia e-mails, sincroniza status de pagamento

As relações

[Customer] --> [Web Application (React SPA)] : Uses (HTTPS)
[Web Application] --> [API Application (Go)] : Makes API calls (HTTPS/JSON)
[API Application] --> [Database (PostgreSQL)] : Reads/writes invoices and accounts (SQL/TCP)
[API Application] --> [Cache (Redis)] : Reads/writes sessions and cached summaries (RESP)
[API Application] --> [Message Queue (RabbitMQ)] : Publishes invoice.created, email.requested (AMQP)
[Background Worker (Go)] --> [Message Queue] : Consumes jobs (AMQP)
[Background Worker] --> [Database (PostgreSQL)] : Updates job and payment status (SQL/TCP)
[Background Worker] --> [Email Service (SendGrid)] : Sends invoice emails (HTTPS/REST)
[API Application] --> [Payment Gateway (Stripe)] : Creates payment links, receives webhooks (HTTPS/REST)

O que este diagrama te diz

Releia essa lista e repare em quantas perguntas concretas de engenharia ela responde:

Onde vive o estado? Em dois lugares: PostgreSQL (durável) e Redis (efêmero). Se você já debateu se as sessões sobrevivem a um restart do Redis, o diagrama torna a questão visível.
Qual é o raio de impacto de uma falha? O worker e a API compartilham o banco de dados. RabbitMQ fora do ar significa que as faturas ainda são criadas, mas os e-mails enfileiram -- por design.
Quais são as fronteiras de confiança? A SPA roda em dispositivos cliente não confiáveis; tudo o que ela pode fazer passa pela autenticação da API.
O que ops precisa rodar? Seis coisas, com seus protocolos. Essa é a sua checklist de monitoramento e, aproximadamente, o seu arquivo docker-compose.

Um novo desenvolvedor consegue absorver isso em dois minutos. Esse é todo o propósito do nível 2 do modelo C4.

Erros comuns em diagramas de container

A maioria dos diagramas de container falha de uma entre algumas formas previsíveis.

Confundir containers com components

Se o seu diagrama de container mostra "OrderController", "InvoiceRepository" ou "AuthMiddleware", você deu um zoom a mais. Esses são components -- blocos de construção internos dentro de um container -- e pertencem a um diagrama de component de nível 3. O teste: ele pode ser implantado ou executado por conta própria? Uma classe de repositório não pode. Mantenha cada diagrama em um único nível de zoom; misturar níveis é a forma mais rápida de produzir um diagrama ilegível.

Omitir os armazenamentos de dados

As equipes frequentemente desenham apenas as coisas para as quais escreveram código e esquecem que bancos de dados, caches e filas também são containers. Um diagrama de container sem seus armazenamentos de dados esconde exatamente a informação de que arquitetos e engenheiros de ops mais precisam: onde o estado vive, o que é compartilhado, o que é um ponto único de falha. Se o seu sistema usa PostgreSQL, Redis e S3, os três vão no diagrama.

Desenhar a implantação em vez da estrutura de runtime

Um diagrama de container não é um diagrama de infraestrutura. Load balancers, pods Kubernetes, grupos de auto-scaling, zonas de disponibilidade e o número de réplicas são preocupações de implantação -- o C4 tem um diagrama de implantação suplementar separado para isso. O diagrama de container responde "quais são as peças lógicas de runtime e como elas conversam?", não "quantas instâncias rodam onde?". Desenhar três caixas "API" idênticas porque você roda três réplicas adiciona ruído, não informação.

Relações sem rótulo ou vagas

Uma seta que só diz "usa" desperdiça o potencial do diagrama. "Faz chamadas de API (HTTPS/JSON)", "publica eventos de pedido (AMQP)", "lê/escreve sessões (RESP)" -- o verbo e o protocolo transformam uma figura em documentação.

Deixar apodrecer

O erro mais danoso nem está no diagrama. Um diagrama de container desenhado dezoito meses atrás, que ainda mostra o monolito que você já dividiu em quatro serviços, engana ativamente todo novo leitor. Documentação de arquitetura desatualizada é pior do que nenhuma -- e é por isso que manter o diagrama sincronizado com o código importa mais do que o quão bonito ele é.

Como criar um diagrama de container

Manualmente

Você consegue construir um diagrama de container sólido em menos de uma hora:

Parta do seu diagrama de contexto. Mantenha os usuários e sistemas externos nas bordas.
Liste suas unidades implantáveis. Percorra seus repositórios, seu arquivo docker-compose, seu console de nuvem. Tudo que roda como seu próprio processo ou armazena dados é um candidato.
Adicione os armazenamentos de dados explicitamente. Bancos de dados, caches, filas, armazenamento de blobs.
Desenhe as relações. Para cada par de containers que se comunicam, adicione uma seta com uma frase com verbo e um protocolo.
Rotule as tecnologias. Nome e tecnologia em toda caixa.
Revise com a equipe. A discussão que isso provoca ("espera, o worker fala com o Stripe diretamente?") costuma valer mais do que o próprio diagrama.

Qualquer ferramenta serve -- Structurizr, PlantUML com a extensão C4, draw.io, até um quadro branco. A notação importa muito menos do que o conteúdo e a disciplina de mantê-lo atual.

Com a Archyl

A abordagem manual tem uma fraqueza estrutural: ela captura um instantâneo, e software não fica parado. A Archyl aborda o diagrama de container pelo lado oposto -- ela deriva o modelo do código:

Descoberta por IA a partir do seu código. Conecte um repositório e a descoberta por IA da Archyl analisa a estrutura do seu código, sua configuração e seus manifestos de dependências para propor um modelo C4 em rascunho -- sistemas, containers, components e as relações entre eles. Você revisa e aprova as sugestões em vez de desenhar caixas de memória.
A detecção de drift mantém a honestidade. Uma vez que o modelo existe, a Archyl compara continuamente os containers documentados com o que o código de fato mostra e expõe um score de drift. Quando alguém divide um serviço ou troca o RabbitMQ pelo Kafka, você descobre pelo dashboard, não por uma sessão de onboarding confusa seis meses depois.
Arquitetura como Código. Prefere texto? Você pode definir seu modelo C4 completo -- containers, tecnologias, relações -- em YAML, versioná-lo junto ao seu código e deixar a Archyl renderizar os diagramas interativos. Mudanças no diagrama passam por pull requests como tudo o mais.

De qualquer forma, o objetivo é o mesmo: um diagrama de container que está preciso hoje e ainda preciso no próximo trimestre.

FAQ

Um container C4 é o mesmo que um container Docker?

Não. Um container C4 é uma abstração arquitetural: qualquer unidade de um sistema que pode ser implantada ou executada separadamente, como um app web, uma API, um banco de dados ou um message broker. Um container Docker é uma tecnologia de empacotamento. Muitos containers C4 acabam sendo implantados como containers Docker, mas vários não são -- uma SPA React roda em um navegador, um app mobile roda em um celular e um banco de dados gerenciado roda como um serviço de nuvem. O nome compartilhado é um acidente infeliz da história.

O que é o nível 2 do modelo C4?

O nível 2 do modelo C4 é o diagrama de container. Ele dá zoom em um sistema de software (a única caixa do diagrama de contexto de nível 1) e mostra as unidades implantáveis/executáveis dentro dele, suas escolhas de tecnologia e os protocolos que elas usam para se comunicar. Ele fica entre o diagrama de contexto (nível 1) e o diagrama de component (nível 3).

Quantos containers um diagrama de container deve mostrar?

Não há regra fixa, mas a legibilidade degrada rapidamente acima de 15-20 containers. Se o seu sistema genuinamente tem mais, divida a visão: um diagrama de container por subsistema, ou agrupe containers relacionados visualmente. Se você tem centenas, provavelmente está documentando múltiplos sistemas e precisa de modelos C4 separados, vinculados no nível de contexto.

Cada microsserviço deveria ser um container separado?

Sim -- por definição. Cada serviço implantável de forma independente é o seu próprio container, junto com o banco de dados de cada serviço se você segue o padrão database-per-service. Esse também é um teste de cheiro útil: se os seus "microsserviços" não podem ser desenhados como containers separados porque compartilham um processo ou não conseguem ser implantados de forma independente, eles podem ser um monolito distribuído.

Pronto para gerar seu diagrama de container em vez de desenhá-lo? Experimente a Archyl gratuitamente e obtenha um modelo C4 a partir do seu código em minutos. Continue explorando a série C4: O que é o modelo C4? Um guia completo | Guia do diagrama de Contexto de Sistema C4 | Guia do diagrama de Component C4.

Diagrama de Container C4: guia completo com exemplos - Archyl Blog