de_DEen_USes_ESfa_IRjapt_PTru_RU

Dominando o Diagrama de Container C4: Aprofundando nas Escolhas de Tecnologia, Responsabilidades e Comunicação (com Exemplos em PlantUML)

O que é um Diagrama de Container C4?

O diagrama de container éNível 2no modelo C4 de Simon Brown. Ele se aprofunda em um único sistema de software (definido no Nível 1 – Contexto do Sistema) para mostrar:

The Ultimate Guide to C4 Model Visualization with Visual Paradigm's AI Tools - ArchiMetric

  • Oformato de alto nívelda arquitetura dentro dos limites do seu sistema.

  • Unidades principaisunidades implantáveis/executáveischamadascontainers.

  • Escolhas de tecnologiapara cada container.

  • Como os containersinteragementre si e com atores/sistemas externos.

Importante esclarecimento: Um “container” no C4não énecessariamente um container Docker. É qualquer unidade separadamente implantável/executável que execute código ou armazene dados. Exemplos:

  • Aplicação web / Aplicação de página única (SPA)

  • Aplicativo móvel

  • API do lado do servidor / microserviço

  • Banco de dados (esquema)

  • Armazenamento de arquivos (bucket S3, pasta do sistema de arquivos)

  • Broker de mensagens / fila (quando modelado explicitamente)

  • Aplicativo de desktop / CLI

  • Processo em lote / tarefa agendada

O diagrama permanecede alto nível — sem detalhes internos de classes ou código (isso é Nível 3 de Componentes ou Nível 4 de Código).

Quando criar um diagrama de container

Crie (e mantenha) um diagrama de container quando:

  • Você já concluiu (ou pelo menos esboçou) o Diagrama de Contexto do Sistema diagrama e precisar responder: “Quais são os principais blocos de construção dentro do nosso sistema?”

  • Onboarding de novos desenvolvedores, arquitetos ou equipe de operações — eles precisam entender rapidamente a pilha de tecnologias e as responsabilidades de alto nível.

  • Tomando decisões significativas de tecnologia ou arquitetura (monolito → microsserviços, adição de aplicativo móvel, escolha de banco de dados, introdução de filas de mensagens, migração para nuvem).

  • Documentação para auditorias, conformidade, revisões de segurança ou resposta a incidentes (ajuda a mostrar a superfície de ataque e fluxos de dados).

  • Você quer “arquitetura como código” que reside no repositório e evolui com o sistema.

  • A maioria das equipes para aqui — Simon Brown ele mesmo observa que Contexto do Sistema + Container diagramas são suficientes para a maioria das equipes de software. Só vá mais fundo (Componentes/Código) quando a complexidade dentro de um container justificar isso.

Pule ou adie se:

  • O sistema é extremamente simples (um processo + banco de dados).

  • Você está em uma fase muito inicial de ideação e precisa apenas do contexto geral.

Por que usar diagramas de container? (Principais benefícios)

  • Clareza para diferentes públicos
    Desenvolvedores veem tecnologias e pontos de integração.
    Equipes de Ops/infra veem unidades implantáveis e caminhos de comunicação.
    Arquitetos veem limites de responsabilidade e riscos de dívida técnica.
    Gerentes veem uma visão suficientemente neutra em relação à tecnologia, mas ainda concreta.

  • Evita o problema do “um grande diagrama”
    Evita jogar tudo (usuários + infraestrutura + classes + ícones de nuvem) em uma única imagem sobrecarregada.

  • Destaca decisões importantes
    Exibe claramente escolhas como SPA + API + banco de dados relacional vs. renderização do lado do servidor + NoSQL, ou síncrono vs. baseado em eventos.

  • Comunicação e colaboração
    Atua como um mapa compartilhado durante sessões de design, pós-análises de incidentes, modelagem de ameaças e planejamento estratégico.

  • Documentação viva
    Quando escrito em PlantUML / Structurizr DSL / semelhantes → versionado no Git, regenerado automaticamente no CI, sempre atualizado.

Como criar um ótimo diagrama de contêineres (Passo a passo + Melhores práticas)

  1. Comece pelo Nível 1
    Copie Pessoas + Sistemas de Software externos do diagrama de contexto — eles se tornam atores que interagem com seus contêineres.

  2. Desenhe a Fronteira do Sistema
    Use Fronteira_Sistema no PlantUML para delimitar claramente “dentro do nosso sistema”.

  3. Identifique os Contêineres
    Pergunte: Quais são as coisas separadamente executáveis/implantáveis que entregam a funcionalidade do sistema?
    Padrões comuns:

    • SPA Web ↔ Backend da API ↔ Banco de dados

    • Aplicativo móvel ↔ Backend para frontend (BFF) ↔ Serviços compartilhados

    • Microserviços com broker de mensagens

    • Monólito legado + nova camada de API

  4. Adicione Tecnologia e Descrição Breve
    Cada contêiner deve mostrar: nome, tecnologia, propósito breve.
    Mantenha as descrições com menos de 15 palavras.

  5. Defina Interações (Relacionamentos)
    Mostre direção + protocolo + intenção (por exemplo, “JSON/HTTPS”, “Lê de e escreve para”, “Publica para”, “Consome de”).
    Use verbos nos relacionamentos.

  6. Melhores práticas

    • Mantenha-o legível — busque menos de 10–12 contêineres. Se houver mais → crie visualizações focadas (por exemplo, “contêineres do subsistema API”).

    • Seja consistente — mesma direção de layout (de cima para baixo/esquerda para direita), mesmo nível de detalhe.

    • Use ícones/sprites — adicione destaque visual (o PlantUML suporta devicons, font-awesome, etc.).

    • Legenda e chave — ative a legenda automática no PlantUML.

    • Evite aglomeração — omita filas/tópicos se eles não adicionarem valor; rotule os protocolos nas setas em vez disso.

    • Versão e armazene como código — faça commit dos arquivos .puml no repositório.

    • Adaptação para o público-alvo — uma versão para desenvolvedores (tecnologia detalhada), versão mais leve para interessados.

Exemplo do PlantUML – Sistema Clássico de Banco na Internet (estilo Big Bank plc)

Aqui está um exemplo limpo e de qualidade de produção usando a biblioteca oficial C4-PlantUML.

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

' Opcional: adicione ícones atraentes (dos sprites do tupadr3)
!include https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons/angular.puml
!include https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons/java.puml
!include https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons/postgresql.puml
!include https://raw.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/master/devicons/android.puml

title Diagrama de Contêiner: Sistema de Banco na Internet

Person(customer, "Cliente de Banco Pessoal", "Um cliente da Big Bank plc")

System_Boundary(c1, "Sistema de Banco na Internet") {
    Container(spa, "Aplicativo de Página Única", "JavaScript & Angular", "Fornece todas as funcionalidades de banco na internet para os clientes por meio de seu navegador web", $sprite="angular")
    Container(mobile, "Aplicativo Móvel", "Android/iOS (React Native)", "Funcionalidades limitadas de banco na internet", $sprite="android")
    Container(api, "Aplicativo de API", "Java & Spring Boot", "Fornece funcionalidades de banco na internet por meio de API", $sprite="java")
    ContainerDb_Ext(db, "Banco de Dados de Banco", "PostgreSQL", "Armazena preferências do usuário, dados em cache, sessões (as contas principais/transações permanecem no mainframe)", $sprite="postgresql")
}

System_Ext(core, "Sistema de Banco Central", "Sistema mainframe – existente")
System_Ext(email, "Sistema de E-mail", "Envia e-mails (por exemplo, AWS SES)")

Rel(customer, spa, "Usa", "HTTPS")
Rel(customer, mobile, "Usa", "HTTPS")

Rel(spa, api, "Chama", "JSON/HTTPS")
Rel(mobile, api, "Chama", "JSON/HTTPS")

Rel(api, db, "Lê e escreve em", "JDBC/SQL")
Rel(api, core, "Usa", "JSON/HTTPS")
Rel(api, email, "Envia e-mail usando", "HTTPS")

LAYOUT_WITH_LEGEND()
LAYOUT_TOP_DOWN()

@enduml

Isso gera um diagrama limpo com:

  • Fronteira do sistema

  • Rótulos de tecnologia

  • Sprites/ícones

  • Relacionamentos claros

  • Legenda

Você pode colá-lo diretamente no servidor online do PlantUML ou em qualquer IDE/editor compatível.

Use esta estrutura como modelo — substitua os elementos pelos nomes, tecnologias e fluxos do seu próprio sistema. Para estilos mais avançados (temas, cores personalizadas), verifique as amostras do C4-PlantUML no GitHub.

Feliz diagramação — e lembre-se: o objetivo écomunicação eficaz, não a perfeição do UML!

Recursos do Diagrama de Contêiner C4

This post is also available in Deutsch, English, Español, فارسی, 日本語 and Ру́сский.