Como um diagrama escolhe o que mostra

Um diagrama não guarda a lista dos seus membros. Ele guarda uma pergunta, e a resposta é calculada a cada leitura. É a diferença que mais custa quando se ignora, e a que faz um desenho não envelhecer.

Esta página explica cada peça dessa pergunta e a ordem em que elas se aplicam.

A ordem da resolução

1. include     quem entra                  (ou os filhos de `scope`, se não houver include)
2. where       filtra o que entrou
3. exclude     tira quem o seletor pegar
4. neighbors   puxa quem encosta, como contexto mudo, fora da fronteira
5. relações    projeta cada ponta na caixa mais próxima que o desenho mostra
6. grupos      as bandas, sobre quem está DENTRO da fronteira
7. subject     marca quem está em foco

A ordem importa: where filtra só o que include trouxe, e exclude age depois do filtro. Nenhum dos três alcança o que neighbors puxa depois.

scope: a caixa que o diagrama detalha

scope: reservas

Faz três coisas:

• desenha a fronteira, uma moldura com o nome daquela caixa;
• define o padrão de include como os filhos diretos do escopo;
• torna o diagrama o destino de quem descer para dentro daquela caixa no leitor.

O escopo é a moldura, e não um membro: ele não aparece como caixa dentro do próprio desenho.

Os seletores

Um seletor nomeia um conjunto sem listá-lo. Estes são todos:

Seletor	O que traz
ref: <caixa>	exatamente aquela caixa
children: <caixa>	os filhos diretos dela
descendants: <caixa>	todos os descendentes, em qualquer profundidade
descendants: <caixa> + depth: <n>	os descendentes até n níveis abaixo
tag: <etiqueta>	quem tem aquela etiqueta. Aceita uma lista, que combina com ou
meta: { <chave>: <valor> }	quem tem aquele metadado. O valor aceita uma lista
level: <nível>	context, container, component ou code. Aceita lista
shape: <forma>	quem tem aquela forma. Aceita lista
project: <id>	tudo de um projeto

Uma string solta é atalho para ref:

include:
  - reservas          # o mesmo que { ref: reservas }
  - ref: colaborador
  - tag: nucleo
  - level: [container, component]

Vários seletores na mesma lista somam — a união de todos.

Um seletor que não acha nada

Um ref para uma caixa inexistente é erro, e o cfour check reprova. Já um tag: que não casa com ninguém é legítimo — o conjunto simplesmente é vazio. Quando o diagrama inteiro fica vazio, você recebe um aviso com o nome dele.

where: um filtro sobre o que entrou

include:
  - descendants: reservas
where:
  level: container

where aceita os mesmos seletores menos ref, children e descendants — ou seja, tag, meta, level, shape e project. A razão é que os três de fora produzem conjuntos, e não respondem “sim ou não” sobre uma caixa.

exclude: tirar quem o seletor pegar

scope: reservas
exclude:
  - ref: sincronizador
  - tag: legado

Aceita todos os seletores, com a mesma sintaxe de include.

neighbors: quem encosta, sem entrar

neighbors: 1

Traz para o desenho quem tem uma seta com a outra ponta já dentro. Essas caixas aparecem esmaecidas e fora da fronteira — são contexto, não membros.

Dois detalhes que evitam surpresa:

• um vizinho de outra árvore aparece como o sistema dele, e não como o componente que por acaso faz a integração. É assim que o C4 desenha quem está de fora;
• num diagrama sem scope, todo vizinho colapsa para a raiz dele, porque uma visão de raízes não deve receber uma caixa de nível 3.

neighbors: 2 repete o processo sobre o resultado. Valores acima de 2 costumam trazer o modelo inteiro.

relations: quais setas desenhar

Valor	Efeito
ausente, ou auto	toda seta cujas duas pontas estão no desenho
none	nenhuma
[id, id, ...]	só aquelas
{ exclude: [id, ...] }	todas menos aquelas

Os identificadores são derivados (<origem>~<tipo>~<destino>), então uma lista explícita quebra em silêncio se você trocar o tipo de uma seta. O cfour check avisa quando um identificador citado não existe. Para descobrir os identificadores: cfour relation list --json.

groupBy: uma banda por valor, sem escrever nenhuma

groupBy: meta.dominio

Cria automaticamente um grupo para cada valor distinto encontrado. Os valores aceitos são:

groupBy	Agrupa por
meta.<chave>	o valor daquele metadado
level	o nível C4
shape	a forma
project	o projeto

Quem não tem valor para aquela dimensão fica solto, fora de qualquer banda.

Não existe groupBy: tag:<prefixo>. Um grupo é uma partição: cada caixa cai em exatamente uma, porque o retângulo é o contorno dos membros dele. Etiquetas acumulam — uma caixa pode ter três —, então agrupar por etiqueta não tem como cumprir a promessa. Escrever isso é um erro com mensagem explícita. Etiqueta serve para filtrar, que é onde a relação de muitos para muitos se resolve.

Para grupos escritos à mão, com nome e aninhamento, veja Grupos dentro de um diagrama.

subject: quem está em foco

subject: reservas
# ou
subject: [reservas, api]

Desenha aquelas caixas com destaque. O foco é propriedade da visão: a mesma caixa pode ser protagonista num diagrama e coadjuvante em outro, e por isso o campo mora no diagrama e não no elemento.

subject não cai de volta para scope: num diagrama com escopo, o escopo é a moldura e não está no desenho.

Os campos restantes

Campo	O que faz
title	o título exibido. Sem ele, vale o identificador
level	o nível em que o seletor de níveis do leitor abre este desenho. Sem ele, é derivado do que o desenho mostra
order	a posição na barra lateral. Padrão: 500
tags, meta	etiquetas e metadados do próprio diagrama, para filtrar a lista de diagramas
notes	uma lista de notas confinadas a este desenho — veja Notas

A pasta onde o arquivo está define a trilha dele na barra lateral. Um primeiro segmento chamado diagrams é descartado, porque ele diz “isto é um diagrama”, que a árvore já mostra.

Descobrir o que um diagrama de fato mostra

cfour diagram show containers --resolved

Ele lista as caixas, quem as trouxe, as setas, e as bandas. É a forma de responder “por que essa caixa está aqui” sem abrir o navegador.

Próximo passo

Grupos dentro de um diagrama.