cfour

Arquitetura C4 como código: você escreve, o cfour valida, mostra no navegador e publica.

npm install -g cfour-cli

O pacote se chama cfour-cli; o comando é cfour.

Do zero ao primeiro diagrama

mkdir minha-arquitetura && cd minha-arquitetura
cfour init                # cria a menor workspace que desenha alguma coisa
cfour serve               # abre no navegador

cfour init escreve o cfour.yaml da workspace e, dentro dela, um usuário, um sistema, uma seta e um diagrama. É o piso — nada menor desenha nada.

Construir a arquitetura pelo terminal

O modelo é um conjunto de arquivos YAML, e eles continuam sendo a fonte da verdade: legíveis, versionados, revisados em pull request. Você pode editá-los à mão, e pode deixar o cfour escrever por você — tudo o que o formato aceita tem comando.

cfour model add vendas --name "Vendas"
cfour element add "Loja Online" --model vendas --shape system
cfour element add "API da Loja" --parent "Loja Online" --shape api --technology ".NET 8"
cfour relation add "Loja Web" "API da Loja" --kind sync --label Chama
cfour diagram add containers --of "Loja Online" --relations auto

O id de cada caixa é gerado — dez caracteres sorteados, que não derivam do nome nem da pasta. Por isso renomear uma caixa, movê-la de model ou renomear a workspace não quebram quem a referencia. E por isso todo comando aceita o nome onde aceita um id: ninguém decora um id. Nome repetido é recusa, e não escolha — o id desempata, e cfour element list mostra o de cada caixa.

Alterar e remover têm comando também, e não só criar:

cfour element set "API da Loja" --technology ".NET 9" --tag pci --tag-rm legado
cfour element set PedidoService --parent "API da Loja"   # reclassifica o nível C4
cfour relation set "Loja Web" "API da Loja" --label "Chama a API"
cfour diagram set containers --include Estoque --neighbors 1
cfour element rm "Carrinho Legado"

Quatro coisas que o CLI garante e um editor não:

• o diff é pequeno. Ele não reescreve o arquivo: encontra o ponto e emenda. Comentários, alinhamento e fim de linha ficam como estavam — e tirar uma etiqueta de três mexe numa linha, não nas três;
• nada é escrito se o resultado não carregar. A validação roda depois da gravação, e qualquer erro novo desfaz tudo;
• remover avisa antes. cfour element rm "API da Loja" recusa e lista quem aponta para ela, com o arquivo de cada um;
• --dry-run mostra o patch e não grava. Vale em todo comando que escreve.

cfour element adopt "API da Loja" k7m2p9x4a2 --dry-run

Adotar o id que outra workspace usa para a mesma caixa conserta todas as referências — parent, setas, seletores de diagrama, participantes e passos de fluxo, alvos de nota, e o arranjo — em todos os arquivos.

As três formas de dizer o que muda

A mesma convenção vale em todo comando set, então quem a aprendeu numa entidade já sabe usar nas outras:

| forma | o que faz | |---|---| | --<campo> <valor> | define ou substitui um campo de valor único | | --tag <t> / --tag-rm <t> | acrescenta ou tira uma etiqueta, sem tocar nas outras | | --meta <k=v> / --meta-rm <k> | define ou tira um metadado | | --clear <campo> | apaga um campo (--technology "" grava vazio, que é outra coisa) |

Nunca é preciso ler o valor atual para mudar uma parte dele — e por isso duas pessoas mexendo em etiquetas diferentes da mesma caixa não se sobrescrevem.

Consultar

cfour element list --level container
cfour find PostgreSQL
cfour refs "API da Loja"       # onde esta caixa é usada
cfour check                    # valida tudo

Modelar conversando: o plugin do Claude Code

O YAML é a consequência; a conversa é o produto. O plugin cfour conduz o trabalho — descobre o propósito antes de propor estrutura, entrevista, escreve o YAML, revisa, e guarda a memória do trabalho no seu repositório.

/plugin marketplace add evandrobreis/cfourdev-claude
/plugin install cfour@cfourdev

O repositório é https://github.com/evandrobreis/cfourdev-claude. Ele usa este CLI para validar o que escreve, então instale os dois.

Publicar

Crie uma conta em cfourdev.com.br, crie um repositório e gere uma chave na página dele.

cfour login --key c4_...
cfour push

Qualquer pessoa da organização gera a própria chave e publica a branch em que estiver, como preview. Publicar na branch principal exige ser admin — a mesma regra que a equipe já tem no git.

Uma chave alcança uma lista de repositórios, escolhida quando ela é criada, e o alvo de cada push é o repo: do cfour.yaml daquela workspace. É isso que faz uma árvore com várias workspaces irmãs — uma pasta por sistema — publicar com uma credencial só. Mantendo repositórios diferentes, guarde uma chave para cada: cfour login nomeia o perfil pelo destino e o vincula àquele repositório, cfour keys mostra o conjunto, e cfour push diz para onde vai antes de enviar qualquer coisa.

Em CI, exporte CFOUR_KEY em vez de rodar cfour login: o login grava a chave em disco, o que é a coisa errada num runner compartilhado.

Como descobrir o que existe

A ajuda é a fonte, e não este arquivo: ela sai da mesma declaração que valida os argumentos, então não tem como divergir do que o comando faz.

| comando | o que mostra | |---|---| | cfour help | a árvore inteira, com uma linha por comando | | cfour <comando> --help | um comando: cada flag, com a descrição e exemplos | | cfour <recurso> <sub> --help | idem para um subcomando: cfour element set --help | | cfour help formato | as regras do YAML — anatomia, níveis, referências —, sem rede | | cfour help --output json | a árvore toda num objeto, para um programa ler | | cfour completion bash | o script de autocompletar do seu shell |

cfour element set --help
cfour completion bash > /etc/bash_completion.d/cfour

A documentação do formato inteira, para agentes, está em https://docs.cfourdev.com.br/llms.txt.

Quando não há ninguém no terminal

O cfour funciona nos dois modos, e a diferença é só de comodidade:

• num terminal, quando falta um campo que tem valor padrão, ele oferece preencher — a lista de formas disponíveis, as caixas que podem ser o pai;
• fora de um terminal — num script, em CI, chamado por um programa — ele nunca pergunta. O campo que falta vira uma recusa que diz qual flag usar, em vez de um processo pendurado esperando resposta que não vem;
• --no-input desliga a pergunta mesmo num terminal.

Todo campo tem flag, então tudo o que se faz interativamente se faz por argumento. Para consumo por programa, --json existe em tudo, inclusive no que escreve:

cfour element add "API da Loja" --parent "Loja Online" --json
cfour check --json

O erro também é um objeto, com um code estável — element_not_found, duplicate_id, ambiguous_ref — para ramificar sem casar texto. E o código de saída é 0 em sucesso, 1 em erro e 2 em uso incorreto; aviso nunca reprova.

Comandos

O fluxo de trabalho, em verbos planos:

| comando | o que faz | |---|---| | cfour init | cria a menor workspace que desenha alguma coisa | | cfour check | valida esta workspace e diz o que está errado | | cfour serve | o viewer local; arrastar uma caixa salva em layouts/ | | cfour push | publica esta workspace, quando ela é status: active | | cfour pull | baixa o bundle das workspaces publicadas que esta usa | | cfour status | o que está publicado, e com qual chave | | cfour login / cfour logout | guarda e esquece uma chave de publicação | | cfour keys | as chaves guardadas nesta máquina, e qual vale aqui | | cfour use | qual chave este repositório usa | | cfour version / cfour help | a versão instalada, e a ajuda | | cfour completion | o script de autocompletar do shell |

A autoria, em recurso e verbo:

| recurso | subcomandos | o que é | |---|---|---| | cfour element | add list show set rm adopt | as caixas | | cfour relation | add list show set mv rm | as setas entre as caixas | | cfour note | add list set rm | os recados: numa caixa, ou soltos num diagrama | | cfour diagram | add list show set mv rm | as visões: o que cada desenho mostra | | cfour group | add list set rm | as bandas que agrupam caixas dentro de um diagrama | | cfour flow | add list show set mv rm | os casos de uso, contados como sequência | | cfour step | add set mv rm | os passos de um fluxo, e a ordem deles | | cfour path | add list set rm | os desvios de um fluxo, com desfecho próprio | | cfour model | add list set rm | as pastas sob models/: onde a arquitetura mora |

A consulta e a configuração:

| recurso | subcomandos | o que é | |---|---|---| | cfour find | — | procura por id, nome, tecnologia, etiqueta ou metadado | | cfour refs | — | onde uma caixa é usada | | cfour config | show set rm title | formas, cores, tipos de seta, de nota e de desfecho | | cfour workspace | show set | quem é esta workspace: id, nome, descrição e status | | cfour uses | add list rm | quais outras workspaces esta lê junto |

Uma workspace é o diretório que contém o cfour.yaml: ela tem identidade e vocabulário próprios, e é ela que se publica. Um repositório comporta várias, lado a lado — uma pasta por sistema. Dentro de cada uma, os models — as pastas sob models/ — são onde os elementos moram, e as views — os arquivos sob views/ — são as representações.

Workspaces irmãs não se enxergam. Para desenhar junto o que é de outra, declare uses: no cfour.yaml de quem lê:

cfour uses add ../plataforma       # uma pasta desta árvore
cfour uses add acme/comuns         # uma workspace publicada — depois, `cfour pull`

A união acontece na leitura: cada workspace publica só o que é dela, e quem lê monta o conjunto e funde. Duas caixas são a mesma quando têm o mesmo id — para unir o que dois times modelaram em separado, um deles usa cfour element adopt.

Configuração

Nenhum .env é carregado automaticamente, e isso é escolha: a precedência de CFOUR_KEY sobre o arquivo de credenciais é explícita.

| variável | o que faz | |---|---| | CFOUR_KEY | a chave; vence o arquivo de credenciais | | CFOUR_ENDPOINT | a API de outra instalação (padrão https://api.cfourdev.com.br) | | CFOUR_SITE | o site que o CLI cita nas mensagens (padrão https://app.cfourdev.com.br) | | CFOUR_CONFIG_HOME | onde gravar as credenciais (padrão $XDG_CONFIG_HOME) |

A chave fica em $XDG_CONFIG_HOME/cfour/credentials, com permissão 0600 num diretório 0700.

Licença

Proprietária — uso vinculado ao serviço cfourdev. Veja o arquivo LICENSE no pacote.