Como o cfourdev funciona

O cfourdev tem quatro peças. Vale conhecer as quatro antes de escrever a primeira linha, porque cada página desta documentação assume que você sabe qual delas está fazendo o quê.

As quatro peças

Os arquivos YAML. São a fonte da verdade. Ficam num diretório do seu repositório Git e descrevem caixas, setas, diagramas, fluxos e notas. Você os edita com o editor que quiser.

O cfour. Uma ferramenta de linha de comando, instalada pelo npm. Ela valida o modelo, responde perguntas sobre ele, escreve nele por comando, abre um leitor na sua máquina e publica o resultado.

A plataforma. Um serviço hospedado que guarda o que foi publicado, controla quem pode ler e escrever, e responde a agentes de IA através de um servidor MCP.

O leitor. A página no navegador que desenha os diagramas — a mesma tanto para o que está na sua máquina quanto para o que foi publicado.

O ciclo

   você escreve
        │
        ▼
   YAML no Git  ──────────────┐
        │                     │
        │  cfour check        │  revisão no pull request,
        │  valida             │  como qualquer outro código
        ▼                     │
   cfour serve  ◄─────────────┘
   desenha na sua máquina
        │
        │  cfour push
        ▼
   plataforma
        │
        ├──►  leitor no navegador   (pessoas)
        └──►  servidor MCP          (agentes de IA)

Nada nesse ciclo é obrigatório além do primeiro passo. Você pode usar só os arquivos e o cfour serve, sem nunca criar uma conta.

O que cada peça decide

os arquivos	o que existe: caixas, setas, o que cada diagrama mostra, os casos de uso
o cfour	se o modelo está válido, e quando ele vai para a plataforma
a plataforma	quem pode ler, quem pode publicar, e por quanto tempo cada publicação vive
o leitor	como o desenho aparece — e guarda, em arquivos do seu repositório, a arrumação manual das caixas

Três coisas que costumam surpreender

Um diagrama não lista os seus membros. Ele guarda um critério — “os filhos desta caixa”, “tudo com a etiqueta nucleo” — e a resposta é calculada a cada leitura. É por isso que um container novo entra sozinho no diagrama de containers do sistema dele.

Uma seta é declarada uma vez só. Se você escreve que o Repositório de Reservas lê do Banco, o diagrama de containers mostra a API lendo do Banco, porque o repositório está dentro da API. Você não escreve a mesma integração em dois níveis.

A posição das caixas não é o modelo. Arrastar uma caixa no leitor grava a posição num arquivo separado, dentro de .layout/. Apagar esses arquivos não perde informação nenhuma de arquitetura — só a arrumação.

O que fica em cada lugar

seu-repositorio/
├── cfour.yaml                     ← o registro: quais modelagens existem aqui
├── arquitetura/                   ← uma modelagem
│   ├── modelagem.yaml             ← identidade dela
│   └── model/
│       ├── workspace.yaml         ← aparência (opcional)
│       └── reservas/              ← um projeto
│           ├── project.yaml
│           ├── elements.yaml      ← caixas e setas
│           ├── contexto.yaml      ← um diagrama
│           └── .layout/           ← arrumação, escrita pelo leitor
└── src/                           ← o seu código

Os nomes arquitetura, reservas e elements.yaml são escolha sua. O que é fixo está explicado em A anatomia de uma modelagem.