O que é um diagrama de contexto?
Um diagrama de contexto (ou System Context Diagram) mostra seu software no centro e, ao redor, todos os atores externos que interagem com ele: usuários, sistemas de terceiros, integrações. É o nível 1 do C4 Model e o único diagrama que deveria existir antes mesmo do MVP começar.
Ele não fala de tecnologia. Não menciona banco, cloud, linguagem. Fala de fronteiras: o que é seu, o que é dos outros, e por onde os dados atravessam essa fronteira.
Por que ele é tão valioso?
- Onboarding em 5 minutos. Um dev novo entende o negócio antes do primeiro
git clone. - Alinhamento com stakeholders. Diretor de produto, comercial e jurídico enxergam o mesmo mapa que o time técnico.
- Detecta dependências invisíveis. Ao listar tudo que "conversa" com o sistema, aparecem integrações que ninguém tinha lembrado — e cada uma é uma potencial falha em produção.
- Base para análise de segurança. Threat modeling começa exatamente aqui: quais são as fronteiras de confiança?
Elementos de um diagrama de contexto
- O sistema — uma única caixa no centro, com o nome do produto.
- Personas — pessoas que usam o sistema (cliente final, admin interno, operador).
- Sistemas externos — APIs de terceiros (Stripe, gateways, ERPs, CRMs), sistemas legados internos, provedores de identidade.
- Setas rotuladas — cada seta descreve o que flui e por qual protocolo: "envia webhook via HTTPS", "consulta saldo via REST", "recebe notificação via email".
Exemplo: sistema de assinaturas
Suponha um SaaS de assinaturas B2B. O diagrama de contexto teria:
Cliente (persona) ─── acessa via HTTPS ──► [ SaaS de Assinaturas ]
Admin interno (persona) ─── gerencia via HTTPS ──► [ SaaS de Assinaturas ]
[ SaaS de Assinaturas ] ─── cobra recorrente ──► Stripe (sistema externo)
[ SaaS de Assinaturas ] ─── emite NFS-e ──► Prefeitura (sistema externo)
[ SaaS de Assinaturas ] ─── envia email transacional ──► Resend (sistema externo)
[ SaaS de Assinaturas ] ─── SSO ──► Google Identity (sistema externo)Quatro integrações externas. Cada uma é um ponto de falha, um custo variável, e um risco de compliance. Sem o diagrama de contexto, esse mapa fica na cabeça de uma ou duas pessoas.
Regras práticas para um bom diagrama de contexto
- Uma página, sempre. Se não coube numa tela, você está descrevendo contêineres, não contexto.
- Rotule toda seta. Seta sem rótulo é decoração, não documentação.
- Direção da seta = direção do fluxo iniciador. Se seu sistema é quem chama a API, a seta sai de você.
- Sem detalhes de tecnologia. "PostgreSQL 16 na AWS us-east-1" não pertence aqui — pertence ao nível de contêineres.
- Legenda. Cor de pessoa ≠ cor de sistema. Um quadrado explicando.
Diagrama de contexto vs diagrama de contêineres
A confusão mais comum: colocar Postgres, Redis e Kafka no diagrama de contexto. Isso é nível 2 (contêineres), não nível 1. A regra: se o item é seu (você mantém, você derruba, você atualiza), ele fica dentro da caixa do sistema no diagrama de contexto. Só o que está fora do seu controle vira caixa separada.
Faça uma vez, mantenha vivo
Diagrama de contexto muda pouco — talvez 2-3 vezes por ano em um produto ativo. Justamente por isso, ele deveria ser versionado como código no mesmo repo do produto. Toda vez que uma integração é adicionada ou removida, o PR atualiza o diagrama junto. É a diferença entre documentação viva e ficção.