Explorador de Arquitetura

O que Explorador de Arquitetura faz?

Produz um arquivo HTML autossuficiente por exploração: runtime, topologia, prosa, tipografia e estilo incorporados, sem chamadas de rede em tempo de execução. Hospede-o em qualquer lugar, abra-o offline, insira-o em uma página com <iframe> ou anexe-o a um e-mail.

O modelo

Uma topologia, muitas projeções. O sistema é modelado uma vez, em profundidade total. Todo o resto é um seletor sobre esse grafo único — nunca um segundo diagrama.

TOPOLOGIA   nós + arestas + metadados        ← a única coisa que você modela
──────────────────────────────────────
PERSONA    política de resolução — vocabulário, profundidade de colapso, quais fatos são exibidos
LENTE      sobreposição de interesse — quais arestas existem, qual fato cada nó anuncia
ERA        passado / presente / planejado — presença e estilo de status
BEATS      narrativa — câmera, foco, prosa, em sequência

Duas regras que o runtime impõe e você não deve violar:

1. A cor pertence à lente. O tipo de nó é indicado pela forma — canto dobrado para uma fonte, espinha para um armazenamento, figura para uma etapa humana, chanfrado para um gateway. Nunca reintroduza um esquema de cor por tipo; isso transforma o diagrama em um arco-íris e torna a troca de lentes sem sentido.
2. Um diagrama sem uma visita guiada não está completo. O linter falha na construção com zero beats. Esta é a regra que mantém estes diagramas autoexplicativos, em vez de apenas bonitos.

Fluxo de trabalho — siga em ordem

1. Entrevista. Não invente o sistema.

O maior erro é gerar uma arquitetura que parece plausível, mas que o usuário nunca descreveu. Pergunte antes de escrever qualquer coisa. Use a ferramenta de perguntas estruturadas do seu agente, se ele tiver uma.

Cubra:

• As camadas. Quais são os 5 a 8 estágios ou grupos de nível superior? Eles se tornam as caixas de nível 1.
• Componentes por camada. Apenas o que vale a pena mostrar. "Postgres" é uma caixa; suas tabelas não.
• O ciclo de vida. Percorra uma requisição ou job representativo do início ao fim. Isso produz as arestas.
• Quem vai ler. Executivo / arquiteto / engenheiro é o conjunto usual, mas pergunte — pode ser "cliente / nossa equipe", ou "estudante / profissional".
• Quais interesses importam. Fluxo de dados mais 2 a 4 de: custo, latência, confiança e governança, modos de falha, propriedade, segurança. Cada lente precisa de suas próprias arestas ou fatos.
• Se há um histórico. v0 → hoje → planejado é o eixo de maior valor para trabalhos com clientes e roteiros. Pule-o se o sistema não tiver um passado significativo.
• O argumento. O que o leitor deve acreditar após ler? Isso se torna os beats. Se o usuário não tem um argumento, o explorador não tem espinha dorsal — insista por um.

2. Escolha o eixo principal

Profundidade raramente é o interessante. Pergunte para que serve o diagrama:

Propósito	Eixo principal
Ensinar como funciona	Tempo — beats percorrendo uma requisição
Pitch para cliente / stakeholder	Era — o que existe, o que é proposto
Revisão de design, risco	Lente — modos de falha, limites de confiança
Onboarding, referência	Profundidade — camadas, depois componentes

3. Escreva a especificação

Leia references/spec-format.md por completo antes de escrever uma. É a referência completa de nós / arestas / beats com todos os campos opcionais.

Copie assets/runtime/specs/llm-eval.js como exemplo prático — ele exercita todos os recursos e é um bom modelo a imitar. Escreva a nova especificação em specs/<nome>.js e, em seguida, aponte src/spec.js para ela (uma linha — o ponto de entrada e o linter a leem por meio dela).

4. Construa

Copie assets/runtime para um diretório de trabalho primeiro e construa lá. Não execute npm install dentro da pasta de skill instalada — geralmente é um local de instalação compartilhado ou com link simbólico.

cp -R <skill-dir>/assets/runtime ./explainer
cd explainer
npm install            # precisa de rede; ~20s
npm run build          # faz lint da spec primeiro, depois gera dist/index.html

A saída do lint informa a contagem de projeções. Se falhar, corrija a spec — nunca enfraqueça o linter. Cada regra que ele impõe existe porque um diagrama real foi enviado sem ela e ficou pior. Veja references/spec-format.md para entender o significado de cada regra.

5. Verifique visualmente — obrigatório, ambos os formatos

Esta é a etapa mais pulada e a mais impactante. A matemática do layout não é trivial e as falhas são silenciosas: um rótulo cortado, uma aresta passando por cinco caixas, uma câmera que enquadra espaço vazio. Não declare como concluído sem olhar.

node scripts/shots.mjs        # matriz desktop → shots/

Em seguida, faça uma captura de tela no tamanho de um telefone (390×844) você mesmo e abra e inspecione as imagens. Verifique:

• Cada combinação de persona × era renderiza sem sobreposição ou corte.
• Cada lente realmente muda a imagem — se duas lentes parecem idênticas, seus conjuntos de arestas estão errados.
• Enquadramento dos beats. Percorra os beats; cada um deve enquadrar seu foco com contexto visível, não espaço vazio e não o sistema inteiro.
• Rótulos. Nada cortado, nada sobrepondo uma caixa.
• Telefone. Refluído para uma coluna, legível a 100%, controles não transbordando.
• Console. Zero erros, inclusive dentro de um iframe com sandbox.

Se algo parecer errado, leia references/troubleshooting.md antes de alterar o código de layout.

6. Entregue

Dê ao usuário o arquivo dist/index.html construído. Diga a ele que o arquivo é autossuficiente e pode ser hospedado, incorporado ou aberto offline.

Apenas Claude Code / Claude apps. Envie o arquivo com SendUserFile. Se for algo que o usuário revisitará — a maioria dos exploradores são —, também o persista com create_artifact.

Inegociáveis

• Cada nó tem um why — uma frase sobre por que a caixa existe, não o que ela é.
• Qualquer coisa que um executivo possa ver tem detail em nível executivo, no vocabulário executivo.
• Pelo menos 6 beats, cada um com prosa real. Beats superficiais produzem uma apresentação de slides, não um argumento.
• ≤34 nós folha. Acima disso, divida em vários exploradores em vez de amontoar.
• Um tema por construção. Os leitores têm um alternador claro/escuro, nada mais.

Adaptação

• Direção visual diferente — src/themes.js contém cinco (house, swiss, editorial, draft, shadcn). Altere THEME_ID em src/App.jsx. Se você adicionar uma tipografia, deve definir metrics.charFactor corretamente, ou cada rótulo será cortado; veja references/troubleshooting.md.
• Mais personas / lentes / eras — dados puros da especificação, sem alterações de código.
• Geração a partir do código-fonte — um script que percorre um repositório e emite a árvore DIAGRAM é uma extensão razoável, mas o why, o detail e os beats ainda precisam vir de um humano.

Escopo

Isso constrói figuras explicativas, não painéis ao vivo, ferramentas de desenho livre e nem inventários de infraestrutura. Se o usuário quiser um diagrama editável que continuará arrastando, quer drawio. Se quiser um único número em uma página, quer um gráfico.