A anatomia de uma modelagem

Antes de escrever caixas e setas, vale saber onde as coisas moram. São poucas regras, e quase tudo é escolha sua.

Os três níveis de organização

Modelagem — uma realidade inteira, com propósito, vocabulário e público próprios. Um repositório pode ter uma só (o caso comum) ou várias.

Projeto — uma pasta diretamente sob model/. É o dono dos identificadores dentro dela: o mesmo api pode existir em dois projetos sem colidir.

Documento — qualquer arquivo .yaml dentro de um projeto. O conteúdo dele diz o que ele é; o nome do arquivo e a pasta são livres.

A estrutura no disco

cfour.yaml o registro — o único caminho que a ferramenta procura
Directoryarquitetura/ uma modelagem (o nome é escolha sua)
- modelagem.yaml identidade: id, nome, status
- Directorymodel/
  - workspace.yaml aparência (opcional)
  - Directoryreservas/ uma pasta aqui é um projeto
    project.yaml
    elements.yaml
    contexto.yaml
    Directory.layout/ arrumação das caixas, escrita pelo leitor
    …
Directorysrc/ o seu código
- …

Não existe índice nem lista mestra. Acrescentar uma caixa é criar ou editar um arquivo, e mais nada.

O que é fixo, e o que não é

Fixo	Livre
o nome `cfour.yaml`, e o fato de ele ficar na raiz do repositório	o nome da pasta da modelagem
o nome `modelagem.yaml`, dentro da pasta da modelagem	os nomes dos projetos
a pasta `model/` dentro da modelagem	o arranjo de pastas dentro de um projeto
o nome `workspace.yaml`, dentro de `model/`	os nomes dos arquivos `.yaml`
que uma pasta diretamente sob `model/` é um projeto	quantos documentos há em cada arquivo

Três nomes de pasta têm significado especial:

.layout/ guarda a posição das caixas. É escrita pelo leitor e nunca é lida como modelo.
shared, como nome de projeto, é onde ficam as caixas que todos os projetos usam — veja Projetos.
Qualquer pasta começando com . e a pasta node_modules são ignoradas.

Como a ferramenta encontra a sua modelagem

Todo comando do cfour sobe a árvore de diretórios a partir de onde você está até achar um cfour.yaml. Achou, tudo o mais é derivado dele: do path de cada modelagem registrada sai o model/ que será carregado.

Quando há mais de uma modelagem registrada, a escolha segue esta ordem:

--modelagem <id> na linha de comando
C4_MODELAGEM no ambiente
o campo "active" do cfour.yaml
a única que existe

Se nada decidir e houver mais de uma, o comando recusa e lista os identificadores disponíveis. Escolher em silêncio seria pior.

As duas formas de um arquivo do modelo

Um .yaml do modelo diz o que carrega de duas maneiras, e as duas podem conviver no mesmo arquivo, separadas por ---:

Singular — kind: no topo, e os campos do objeto logo abaixo:

kind: project
id: reservas
name: Reservas de Salas

Coleção — sem kind, com uma ou mais das listas elements:, relations:, diagrams:, flows: e notes::

elements:
  - id: colaborador
    name: Colaborador
    shape: actor

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

Os valores válidos de kind: na forma singular são project, element, relation, diagram, flow, note e folder. Um kind que a ferramenta não conhece faz o documento ser ignorado, com aviso.

O identificador de cada coisa

Um identificador local usa letras, números, ponto, hífen ou sublinhado, e começa com letra ou número. A barra é reservada: ela separa o projeto do identificador.

Dentro do modelo carregado, tudo tem identificador qualificado: reservas/api é a caixa api do projeto reservas. Você quase nunca escreve a forma qualificada — dentro do próprio projeto basta api — mas é ela que aparece nas mensagens de erro e nas respostas de consulta.

Próximo passo

Elementos: as caixas começa a construir um modelo de verdade, que cresce até o fim desta seção.