Um Diagrama C4 é um método padronizado de visualização arquitetônica projetado para modelar sistemas de software em múltiplos níveis de abstração estrutural. Integrado nativamente ao Mermaid.js, o c4motor segue os quatro níveis principais do modelo C4: Contexto (o ecossistema macro), Contêineres (aplicações, serviços e bancos de dados), Componentes (módulos estruturais internos), e interações dinâmicas. Esta ferramenta elimina a complicação da estilização personalizada com CSS, aplicando blocos arquitetônicos consistentes e prontos para apresentação com base nas suas declarações de texto.
Compreendendo as Abstrações e Palavras-Chave do Diagrama C4
O Mermaid suporta quatro cabeçalhos especializados de inicialização de diagramas, dependendo do nível de detalhe que sua disposição do sistema exige:
C4Contexto: Foca na visão de conjunto, exibindo usuários, ecossistemas de software principais e dependências externas de alto nível.C4Contêiner: Amplia um nível para decompor aplicações autônomas, interfaces de front-end, microserviços, sistemas de armazenamento de banco de dados e filas.C4Componente: Aprofunda-se dentro de um contêiner para mostrar módulos de nível de código interno, como Controladores, Serviços e Repositórios.C4Dinâmico: Foca em rastrear interações de dados em tempo de execução ou sequenciamento passo a passo de transações entre blocos de infraestrutura.
Estrutura Básica de Sintaxe
Todo diagrama C4 começa com seu cabeçalho de nível específico, seguido por uma declaração opcional de título e componentes macro separados por vírgulas. Os parâmetros ficam dentro de parênteses, com strings delimitadas por aspas duplas.
C4Context
título "Plano de Contexto do Sistema para o Núcleo da Internet"
Pessoa(cliente, "Cliente Bancário", "Um cliente do banco com contas pessoais.")
Sistema(sistema_bancario, "Sistema de Banco na Internet", "Permite que os clientes visualizem informações da conta.")
Rel(cliente, sistema_bancario, "Utiliza", "HTTPS")
A Taxonomia Completa dos Macros do Elemento C4
A biblioteca C4 do Mermaid fornece um conjunto extenso de macros especializadas para distinguir claramente entre componentes internos, sistemas externos e camadas de banco de dados em todos os níveis de abstração.
1. Macros de Pessoa e Usuário
Pessoa(alias, rótulo, [descr], [sprite], [tags]): Modela um usuário humano interno ou interessado.Pessoa_Ext(alias, rótulo, [descr], [sprite], [tags]): Modela um usuário externo (por exemplo, um fornecedor terceirizado ou auditor) fora dos limites organizacionais principais.
2. Macros de Sistema e Ecossistema de Software
Sistema(alias, rótulo, [descr], [sprite], [tags]): Representa um cluster de sistemas de software interno, dentro do escopo, sob sua gestão direta.Sistema_Ext(alias, rótulo, [descr], [sprite], [tags]): Modela um sistema de software externo essencial gerenciado por terceiros (por exemplo, provedores de identidade, registros principais de bancos).SistemaDb(alias, rótulo, [descr], [sprite], [tags]): Representa uma caixa de repositório de dados em nível de sistema com formato cilíndrico.SistemaDb_Ext(alias, rótulo, [descr], [sprite], [tags]): Representa uma camada de banco de dados externa, de terceiros.
3. Macros da Camada de Container (Nível C4Container)
Container(alias, rótulo, tecnologia, [descr], [sprite], [tags]): Modela uma aplicação executável separada, servidor de API ou interface de front-end.ContainerDb(alias, rótulo, tecnologia, [descr], [sprite], [tags]): Representa um invólucro de motor de banco de dados relacional ou não relacional em nível de container.Container_Ext(alias, rótulo, tecnologia, [descr], [sprite], [tags]): Representa um contêiner em nuvem externo ou serviço de aplicação.ContainerDb_Ext(alias, rótulo, tecnologia, [descr], [sprite], [tags]): Representa uma camada de armazenamento de banco de dados em nuvem externa e gerenciada.
4. Macros da Camada de Componente (Nível C4Component)
Componente(alias, rótulo, tecnologia, [descr], [sprite], [tags]): Mapeia um módulo, camada ou controlador de classe em nível de código interno.ComponenteDb(alias, rótulo, tecnologia, [descr], [sprite], [tags]): Modela um sistema de armazenamento de microcomponentes interno ou um sistema de cache de arquivos de baixo nível.
Contêineres de Fronteira e Envoltórios Estruturais
Para indicar perimeters de segurança, firewalls corporativos ou fronteiras lógicas de aplicação, o Mermaid fornece três envoltórios de contêiner com colchetes dedicados. Os elementos aninhados dentro são agrupados visualmente.
Enterprise_Boundary(alias, label) { ... }: Envolve sistemas de alto nível dentro de uma ampla fronteira visual que representa o perímetro geral da infraestrutura corporativa ou da empresa.System_Boundary(alias, label) { ... }: Agrupa contêineres de aplicativos ou microserviços estreitamente relacionados dentro de uma caixa unificada de ecossistema de software.Container_Boundary(alias, label) { ... }: Isola componentes de nível de código dentro de uma única camada de contexto de módulo de aplicativo.
Operadores Direcionais de Relacionamento Avançados
Conectar blocos em diagramas C4 depende do Relmacro ou suas variações explicitamente direcionadas. Em vez de passar linhas de fluxograma brutas, você rastreia conexões semanticamente declarando vetores de tecnologia diretamente dentro dos blocos lógicos.
| Token de Sintaxe de Relacionamento | Direção da Setas Visual | Contexto de Alinhamento de Uso |
|---|---|---|
Rel(from, to, label, [tech]) |
Dinâmico / Automatizado | Relacionamento padrão. Deixe o algoritmo de layout determinar o melhor caminho da linha. |
BiRel(from, to, label, [tech]) |
Bidirecional (<–>) | Indica trocas interativas de duas vias, protocolos duplex ou processos de sincronização. |
Rel_Back(from, to, label, [tech]) |
Seta Reversa no Topo (<–) | Desenha a relação na direção lógica do código, mas inverte a seta visual visível para trás. |
Rel_Neighbor(from, to, label, [tech]) |
Preferência de Layout Horizontal | Força o nó de destino a permanecer diretamente ao lado do nó de origem na mesma linha horizontal. |
Rel_Down(from, to, label, [tech]) / Rel_D(...) |
Diretamente para Baixo (v) | Força fluxos de dados verticais para baixo até camadas de banco de dados ou processos de fundo subsequentes. |
Rel_Up(from, to, label, [tech]) / Rel_U(...) |
Para Cima Reto (^) | Força os rastros de relacionamento a viajar diretamente para cima até os componentes da interface do cliente. |
Rel_Esq(from, to, label, [tech]) / Rel_E(...) |
Para a Esquerda Reto (<-) | Direciona os caminhos horizontalmente para o lado esquerdo do elemento da tela. |
Rel_Dir(from, to, label, [tech]) / Rel_D(...) |
Para a Direita Reto (->) | Direciona os caminhos horizontalmente para o lado direito do elemento da tela. |
Estilo Dinâmico Personalizado e Marcação (Substituição de Formas C4)
Para sinalizar aplicações legadas, destacar sistemas premium ou destacar fluxos de dados seguros, você pode criar estilos personalizados usando o motor de marcação de elementos. Você define uma matriz de propriedades de marcação no topo do seu documento e depois acrescenta essa etiqueta às definições dos seus elementos.
Palavras-chave para Modificação de Estilo:
AtualizarEstiloElemento(elementName, corFundo, corFonte, [corBorda], [sombreamento]): Substituição direta da paleta de fundo padrão de uma caixa de elemento explícita.AtualizarEstiloRel(from, to, corLinha, corTexto): Direciona explicitamente uma rota de conexão para recolorir caminhos de linha ou descrições de conexão.
C4Context
título "Mapa de Arquitetura Global com Codificação por Cor Personalizada"
Sistema(legacy_api, "Núcleo de Faturamento Legado", "Processa renovações de assinatura.")
Sistema(modern_portal, "Portal do Painel do Cliente", "Motor moderno de visualização web para usuários.")
%% Personalizações de cor diretas
AtualizarEstiloElemento(legacy_api, "#d9534f", "#ffffff", "#c9302c")
AtualizarEstiloElemento(modern_portal, "#5cb85c", "#ffffff", "#4cae4c")
Planta Real: Mapa de Contêiner de Fronteira do Sistema Empresarial de Comércio Eletrônico
Esta planta abrangente e em múltiplos níveis rastreia um ecossistema de comércio eletrônico online. Isola servidores centrais internos usando um Contêiner_Sistema contêiner de bloco, implementa retransmissões de notificação externas na nuvem por meio de System_Ext, mapeia armazenamentos internos de bancos de dados relacionais junto com microserviços externos de rastreamento e fixa pipelines de comunicação usando parâmetros explícitos da stack tecnológica.
C4Container
título "Modelo de Contêiner para Plataforma Empresarial de Comércio Eletrônico"
Pessoa(cliente, "Comprador Online", "Navega pelos itens do catálogo e adiciona produtos ao seu carrinho digital.")
System_Ext(gateway_pagamento, "Serviço API Stripe", "Banco de dados de cartões de crédito de terceiros e motor de processamento.")
System_Boundary(escopo_e_commerce, "Perímetro Central de Comércio Eletrônico") {
Container(aplicativo_front_end, "Aplicativo Web de Loja", "Next.js, React", "Entrega ativos estáticos e gerencia sessões de carrinho do usuário.")
Container(servico_checkout, "Microserviço de Checkout", "Node.js, Express", "Processa fluxos de trabalho do carrinho de compras e calcula impostos.")
ContainerDb(banco_pedidos, "Banco de Dados de Registro de Pedidos", "PostgreSQL", "Armazena linhas de transações históricas e registros de ledger seguros.")
}
%% Caminhos de Interação Arquitetônica
Rel(cliente, aplicativo_front_end, "Visualiza produtos e faz pedidos usando", "HTTPS/Navegador")
Rel_Down(aplicativo_front_end, servico_checkout, "Envia transações de compras via", "JSON/REST API")
Rel_Direita(servico_checkout, banco_pedidos, "Persiste estados transacionais dentro de", "SQL/Conexão JDBC")
Rel_Esquerda(servico_checkout, gateway_pagamento, "Autoriza chamadas de cobrança com token usando", "API Segura TLS/HTTPS")
Armadilhas Comuns de Sintaxe e Restrições do Sistema
Ao compilar mapas C4 limpos para frameworks de software, tenha cuidado com esses parâmetros de execução para evitar que o diagrama falhe:
- Formatação de Separador por Vírgula: Diferentemente de quase todos os outros esquemas Mermaid, os macros C4 exigem vírgulas estritas entre os parâmetros:
Pessoa(id, "Rótulo", "Desc"). Esquecer uma vírgula separadora fará com que o construtor de layout falhe completamente. - Aspas de Rótulo Reservadas: Campos de exibição, tags tecnológicas e blocos de descrição dentro de macros *devem* ser envolvidos por aspas duplas claras. Inserir textos brutos em campos sem envolver com aspas causa falhas de análise que quebram o diagrama.
- Ordem de Aninhamento de Limites: Ao envolver elementos dentro de um
System_BoundaryouEnterprise_Boundarybloco, você deve limpar explicitamente o conteúdo do espaço de trabalho usando chaves padrão{ }. Deixar uma chave de limite aberta ou combiná-las incorretamente quebra os layouts de renderização. - Inicialização de Alias Dinâmica: Você não pode desenhar relacionamentos (
Rel) para um identificador de alias que não tenha sido inicializado explicitamente por um bloco de macro de elemento acima dele. Mantenha seu fluxo de declaração avançando progressivamente de cima para baixo.