O diagrama de Contexto de Sistema é o nível 1 do modelo C4 -- o diagrama de arquitetura mais importante que sua equipe pode criar. Este guia explica o que pertence a um diagrama de contexto C4, percorre um exemplo completo de diagrama de contexto e mostra como criá-lo manualmente ou gerá-lo a partir do seu código.

Diagrama de Contexto de Sistema C4: guia completo com exemplos

Se você for desenhar apenas um diagrama de arquitetura na vida, que seja um diagrama de Contexto de Sistema. Ele é a porta de entrada do modelo C4, o diagrama que todo stakeholder consegue ler sem treinamento e a forma mais rápida de expor divergências sobre o que o seu sistema realmente faz.

Ainda assim, a maioria das equipes erra. Elas enfiam bancos de dados, microsserviços e clusters Kubernetes até que o diagrama de "contexto" vire um mapa de infraestrutura ilegível. Ou pulam essa etapa por completo e vão direto para um diagrama de Container, deixando os stakeholders não técnicos sem nada que possam compreender.

Este guia é um mergulho profundo no nível 1 do modelo C4: o que é um diagrama de contexto de sistema, exatamente o que pertence a ele (e o que não pertence), um exemplo completo resolvido, os erros que arruínam a maioria dos diagramas de contexto e um processo passo a passo para criar um -- à mão ou gerado a partir do seu código. Se você é novo no modelo C4 em si, comece pelo nosso guia completo do modelo C4 e depois volte aqui.

O que é um diagrama de Contexto de Sistema?

Um diagrama de Contexto de Sistema é o primeiro e mais alto nível de diagrama do modelo C4. Ele mostra um sistema de software como uma única caixa e responde a uma única pergunta: como esse sistema se encaixa no seu ambiente?

Como diz a definição do glossário, o diagrama de Contexto de Sistema foca nas pessoas e nos sistemas externos que interagem com o sistema descrito, omitindo deliberadamente a estrutura interna. Seu objetivo é estabelecer o escopo: quem usa o sistema, de quais sistemas ele depende e quais sistemas dependem dele.

Três tipos de elementos aparecem em um diagrama de contexto, e somente três:

Seu sistema de software -- uma caixa, no centro. Não os seus serviços, não os seus bancos de dados. Uma caixa.
Pessoas -- os usuários, papéis ou personas que interagem com o sistema. Um "Cliente", um "Administrador", um "Agente de Suporte".
Sistemas de software externos -- os sistemas com os quais o seu conversa, mas que a sua equipe não controla: um gateway de pagamento, um provedor de e-mail, um ERP legado, um provedor de identidade.

Conectando-os estão as relações: setas rotuladas que descrevem quem faz o quê. "Faz pedidos usando", "Envia solicitações de pagamento para", "Recebe atualizações de envio de".

Esse é todo o vocabulário. Caixas para o sistema, as pessoas e os sistemas externos; setas para as relações. A disciplina do diagrama vem daquilo que você deixa de fora.

Quem é o público?

O diagrama de Contexto de Sistema é único entre os quatro níveis do C4 porque foi projetado para todo mundo -- incluindo pessoas que jamais lerão uma linha de código:

Stakeholders não técnicos. Um product manager, um CEO ou um responsável por compliance consegue olhar um diagrama de contexto e entender o propósito do sistema, seus usuários e suas dependências de terceiros em menos de um minuto.
Novos membros da equipe. Antes de um novo engenheiro aprender a sua estrutura de pastas, ele deveria aprender a fronteira do seu sistema. O diagrama de contexto é o slide número um do onboarding.
Arquitetos e revisores de segurança. Toda seta que cruza a fronteira do sistema é um ponto de integração, um fluxo de dados e uma potencial superfície de ataque. Revisões de segurança e compliance costumam começar por aqui.
Outras equipes. Quando outra equipe pergunta "o seu sistema chama a API de cobrança diretamente?", o diagrama de contexto responde sem precisar de reunião.

É por isso que escolhas de tecnologia não pertencem aqui. No momento em que você escreve "PostgreSQL" ou "Kafka" em um diagrama de contexto, você reduziu o público a engenheiros -- e para isso você tem o diagrama de Container.

O que pertence a um diagrama de contexto (e o que não pertence)

Inclua

O sistema em escopo -- exatamente uma caixa, claramente nomeada.
Toda categoria de usuário -- não pessoas individuais, mas papéis ou personas. Se clientes e funcionários de almoxarifado usam o sistema de formas diferentes, são duas caixas-de-pessoa separadas.
Toda dependência de sistema externo -- incluindo aquelas que você dá como certas: o serviço de e-mail, o provedor de identidade, a plataforma de analytics, o stack de monitoramento se for arquiteturalmente relevante.
Sistemas que dependem de você -- se o sistema de um parceiro consome sua API, ele pertence ao diagrama, com a seta apontando para você.
Relações rotuladas -- toda seta precisa de uma frase com verbo. Uma seta sem rótulo é um ponto de interrogação.

Exclua

Containers -- nada de aplicações web, nada de serviços de API, nada de bancos de dados, nada de filas de mensagens. Isso é nível 2.
Escolhas de tecnologia -- nada de "React", nada de "Go", nada de "PostgreSQL". Um diagrama de contexto deve sobreviver a uma reescrita completa do seu stack sem mudar.
Estrutura interna de sistemas externos -- o Stripe é uma caixa, não um diagrama da arquitetura do Stripe.
Detalhes de infraestrutura e de implantação -- nada de regiões, nada de clusters, nada de load balancers.
Funcionalidades individuais -- o diagrama mostra relações, não uma lista de features.

Um teste simples: se remover um elemento não mudaria quem interage com o sistema ou quais sistemas externos ele toca, esse elemento não pertence ao nível 1.

Um exemplo completo de diagrama de contexto: plataforma de pagamentos online

Vamos trabalhar com um exemplo realista. Imagine que você está documentando a PayFlow, uma plataforma de pagamentos online que permite a comerciantes aceitar pagamentos com cartão em seus sites.

Passo 1: Nomeie o sistema

Uma caixa no centro: Plataforma de Pagamentos PayFlow. Dê a ela uma descrição de uma linha: "Permite que comerciantes aceitem e gerenciem pagamentos online com cartão."

Passo 2: Identifique as pessoas

Quem interage com a PayFlow, e em que papel?

Comerciante -- dono de negócio que configura páginas de pagamento, visualiza transações e dispara reembolsos.
Cliente Final -- um comprador que paga por uma compra através de um checkout da PayFlow.
Agente de Suporte -- funcionário interno que investiga transações contestadas.

Passo 3: Identifique os sistemas externos

De que a PayFlow depende, e o que depende da PayFlow?

Bandeiras de Cartão / Banco Adquirente -- autoriza e liquida transações com cartão.
Serviço de Detecção de Fraude -- pontua transações quanto ao risco de fraude.
Serviço de E-mail -- envia recibos e notificações.
Provedor de Identidade -- gerencia o single sign-on dos comerciantes.
Site E-Commerce do Comerciante -- o próprio site do comerciante, que incorpora o checkout da PayFlow e consome a API da PayFlow.
Plataforma Contábil -- recebe relatórios de liquidação para a contabilidade do comerciante.

Passo 4: Desenhe as relações

A lista completa de elementos e relações fica assim:

People:
  [Merchant]          --> [PayFlow] : Configures payments, views transactions, issues refunds
  [End Customer]      --> [PayFlow] : Pays for purchases via hosted checkout
  [Support Agent]     --> [PayFlow] : Investigates and resolves disputes

External systems:
  [Merchant E-Commerce Site] --> [PayFlow] : Initiates payments via API, embeds checkout
  [PayFlow] --> [Card Networks / Acquiring Bank] : Authorizes and settles card transactions
  [PayFlow] --> [Fraud Detection Service] : Requests risk scores for transactions
  [PayFlow] --> [Email Service] : Sends receipts and payment notifications
  [PayFlow] --> [Identity Provider] : Delegates merchant authentication
  [PayFlow] --> [Accounting Platform] : Exports settlement reports

Dez elementos no total: um sistema, três pessoas, seis sistemas externos. Toda seta tem uma frase com verbo. Não há menção a serviços, bancos de dados, filas ou linguagens -- e, ainda assim, qualquer pessoa que leia este diagrama entende o que é a PayFlow, quem a usa e do que ela depende.

Repare no que este diagrama torna imediatamente visível:

Superfície de compliance. Bandeiras de cartão e detecção de fraude no diagrama dizem a um revisor de segurança exatamente onde os dados relevantes para PCI trafegam.
Risco de fornecedor. Seis dependências externas, cada uma um potencial ponto de falha ou de negociação contratual.
Fronteira bidirecional. O site e-commerce do comerciante chama para dentro da PayFlow -- o sistema não é apenas um consumidor de outros serviços, ele é também uma dependência para outra pessoa.

É esse o tipo de conversa que um diagrama de contexto foi feito para iniciar.

Erros comuns em diagramas de Contexto de Sistema

Erro 1: Detalhe demais

A falha mais comum. O diagrama começa limpo, depois alguém adiciona "só o banco de dados principal", depois o API gateway, depois os três microsserviços principais e, em um mês, ele virou um diagrama de Container usando o nome de um diagrama de contexto. A correção é implacável: o seu sistema é uma caixa. Se você sente vontade de mostrar as entranhas, esse é o sinal para criar um diagrama de Container como uma visão separada e vinculada -- não para sobrecarregar este aqui.

Erro 2: Dependências externas faltando

As equipes esquecem de forma confiável as dependências que consideram chatas: o provedor de e-mail, o gateway de SMS, o provedor de identidade, a CDN, o serviço de feature-flags. Mas dependências "chatas" causam indisponibilidades reais e lock-in de fornecedor real. Percorra seus arquivos de configuração e variáveis de ambiente -- toda chave de API geralmente corresponde a um sistema externo que pertence ao diagrama.

Erro 3: Misturar níveis de abstração

Um diagrama que mostra "Cliente → App Web → API de Pedidos → PostgreSQL → Stripe" mistura uma pessoa, dois containers, um banco de dados e um sistema externo em uma única visão achatada. O leitor não consegue dizer onde fica a fronteira do seu sistema. Cada diagrama C4 deve viver em exatamente um nível de zoom; o objetivo central da hierarquia do modelo C4 é que você dá zoom entre diagramas, nunca dentro de um.

Erro 4: Relações sem rótulo ou vagas

"Usa" não é um rótulo de relação -- tudo "usa" tudo. Escreva o que realmente acontece: "Envia pedidos via", "Recebe eventos de webhook de", "Autentica-se contra". Os rótulos são onde mora a maior parte da informação do diagrama.

Erro 5: Desenhar uma vez e nunca atualizar

Um diagrama de contexto de 2023 que ainda mostra o CRM legado do qual você migrou no ano passado é ativamente enganoso. Diagramas de contexto mudam com menos frequência do que diagramas de níveis mais baixos, mas mudam -- a cada nova integração de fornecedor, a cada API de parceiro descontinuada. Trate o diagrama como documentação viva, não como um artefato de kickoff.

Como criar um diagrama de Contexto de Sistema: passo a passo

A abordagem manual

Nomeie e descreva o sistema. Uma frase: o que ele faz, para quem?
Liste os papéis de usuário. Faça um brainstorm de toda persona distinta que interage com o sistema. Una papéis que interagem de forma idêntica; separe papéis que não interagem.
Liste os sistemas externos. Percorra integrações, chaves de API, webhooks, exportações agendadas. Inclua sistemas que chamam você, não apenas sistemas que você chama.
Desenhe as relações. Uma seta por interação significativa, cada uma rotulada com uma frase com verbo. A direção segue a iniciativa: quem inicia a interação?
Revise com a equipe. Este é o passo de maior valor. Uma revisão de 30 minutos revela de forma confiável as divergências: "espera, a gente ainda chama esse serviço?", "desde quando parceiros batem direto na nossa API?". Esses debates são a entrega.
Publique onde as pessoas vão encontrá-lo -- não enterrado em uma página de wiki que ninguém visita.

Qualquer ferramenta serve para o desenho em si: um quadro branco, diagrams.net, Structurizr, PlantUML com extensões C4. O gargalo nunca foi o desenho -- são os passos 2, 3 e 5, e manter o resultado preciso ao longo do tempo.

A abordagem automatizada: gerando diagramas de contexto com a Archyl

É aqui que a Archyl segue um caminho diferente das ferramentas de desenho. Em vez de partir de uma tela em branco, você conecta seus repositórios e roda a descoberta por IA: a Archyl analisa a estrutura do seu código, arquivos de configuração e grafos de dependências e então propõe um modelo C4 em rascunho -- sistemas, dependências externas, containers, components e as relações entre eles. Você revisa cada sugestão, aceita ou ajusta, e a visão de Contexto de Sistema é renderizada automaticamente a partir do modelo.

Como o diagrama é gerado a partir de um modelo em vez de desenhado à mão, duas coisas decorrem disso:

Os níveis permanecem conectados. A caixa do sistema no seu diagrama de contexto é a mesma entidade na qual você dá zoom para a visão de container. Sem drift de copiar e colar entre diagramas.
A obsolescência se torna mensurável. A detecção de drift da Archyl compara continuamente a arquitetura documentada com o que de fato existe no código, então, quando uma integração é removida ou um serviço é renomeado, você descobre por um score de drift em vez de por um novo contratado confuso.

Se você prefere documentação que vive no controle de versão, a Archyl também suporta um fluxo de Arquitetura como Código: defina seu modelo C4 em YAML, faça commit junto ao seu código e deixe os diagramas renderizarem a partir dessa definição.

Do contexto aos containers

O diagrama de Contexto de Sistema estabelece a fronteira; o próximo nível abre a caixa. Uma vez que seu diagrama de contexto esteja estável, o passo seguinte natural é o diagrama de container -- a visão de nível 2 que mostra as unidades implantáveis (apps web, APIs, bancos de dados, brokers) dentro do seu sistema e como elas se comunicam. Cobrimos isso em detalhe no nosso guia do diagrama de Container C4.

A progressão importa. Equipes que pulam o diagrama de contexto e começam no nível 2 tendem a produzir diagramas de container com fronteiras imprecisas -- sistemas externos misturados com serviços internos, porque ninguém nunca chegou a um acordo sobre onde o sistema termina.

FAQ

Qual é a diferença entre um diagrama de Contexto de Sistema e um diagrama de Container?

O diagrama de contexto (nível 1) mostra seu sistema como uma única caixa e foca no seu ambiente: usuários e sistemas externos. O diagrama de container (nível 2) dá zoom dentro dessa caixa para mostrar as unidades implantáveis -- apps web, serviços, bancos de dados -- e suas escolhas de tecnologia. O contexto responde "com o que esse sistema interage?"; os containers respondem "do que esse sistema é feito?".

Quantos elementos um diagrama de contexto deve ter?

Não há regra fixa, mas a maioria dos diagramas de contexto saudáveis tem um sistema, de dois a cinco papéis de usuário e de três a dez sistemas externos. Se você passou de quinze ou vinte elementos, ou a fronteira do seu sistema está ampla demais, ou você está documentando um panorama corporativo -- caso em que o diagrama de Panorama de Sistemas C4 (vários sistemas em uma visão) é o melhor encaixe.

Bancos de dados devem aparecer em um diagrama de Contexto de Sistema?

Não -- desde que o banco de dados pertença ao seu sistema, ele é um detalhe interno e aparece no nível de container. A exceção é um banco de dados operado por outra equipe ou fornecedor do qual seu sistema lê diretamente; isso é, na prática, um sistema externo e pode aparecer como tal.

Um diagrama de contexto C4 é o mesmo que um diagrama de contexto UML ou de fluxo de dados?

Conceitualmente são primos -- a ideia de um "diagrama de contexto" (um sistema, seu ambiente) é anterior ao C4 e existe na prática de análise estruturada e de UML. A versão C4 se distingue pelo seu lugar em uma hierarquia: todo elemento nela pode ser decomposto no nível seguinte abaixo, dando a você um mapa navegável em vez de uma figura isolada.

Pronto para criar seu diagrama de Contexto de Sistema? Experimente a Archyl gratuitamente e gere um modelo C4 diretamente a partir dos seus repositórios. Ou continue lendo: O que é o modelo C4? Um guia completo | Guia do diagrama de Container C4 | Diagrama de Contexto de Sistema no glossário.

Diagrama de Contexto de Sistema C4: guia completo com exemplos - Archyl Blog