Primeiro diagrama

Ao fim desta página você terá um modelo válido e um diagrama desenhado na sua máquina. Leva menos de dez minutos, não exige conta nenhuma e não envia nada para lugar nenhum.

Pré-requisito: a ferramenta instalada — veja Instalação.

1. Criar a estrutura inicial

   Dentro do repositório onde a arquitetura vai morar:

   cfour init

   Ele escreve cinco arquivos e diz o que fazer em seguida:

   criado cfour.yaml
   criado arquitetura/modelagem.yaml
   criado arquitetura/model/ola/project.yaml
   criado arquitetura/model/ola/elements.yaml
   criado arquitetura/model/ola/contexto.yaml

   Esse é um modelo mínimo que já desenha alguma coisa: uma pessoa, um sistema, uma seta e um diagrama. O nome da modelagem é arquitetura por padrão; use cfour init --id <id> --nome "<nome>" para escolher outro.

2. Ver o que ele escreveu

   O arquivo arquitetura/model/ola/elements.yaml tem duas caixas e uma seta:

   arquitetura/model/ola/elements.yaml

   elements:
     - id: visitante
       name: Visitante
       shape: actor
   
     - id: site
       name: Site
       shape: system
       description: O que o visitante abre.
   
   relations:
     - from: visitante
       to: site
       kind: sync
       label: Acessa

   Repare no que não está escrito: ninguém disse que site é um sistema. Ele é raiz — não tem parent —, e no C4 uma raiz é um sistema. O nível vem da árvore de contenção, nunca de um campo.

   E o diagrama, em contexto.yaml:

   arquitetura/model/ola/contexto.yaml

   kind: diagram
   id: contexto
   title: arquitetura — Contexto
   level: context
   include:
     - level: context

   include recebe um critério, e não uma lista de identificadores. level: context casa com toda caixa que é raiz — então acrescentar um segundo sistema no arquivo ao lado o traz para este desenho sem ninguém editar aqui.

3. Validar

   cfour check

   arquitetura (arquitetura)
     2 elementos · 1 relações · 1 diagramas · 0 fluxos
     0 erro(s), 0 aviso(s)

   Esse é o comando que você vai rodar o tempo todo, e é o que você coloca no seu CI. Ele sai com código 1 quando há erro.

4. Ver na tela

   cfour serve

   cfour serve · http://127.0.0.1:5199
     1 modelagem(ns) · arrastar salva em .layout/ da modelagem aberta
     Ctrl+C para parar

   Abra o endereço. Você verá o diagrama de contexto: o Visitante e o Site, com a seta entre eles.

   O servidor escuta apenas em 127.0.0.1, ou seja, só a sua máquina o alcança.

5. Acrescentar uma caixa e descer um nível

   Abra elements.yaml e acrescente um container dentro do site — basta dar a ele um parent:

   arquitetura/model/ola/elements.yaml

   elements:
     - id: visitante
       name: Visitante
       shape: actor
   
     - id: site
       name: Site
       shape: system
       description: O que o visitante abre.
   
     - id: site-web
       name: Aplicação Web
       shape: browser
       parent: site
       technology: React

   Agora site-web está um nível abaixo de site, ou seja, é um container.

6. Escrever o diagrama que mostra esse nível

   Crie arquitetura/model/ola/containers.yaml:

   arquitetura/model/ola/containers.yaml

   kind: diagram
   id: containers
   title: Site — Containers
   level: container
   scope: site
   relations: auto

   scope: site faz duas coisas: abre a caixa site por dentro e, como não há include, mostra os filhos diretos dela. É assim que se desce um nível.

   Valide e recarregue o navegador:

   cfour check && cfour serve

Se você criar filhos e não criar o diagrama

O leitor nunca inventa uma visão: uma caixa só é navegável por dentro através de um diagrama que alguém escreveu para ela. Por isso o cfour check avisa quando uma caixa tem filhos e nenhum diagrama com scope apontando para ela — aquele conteúdo existe no modelo e ninguém consegue vê-lo.

Para onde ir agora

• Para construir um modelo de verdade, passo a passo, comece em A anatomia de uma modelagem e siga a seção Modelando na ordem.
• Para publicar e compartilhar por link, vá para Como a publicação funciona.
• Para escrever pelo terminal em vez de editar YAML à mão, veja Escrever no modelo.