Elementos: as caixas

Uma caixa — um elemento — é uma pessoa, um sistema, um container, um componente ou uma classe. Tudo isso é a mesma estrutura no arquivo; o que diferencia é onde a caixa está na árvore e qual desenho ela pede.

A partir desta página vamos construir um modelo de reserva de salas de reunião, que cresce até o fim da seção Modelando.

A primeira caixa

model/reservas/elements.yaml

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

Quatro campos, e só o id é obrigatório. Sem parent, essa caixa é raiz da árvore — portanto está no nível context, portanto é um sistema.

Os campos de um elemento

Campo	Obrigatório	O que faz
id	sim	o identificador dentro do projeto. Letras, números, ., -, _
name	não	o nome exibido. Sem ele, o próprio id aparece na caixa
shape	não	o desenho. Padrão: system
parent	não	a caixa que contém esta. É o que decide o nível C4
description	não	uma frase sobre o que ela faz, exibida na caixa
technology	não	a tecnologia, exibida na caixa em letra menor
tags	não	etiquetas livres, para filtrar e agrupar
meta	não	pares chave/valor livres
level	não	força o nível. Discordar da árvore gera aviso, e a árvore vence
bind	não	declara que esta caixa é o espelho de um elemento de outra modelagem

O nível é derivado, não escolhido

Esta é a regra que mais muda a forma de escrever. O nível C4 vem da profundidade na árvore de contenção, que o campo parent constrói:

sem parent              → context     (um sistema, ou uma pessoa)
filho de uma raiz       → container
filho de um container   → component
filho de um componente  → code

Não existe um quinto nível: uma caixa mais funda que code continua sendo code. E não existe um campo “eu quero que esta seja um componente” — para descer um nível, dê um parent à caixa.

O campo `level` existe, e quase nunca deve ser usado

Ele serve para o caso raro em que você quer nomear o nível explicitamente. Se o valor discordar da árvore, o cfour check avisa e o valor derivado prevalece. Na prática: use parent, não level.

As formas disponíveis

shape escolhe o desenho e a cor. Estas são as formas que vêm de fábrica:

shape	Desenho	Uso típico
system	caixa	um sistema seu
external	caixa de borda tracejada, cinza	um sistema de terceiro ou de outra equipe
actor	silhueta de pessoa	uma pessoa, ou um papel
bot	silhueta de robô	um agente automatizado tratado como ator
container	caixa	uma parte executável genérica
api	caixa	um serviço com interface de programação
browser	janela de navegador	uma aplicação que roda no navegador
database	cilindro	um banco de dados
queue	fila	uma fila de mensagens
topic	tópico	um tópico de eventos
component	caixa menor	um componente dentro de um container
class	caixa menor	uma classe, no nível de código

Uma forma desconhecida não some do desenho: ela vira uma caixa neutra, e o cfour check avisa. Você pode criar formas próprias — veja Aparência da modelagem.

Forma e nível são coisas separadas

shape: database num container e shape: database num componente desenham o mesmo cilindro; o que muda é a cor, que vem do nível. Escolher shape: component para uma caixa que é filha de um sistema não a torna um componente — ela continua sendo um container, desenhado com a silhueta errada.

Descendo um nível

Para pôr containers dentro do sistema, basta dar a eles um parent:

model/reservas/containers.yaml

elements:
  - id: painel
    name: Painel de Reservas
    shape: browser
    parent: reservas
    technology: React
    description: Onde a pessoa procura uma sala livre e confirma a reserva.

  - id: api
    name: API de Reservas
    shape: api
    parent: reservas
    technology: Node.js
    description: Onde moram as regras — conflito de horario, limite e confirmacao.

Nada mais precisa mudar. As duas caixas agora são containers de reservas, e qualquer diagrama que abra reservas por dentro passa a mostrá-las.

O estado atual do modelo

Este é o arquivo completo depois de acrescentar a pessoa e o sistema de fora:

model/reservas/elements.yaml

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

Repare em agenda-corporativa: ela é external porque é um sistema de outra gente. Você não vai detalhar o que existe dentro dela, e o desenho tracejado diz isso a quem lê.

Próximo passo

As caixas existem, mas ainda não conversam. Relações: as setas.