Diagramas C4
Fonte: o modelo C4 oficial em https://c4model.com/. Aplique estas regras ao desenhar, revisar ou explicar um diagrama C4. Carregue também a skill writing quando a saída incluir prosa (ADRs, docs, descrições de PR).
1. Propósito
C4 é um conjunto de "mapas do seu código" em quatro níveis de zoom: Contexto, Containers, Componentes, Código. Simon Brown o criou, inspirado por UML e pelo modelo de visão 4+1, para substituir diagramas ad-hoc de caixas e linhas. Falhas típicas que ele corrige: sem legenda, abstrações misturadas, setas não rotuladas, falta de tecnologia e rótulos vagos como "lógica de negócio".
C4 é independente de notação e de ferramenta. As abstrações e as regras abaixo importam; as formas não.
2. Abstrações
Hierarquia: Pessoa -> Sistema de Software -> Container -> Componente -> Código. Cada nível amplia um elemento do nível superior.
| Abstração | Definição | Exemplos |
|---|---|---|
| Pessoa | Um usuário humano, ator, papel ou persona do sistema | Cliente, Agente de Suporte, Administrador |
| Sistema de Software | Nível mais alto de abstração; entrega valor aos usuários. Tipicamente propriedade e construção de uma única equipe. Não é um domínio de produto, contexto delimitado, tribo ou squad | Plataforma de Ingressos, Sistema de Pagamentos |
| Container | Uma aplicação ou armazenamento de dados executável/implantável de forma independente dentro de um sistema de software | Aplicação web no servidor, SPA, aplicação desktop, aplicação mobile, função serverless, aplicação batch/console, API de microsserviço, esquema de banco de dados, bucket S3/blob store, CDN, sistema de arquivos, script de shell |
| Componente | Um agrupamento de funcionalidades relacionadas por trás de uma interface bem definida, dentro de um container. Não é implantável separadamente: todos os componentes de um container compartilham um único espaço de processo | OrderController, PaymentService, EmailSender |
| Código | Classes, interfaces, funções ou tabelas de BD dentro de um componente | class OrderValidator, tabela pedidos |
Regras de Container (FAQ C4)
- Um container C4 não é Docker. É uma aplicação ou armazenamento de dados executável/implantável, independentemente do empacotamento.
- Uma aplicação HTML renderizada no servidor é 1 container. Um servidor mais um SPA ou cliente mobile são 2 containers se comunicando por uma API remota.
- JARs, DLLs, assemblies e módulos não são containers. Eles organizam o código dentro de um container.
- Serviços de dados gerenciados (S3, RDS, CDN) são containers dentro do limite do seu sistema quando você possui ou controla os buckets ou esquemas. Eles não são sistemas externos.
Regras de Componente
- Um componente não é uma pasta, pacote ou JAR. É um agrupamento funcional com uma interface.
- Componentes não são implantáveis independentemente. Se implanta separadamente, é um container.
Adaptando a terminologia
As equipes podem substituir nomes idiomáticos da linguagem (por exemplo, Módulo ou Função em código funcional) quando definirem o termo explicitamente no diagrama ou em sua documentação. Não invente níveis de abstração extras a menos que cada um seja estritamente definido.
3. Padrões especiais de modelagem
Filas e tópicos
- Errado: um único "Barramento de Mensagens" gigante no meio com todos os serviços conectados (hub-and-spoke). Isso esconde quem produz e quem consome o quê.
- Opção 1 (preferida): modele cada fila ou tópico como seu próprio container (um armazenamento de dados de mensagens). Produtores escrevem nele, consumidores leem ou assinam dele.
- Opção 2: para acoplamento ponto-a-ponto direto, omita a caixa de fila e rotule o relacionamento como
"Publica eventos de pedido via Fila pedidos [AMQP]". Opcionalmente, estilize essas linhas de forma diferente de chamadas HTTP (explique na legenda).
Por exemplo: Order API --"Publica OrderPlaced em [Kafka]"--> [(tópico pedidos)] --"Lê OrderPlaced de [Kafka]"--> Fulfilment Worker.
Microsserviços (Regra da Lei de Conway)
- Uma equipe é dona de todo o sistema de software: modele cada microsserviço como um grupo de containers dentro do limite desse sistema (container de API mais seu próprio container de esquema de banco de dados, ou um único container Lambda sem estado).
- Equipes separadas são donas de cada serviço: promova cada serviço com propriedade independente para seu próprio Sistema de Software, cada um com seus próprios diagramas de Contexto do Sistema e Container. Declare a propriedade de filas/tópicos explicitamente entre os limites do sistema.
4. Catálogo de diagramas
Níveis estáticos principais
| Nível | Diagrama | Recomendado | Escopo | Público | Mostrar / omitir |
|---|---|---|---|---|---|
| 1 | Contexto do Sistema | Sim | 1 sistema de software | Técnico e não técnico | Pessoas e sistemas externos ao redor do sistema. Omita tecnologia e protocolos de baixo nível |
| 2 | Container | Sim | 1 sistema de software | Técnico, operações | Principais escolhas tecnológicas e protocolos entre processos. Omita clustering, balanceadores de carga, failover |
| 3 | Componente | Não: apenas quando agregar valor claro, idealmente automatizado | 1 container | Arquitetos, desenvolvedores | Componentes dentro de um container e suas interações |
| 4 | Código | Não: gere sob demanda na IDE | 1 componente | Desenvolvedores | Diagrama de classes UML ou ERD |
Diagramas de suporte
| Diagrama | Recomendado | Uso |
|---|---|---|
| Paisagem do Sistema | Sim, para organizações e portfólios | Mapa empresarial ou departamental de todos os sistemas e pessoas. Um diagrama de Contexto sem um único sistema focal |
| Dinâmico | Não: use com moderação | Colaborações complexas em tempo de execução. Estilo de colaboração numerada ou estilo de sequência UML |
| Implantação | Sim | 1 ambiente (prod, staging, dev). Nós de implantação aninhados (físico, VM, Docker, Kubernetes, runtime) contendo instâncias de sistema/container, mais nós de infraestrutura (DNS, balanceadores de carga, firewalls) |
Compatibilidade
- arc42: Contexto e Escopo -> L1; Nível de Bloco de Construção 1 -> L2; Nível de Bloco de Construção 2 -> L3; Nível de Bloco de Construção 3 -> L4.
- UML: complemente C4 com diagramas UML de estado, sequência e ERD para fluxos de trabalho, máquinas de estado e modelos de dados.
Regra de escala
Quando um diagrama ficar poluído, não amontoe dezenas de caixas em uma única tela. Divida no mesmo nível de abstração por área de negócio, contexto delimitado, funcionalidade ou foco em um único serviço (o serviço focal mais seus vizinhos de entrada e saída).
5. Regras de notação
Diagrama
- O título declara o tipo de diagrama e o escopo:
Diagrama de Container para Sistema de Checkout. - Sempre inclua uma chave/legenda explicando formas, cores, bordas, tipos de linha, pontas de seta e siglas.
- Mantenha pureza estrita de abstração: nunca misture níveis de abstração (por exemplo, nenhuma caixa
Componentedentro de um diagrama L2 de Container), e nunca coloque protocolos ou etapas de implementação interna ([HTTPS],pacote mascarado,tool_runner) dentro de um diagrama L1 de Contexto do Sistema. - Ao comparar arquiteturas concorrentes ou históricas, rotule os títulos dos limites explicitamente (
Opção A (Substituída)vs.Opção B (Atual)) e atualize todos os diagramas no documento sempre que requisitos ou suposições mudarem.
Elemento
- Nome, tipo de elemento explícito (
Pessoa,Sistema de Software,Container,Componente,Banco de Dados,Nó de Implantação) e uma descrição concisa de responsabilidade. - Tecnologia explícita em cada container, componente e nó de implantação.
Relacionamento
- Apenas setas unidirecionais. Nunca
<-->. Se os dados fluírem em ambos os sentidos, mostre a direção do iniciador e descreva a resposta no rótulo. - Rótulos com verbos de ação específicos. Nunca um "Usa" genérico. Escreva
Submete pedidos para,Lê mapa de assentos de. - Protocolo/tecnologia em relacionamentos entre containers:
[JSON/HTTPS],[SQL],[gRPC],[AMQP].
6. Mermaid em Markdown
Prefira flowchart (flowchart TB ou LR), não o C4Context/C4Container nativo do Mermaid. A sintaxe C4 nativa é experimental e frequentemente falha ao renderizar em visualizadores Markdown. Emita-a apenas se o usuário pedir explicitamente e confirmar suporte do renderizador.
Convenções de flowchart:
subgraphpara o limite do sistema (Containers/Componentes) ou nós de implantação.[(...)]para bancos de dados, armazenamentos de dados, filas e tópicos.- Rótulos HTML entre aspas:
"<b>Nome</b><br/>«Container: Tech»<br/>Responsabilidade curta". - Setas com rótulos entre aspas:
A -->|"Ação [Protocolo]"| B. - Um
classDefpor tipo de elemento, aplicado consistentemente. - Um subgraph
Legendacompacto (nós não conectados, ancorado na parte inferior com um link invisívelbottomNode ~~~ Legendaquando Dagre o coloca no topo) é necessário sempre que cores, formas de cilindro ou múltiplos estilos de linha forem usados; coloque um título como cabeçalho ou linhaTítulo: ...diretamente acima do bloco de código. - Diagramas dinâmicos:
sequenceDiagram, ou umflowchartcom rótulos de seta numerados (1. Submete pedido [JSON/HTTPS]). - Diagramas de implantação:
subgraphs aninhados em umflowchart. - Sempre coloque entre aspas rótulos que contenham parênteses, colchetes ou dois-pontos.
- Nunca coloque ponto e vírgula (
;) sem escape dentro de rótulos desequenceDiagramoustateDiagram-v2(o Mermaid trata;como terminador de instrução e divide o texto restante em estados ou erros de análise); envolva blocosNotelongos emsequenceDiagramcom<br/>para que o texto nunca seja cortado na borda do viewport.
Template: L1 Contexto do Sistema
Título: Diagrama de Contexto do Sistema para Plataforma de Ingressos
flowchart TB
cliente["<b>Cliente</b><br/>«Pessoa»<br/>Compra ingressos para eventos"]
plataforma["<b>Plataforma de Ingressos</b><br/>«Sistema de Software»<br/>Permite que clientes naveguem por eventos e comprem ingressos"]
pagamentos["<b>Provedor de Pagamento</b><br/>«Sistema de Software, externo»<br/>Cobra cartões"]
email["<b>Serviço de Email</b><br/>«Sistema de Software, externo»<br/>Entrega emails de confirmação"]
cliente -->|"Navega por eventos e compra ingressos usando"| plataforma
plataforma -->|"Solicita cobranças de cartão de"| pagamentos
plataforma -->|"Envia emails de confirmação usando"| email
email -->|"Entrega emails de confirmação para"| cliente
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef system fill:#1168bd,stroke:#0b4884,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class cliente person
class plataforma system
class pagamentos,email external
subgraph Legenda
direction LR
l1["Pessoa"]:::person
l2["Sistema de Software (no escopo)"]:::system
l3["Sistema de Software (externo)"]:::external
end
Template: L2 Container (com container de fila)
Título: Diagrama de Container para Plataforma de Ingressos
flowchart TB
cliente["<b>Cliente</b><br/>«Pessoa»<br/>Compra ingressos para eventos"]
pagamentos["<b>Provedor de Pagamento</b><br/>«Sistema de Software, externo»<br/>Cobra cartões"]
subgraph limite["Plataforma de Ingressos [Sistema de Software]"]
spa["<b>App Web</b><br/>«Container: React SPA»<br/>UI de navegação e checkout"]
api["<b>API de Pedidos</b><br/>«Container: Java, Spring Boot»<br/>Valida e coloca pedidos"]
db[("<b>BD de Pedidos</b><br/>«Container: PostgreSQL»<br/>Armazena pedidos e ingressos")]
topico[("<b>tópico pedidos</b><br/>«Container: Tópico Kafka»<br/>Eventos OrderPlaced")]
worker["<b>Worker de Fulfillment</b><br/>«Container: Python»<br/>Emite ingressos e envia emails"]
end
cliente -->|"Navega e compra usando [HTTPS]"| spa
spa -->|"Submete pedidos para [JSON/HTTPS]"| api
api -->|"Escreve pedidos em [SQL/TCP]"| db
api -->|"Publica OrderPlaced em [Kafka]"| topico
worker -->|"Lê OrderPlaced de [Kafka]"| topico
worker -->|"Atualiza status do ingresso em [SQL/TCP]"| db
api -->|"Solicita cobranças de cartão de [JSON/HTTPS]"| pagamentos
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef container fill:#438dd5,stroke:#2e6295,color:#fff
classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class cliente person
class spa,api,worker container
class db,topico store
class pagamentos external
subgraph Legenda
direction LR
l1["Pessoa"]:::person
l2["Container"]:::container
l3[("Armazenamento de dados / fila / tópico")]:::store
l4["Sistema externo"]:::external
end
Nota da legenda: setas apontam do iniciador para o destino. O rótulo indica a ação e [protocolo].
Template: Implantação
Título: Diagrama de Implantação para Plataforma de Ingressos (Produção)
flowchart TB
usuarios["<b>Navegador do Cliente</b><br/>«Nó de Implantação: Chrome»"]
subgraph aws["AWS «Nó de Implantação: Cloud, us-east-1»"]
dns["<b>Route 53</b><br/>«Nó de Infraestrutura: DNS»"]
lb["<b>Balanceador de Carga</b><br/>«Nó de Infraestrutura: ALB»"]
subgraph eks["EKS «Nó de Implantação: Cluster Kubernetes»"]
subgraph pod["pod order-api «Nó de Implantação: Docker, x3»"]
api["<b>API de Pedidos</b><br/>«Instância de Container: Java, Spring Boot»"]
end
end
subgraph rds["RDS «Nó de Implantação: PostgreSQL 16»"]
db[("<b>BD de Pedidos</b><br/>«Instância de Container: Esquema PostgreSQL»")]
end
end
usuarios -->|"Resolve nome de host usando [DNS]"| dns
usuarios -->|"Envia requisições para [HTTPS]"| lb
lb -->|"Encaminha requisições para [HTTP]"| api
api -->|"Lê e escreve pedidos em [SQL/TCP]"| db
Adicione um subgraph Legenda se usar cores ou estilos além dos padrão.
Template: Dinâmico (Sequência)
Título: Diagrama Dinâmico (estilo sequência) para Checkout de Pedido na Plataforma de Ingressos
sequenceDiagram
autonumber
actor cliente as Cliente
participant spa as App Web (React SPA)
participant api as API de Pedidos (Spring Boot)
participant pagamentos as Provedor de Pagamento
participant db as BD de Pedidos (PostgreSQL)
participant topico as tópico pedidos (Kafka)
cliente->>spa: Clica "Finalizar Pedido"
spa->>api: POST /orders [JSON/HTTPS]
api->>pagamentos: Cobra cartão [JSON/HTTPS]
pagamentos-->>api: Pagamento autorizado
api->>db: Insere linha de pedido [SQL/TCP]
api->>topico: Publica OrderPlaced [Kafka]
api-->>spa: 201 Criado (confirmação do pedido)
spa-->>cliente: Mostra recibo do pedido
Mantenha os rótulos de participantes e mensagens de sequenceDiagram livres de barras não entre aspas, ponto e vírgula (;, que o Mermaid analisa como terminadores de instrução) ou novas linhas brutas para máxima compatibilidade com visualizadores Markdown.
7. Dicas de estilo Mermaid
- Cores: use cores acessíveis (contraste suficiente, sem vermelho e verde exclusivos para daltônicos). Cores sugeridas: Pessoas azul escuro (
#08427b), Containers azul médio (#438dd5), Sistemas azul mais claro (#1168bd), Armazenamentos azul marinho (#2e6da4), Externos cinza (#999). - Bordas: mantenha bordas sólidas de tom mais escuro.
- Formas: pessoas são retângulos com cantos arredondados, containers são retângulos retos, armazenamentos de dados são cilindros (
[( )]). - Tamanho da fonte: mantenha o tamanho padrão do Mermaid ou defina
fontSize: 14noclassDef. - Legenda: sempre inclua se forem usadas cores ou formas não padrão. Use um subgraph separado.
8. Revisão e garantia de qualidade
Ao revisar um diagrama C4, verifique:
- O título corresponde ao tipo e escopo do diagrama.
- Legenda presente, atualizada e cobrindo todas as formas, cores e tipos de linha.
- Sem abstrações misturadas (por exemplo, sem
Componentedentro de L2). - Cada elemento tem tipo e tecnologia/descrição.
- Setas são unidirecionais com rótulos de ação e protocolo quando aplicável.
- Nomes de elementos consistentes entre diagramas (mesmo nome = mesmo elemento).
- Nenhuma abreviação ou sigla não explicada.
- Diagramas ficam legíveis sem zoom extremo (divida se mais de ~15 caixas).
-
flowcharté preferido em vez deC4Context/C4Containerdo Mermaid. - A legenda está ancorada na parte inferior quando necessário.
- Rótulos com caracteres especiais estão entre aspas.
9. Exemplos de prompts
- "Desenhe um diagrama de Contexto do Sistema L1 para um sistema de processamento de pedidos."
- "Converta esta descrição de arquitetura em um diagrama de Container L2 usando Mermaid."
- "Adicione um diagrama de Implantação mostrando serviços implantados no EKS com bancos de dados RDS."
- "Revise este diagrama C4 em busca de violações de pureza de abstração."
- "Atualize o diagrama de Container para refletir a adição de uma fila de mensagens."