Diagrama de contexto

O diagrama de contexto responde a uma pergunta: que sistema é este, quem o usa e com que outros sistemas ele conversa? Ele é o único desenho que uma pessoa não técnica precisa entender, e por isso não mostra nada de dentro.

O que ele contém

o seu sistema, em destaque;
as pessoas e os papéis que o usam;
os sistemas de terceiros ou de outras equipes com que ele conversa;
as setas entre tudo isso, com rótulos em linguagem de negócio.

E nada mais. Sem containers, sem bancos de dados, sem tecnologia.

O modelo até aqui

elements:
  - id: colaborador
    name: Colaborador
    shape: actor
    description: Quem precisa de uma sala para a proxima reuniao.

  - id: reservas
    name: Reserva de Salas
    shape: system
    description: Procura salas livres, confirma reservas e avisa quem participa.

  - id: agenda-corporativa
    name: Agenda Corporativa
    shape: external
    technology: Google Workspace
    description: Onde a empresa inteira ja mantem os compromissos das pessoas.

relations:
  - from: colaborador
    to: reservas
    kind: sync
    label: Procura e reserva

  - from: reservas
    to: agenda-corporativa
    kind: sync
    label: Cria o evento na agenda

Três caixas, todas raízes — nenhuma tem parent —, portanto todas no nível context. Duas setas.

O diagrama

kind: diagram
id: contexto
title: Reserva de Salas — Contexto
level: context
order: 10
include:
  - level: context
relations: auto
subject: reservas

Campo por campo:


`kind: diagram`	diz que este documento é um diagrama
`id`	o identificador dele dentro do projeto. Sem ele, o nome do arquivo vale como identificador
`title`	o título exibido no desenho e na barra lateral
`level`	o nível em que o seletor de níveis do leitor abre este desenho
`order`	a posição na barra lateral. Padrão: 500
`include`	o critério de quem entra
`relations: auto`	desenha toda seta cujas duas pontas estão no desenho
`subject`	a caixa em foco, desenhada com destaque

`include: level: context` — um critério, não uma lista

Esta é a linha que faz o desenho não envelhecer:

include:
  - level: context

Ela não diz quais caixas mostrar; diz que tipo de caixa mostrar. Acrescentar um segundo sistema no arquivo ao lado o traz para este desenho sem ninguém editar aqui.

Nem todo diagrama de contexto quer isso. Num modelo grande, “toda raiz” pode ser gente demais, e aí você nomeia os membros um a um:

include:
  - ref: reservas
  - ref: colaborador
  - ref: agenda-corporativa

A escolha é sua, e as duas formas convivem na mesma lista. A regra prática: use um critério quando o conjunto é o que você quer de fato; use referências quando o diagrama é uma seleção editorial.

`subject`: o que está em foco

subject: reservas desenha aquela caixa com destaque. O foco é uma propriedade da visão, e nunca da caixa: o mesmo sistema pode estar em foco num diagrama e ser um coadjuvante em outro. Por isso o campo mora no diagrama.

subject também aceita uma lista, quando o desenho tem mais de um protagonista.

`relations: auto`, e as alternativas

Valor	Efeito
`auto`	desenha toda seta cujas duas pontas estão no desenho
`none`	não desenha seta nenhuma
uma lista de identificadores	desenha só aquelas setas
`{ exclude: [ids] }`	desenha todas menos aquelas

Sem o campo, o comportamento é o mesmo de auto. A lista explícita é rara e frágil — os identificadores derivados mudam se você trocar o tipo de uma seta —, mas existe para o desenho que precisa esconder uma integração específica.

Próximo passo

Diagrama de containers abre o sistema por dentro.