Diagrama de Component C4: guia completo com exemplos

O diagrama de component é o nível 3 do modelo C4 -- e é o nível com a pior reputação. O nível 1 (Contexto de Sistema) é fácil de desenhar e raramente muda. O nível 2 (Container) mapeia de forma limpa sobre aquilo que você implanta. Mas o nível 3? Ele dá zoom nas entranhas de um único container, o que significa que muda toda vez que um desenvolvedor reestrutura um pacote. A maioria das equipes ou pula esse nível por completo ou o desenha uma vez e deixa apodrecer.

É uma pena, porque um diagrama de component bem mantido é o artefato mais útil para um desenvolvedor que entra em um código. Ele responde à pergunta que todo recém-chegado faz: "onde fica de verdade a lógica de X?"

Este guia cobre o que é um diagrama de component C4, como ele difere de um diagrama de component UML, quando o nível 3 vale o custo de manutenção (e quando não vale), um exemplo completo resolvido, os erros que tornam diagramas de component inúteis e como mantê-los precisos sem fazer tudo à mão.

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

O que é um diagrama de Component C4?

Um diagrama de component abre um container -- uma unidade implantável do seu diagrama de container -- e revela os components dentro dele.

Em termos C4, um component é um agrupamento coeso de funcionalidades relacionadas por trás de uma interface bem definida. Pense nos principais blocos de construção dentro de uma aplicação:

• Um controller ou grupo de handlers HTTP
• Um serviço de domínio que detém uma fatia da lógica de negócio
• uma camada de repositório ou de acesso a dados
• Um client que envolve uma API externa
• Um middleware, interceptor ou worker em segundo plano

A palavra-chave é agrupamento. Um component é uma abstração sobre o código, não uma única classe ou arquivo. O component OrderService pode se estender por uma dúzia de arquivos, mas conceitualmente é uma única coisa: a parte do container responsável pela lógica de negócio de pedidos. Como diz a definição do glossário, um component C4 é "um agrupamento de código de nível mais alto com uma única responsabilidade" -- não um mapeamento 1:1 para uma classe de linguagem de programação.

O que o diagrama de component responde

• Como este container está estruturado internamente?
• Qual component detém qual responsabilidade?
• Como os components colaboram para atender a uma requisição?
• De onde se originam as chamadas a bancos de dados e sistemas externos?

O que ele deliberadamente deixa de fora

• Classes, interfaces e funções individuais (isso é nível 4, o diagrama de code)
• As entranhas de outros containers
• Detalhes de implantação e infraestrutura

Um container por diagrama, somente components. Se você se vê desenhando classes, deu zoom demais.

Diagrama de Component C4 vs. diagrama de Component UML

Isso confunde as pessoas constantemente, porque o UML também tem algo chamado "diagrama de component" -- e não é a mesma coisa.

Um diagrama de component UML modela componentes de software como unidades com interfaces fornecidas e requeridas (a famosa notação lollipop-and-socket, de pirulito e soquete), frequentemente enfatizando empacotamento físico, artefatos e relações de implantação. Ele vem com regras de notação formais e um metamodelo preciso.

Um diagrama de component C4 é mais solto e mais pragmático. Ele é simplesmente o nível 3 de uma hierarquia de zoom: caixas para components, setas para relações, uma curta descrição em texto em cada um. Não há notação especial a aprender. O valor vem da hierarquia -- todo box de component vive dentro de um container específico, que vive dentro de um sistema específico -- não da notação em si.

Na prática: se alguém pede um "diagrama de component" em um contexto C4, ela quer um mapa estrutural das entranhas de um container que um novo desenvolvedor consiga ler em dois minutos. Se ela quer interfaces de pirulito e estereótipos <<artifact>>, está pedindo UML.

Quando vale a pena manter o nível 3?

Aqui está a resposta honesta que a maioria dos guias evita: o nível 3 é o nível com a pior relação esforço-estabilidade de todo o modelo C4.

Diagramas de contexto mudam algumas vezes por ano. Diagramas de container mudam quando você adiciona ou remove um serviço -- talvez mensalmente. Diagramas de component mudam toda vez que alguém refatora um pacote, extrai um serviço ou renomeia um módulo. Se você os mantém à mão, está se inscrevendo para uma jardinagem constante e, no momento em que você para, o diagrama começa a mentir.

Então seja deliberado sobre onde você gasta esse esforço.

Crie um diagrama de component quando:

• O container é genuinamente complexo. Uma API backend com 15 pacotes, múltiplas camadas e fronteiras não óbvias merece um mapa. Um serviço CRUD de três endpoints não.
• A estrutura encarna um design deliberado. Se você usa arquitetura hexagonal, CQRS ou um esquema de camadas limpo, o diagrama de component torna a estrutura pretendida explícita -- e te dá algo para apontar quando um pull request a viola.
• Múltiplas equipes tocam o mesmo container. Código compartilhado precisa de um modelo mental compartilhado.
• O onboarding é um gargalo. Se novos desenvolvedores levam semanas para se localizar em um container, um diagrama de component se paga já com a primeira contratação.

Pule quando:

• O container é pequeno e sua estrutura de pastas é autoexplicativa.
• O container é de terceiros (você não desenha as entranhas do Redis).
• Ninguém vai se comprometer a mantê-lo atualizado. Um diagrama de component desatualizado é pior do que nenhum -- ele envia desenvolvedores com confiança para um código que não existe mais.

É exatamente por isso que o nível 3 é o nível que a maioria das equipes ou pula ou automatiza. Gerar components a partir da estrutura real do código -- e verificá-los contra ela -- remove o imposto de manutenção que mata os diagramas desenhados à mão. Mais sobre isso adiante.

Um exemplo resolvido: dentro de um container de API

Vamos tornar isso concreto. Pegue a plataforma de e-commerce do nosso guia do modelo C4 e dê zoom em um único container: a Order API (Go). No nível 2, ela é uma caixa. No nível 3, ela se abre em components.

Os components

As relações

[Auth Middleware] --> [Order Controller] : Passes authenticated requests
[Auth Middleware] --> [Admin Controller] : Passes authenticated requests (admin role)
[Order Controller] --> [Order Service] : Delegates business operations
[Admin Controller] --> [Order Service] : Delegates back-office operations
[Order Service] --> [Order Repository] : Reads/writes orders
[Order Service] --> [Payment Client] : Authorizes and captures payments
[Order Service] --> [Email Adapter] : Triggers transactional emails
[Order Service] --> [Event Publisher] : Emits domain events
[Order Repository] --> [Order Database (PostgreSQL)] : SQL
[Payment Client] --> [Payment Gateway (Stripe)] : HTTPS/REST
[Email Adapter] --> [Email Service (SendGrid)] : HTTPS/REST
[Event Publisher] --> [Message Queue (Kafka)] : Publishes events

Note que o banco de dados, o Stripe, o SendGrid e o Kafka aparecem nas bordas. Eles não são components deste container -- são containers vizinhos e sistemas externos -- mas mostrar de onde se originam as chamadas de saída é exatamente o que torna o diagrama útil.

O que este diagrama diz a um novo desenvolvedor

Em trinta segundos, um desenvolvedor que entra nesta equipe aprende:

1. O caminho da requisição: middleware → controller → service → repository. Existe exatamente um lugar onde a lógica de negócio vive, e não é o controller.
2. As fronteiras: todas as chamadas externas passam por adapters dedicados (Payment Client, Email Adapter). Se você precisa falar com o Stripe, você estende o client; você não importa o SDK em um controller.
3. Os efeitos colaterais: pedidos produzem eventos no Kafka e e-mails via SendGrid. Se um e-mail não é enviado, você sabe quais dois components verificar.
4. Onde adicionar código: uma nova funcionalidade de "vale-presente" claramente precisa de mudanças no controller, no service e possivelmente de um novo client -- e o diagrama mostra o padrão a seguir.

Esse último ponto é subestimado. Um diagrama de component não apenas descreve a estrutura -- ele a prescreve. Ele diz aos contribuidores como se parece "consistente com este código".

Erros comuns com diagramas de component

Mapear uma classe para um component

O erro mais frequente. Se o seu container tem 80 classes e o seu diagrama de component tem 80 caixas, você desenhou um diagrama de classes com passos extras. Components são agrupamentos: OrderController (um component) pode cobrir cinco classes de handler. Mire em 5-15 components por container. Se você passou de 20, suas abstrações estão granulares demais -- ou o seu container está fazendo coisas demais.

Documentar todo container no nível 3

A simetria é tentadora: "temos 12 containers, então precisamos de 12 diagramas de component". Resista. A maioria desses diagramas nunca será lida e nunca será atualizada. Documente os dois ou três containers onde a complexidade de fato dói e deixe a estrutura de pastas falar pelo resto.

Deixar o diagrama apodrecer

O nível 3 sofre drift mais rápido do que qualquer outro nível. Um diagrama de component desenhado em janeiro descreve um container que provavelmente não existe em junho. Cada refatoração, cada pacote extraído, cada módulo renomeado amplia a distância. E um diagrama confiantemente errado é pior do que nenhum diagrama: ele envia desenvolvedores à caça de components que foram deletados dois trimestres atrás. Se você não consegue automatizar a manutenção, ao menos coloque "atualizar o diagrama de component" na checklist de pull request daquele container.

Desenhar components sem responsabilidades

Uma caixa rotulada OrderManager sem descrição é ruído. Todo component deveria carregar uma declaração de responsabilidade de uma linha ("Valida tokens JWT e injeta a identidade do usuário"). Se você não consegue escrever essa frase, a fronteira do component provavelmente está errada.

Mostrar detalhe de implementação em vez de estrutura

Generics, design patterns, utilitários auxiliares -- nada disso pertence ao nível 3. Se a parte interessante de um component é como ele é implementado, isso é tarefa para o diagrama de code (ou, mais frequentemente, para o próprio código).

Como a Archyl mantém os diagramas de component precisos

Tudo acima aponta para a mesma conclusão: diagramas de component são valiosos, mas mantê-los à mão é um jogo perdido. Esse é exatamente o problema que a Archyl foi construída para resolver.

A descoberta por IA extrai components do código

Em vez de desenhar components à mão, você conecta seu repositório e roda a descoberta por IA. A Archyl analisa a estrutura do seu código -- pacotes, módulos, camadas, convenções de nomenclatura -- e propõe um modelo C4, incluindo os components dentro de cada container e as relações entre eles. Um serviço Go com os pacotes handlers/, service/ e repository/ retorna exatamente como o tipo de diagrama de component mostrado no exemplo acima. Você revisa as sugestões, aceita ou ajusta, e tem um modelo de nível 3 em minutos.

A detecção de drift sinaliza a divergência

Esta é a parte que mantém o nível 3 vivo. Como a Archyl vincula components a arquivos e diretórios reais no seu repositório, ela pode verificar continuamente se os components documentados ainda existem no código. Quando alguém deleta um pacote, renomeia um módulo ou reestrutura uma camada, o score de drift cai e os components afetados são sinalizados. Seu diagrama de component deixa de ser um instantâneo e se torna um contrato monitorado.

Arquitetura como Código

Se você prefere definições explícitas à descoberta, a Archyl suporta definir seu modelo C4 -- sistemas, containers, components e relações -- em YAML que vive no seu repositório. Seu diagrama de component é versionado, revisado em pull requests e renderizado automaticamente. Combinado com a detecção de drift, isso te dá documentação de nível 3 com as características de manutenção de código.

FAQ

Qual é a diferença entre um diagrama de component C4 e um diagrama de component UML?

Um diagrama de component UML é uma notação formal com interfaces fornecidas/requeridas, artefatos e estereótipos, focada em modelar componentes como unidades empacotadas. Um diagrama de component C4 é o nível 3 da hierarquia de zoom do C4: uma visão pragmática de caixas-e-setas dos components dentro de um container específico. O C4 não tem requisitos de notação formal -- seu valor vem da hierarquia consistente (system → container → component → code), não dos símbolos.

Um component é o mesmo que uma classe?

Não. Um component C4 é um agrupamento coeso de código por trás de uma interface bem definida -- ele pode ser implementado como uma classe, uma dúzia de classes, um pacote ou um módulo. Se o seu diagrama de component tem uma caixa por classe, você desceu um nível de zoom a mais.

Todo container precisa de um diagrama de component?

Não, e tentar documentar todo container no nível 3 é uma das formas mais rápidas de abandonar o C4. Crie diagramas de component apenas para containers que são complexos, compartilhados entre equipes ou centrais para o onboarding. Para o resto, o diagrama de container mais uma estrutura de pastas legível é suficiente.

Quantos components um diagrama de component deve mostrar?

Aproximadamente de 5 a 15. Menos de 5 e o diagrama provavelmente não está te dizendo nada que o diagrama de container já não dissesse. Mais de 20 e ou as fronteiras dos seus components estão granulares demais ou o próprio container deveria ser dividido.

Quer diagramas de component que permaneçam precisos? Experimente a Archyl gratuitamente e gere um modelo C4 -- components incluídos -- a partir do seu código em minutos. Ou continue lendo: O que é o modelo C4? Um guia completo | Guia do diagrama de Container C4 | Guia do diagrama de Code C4 | Diagrama de Component no glossário.