sandeco Arquitetura 3D
Cria visualizações 3D de arquitetura de software usando Three.js. Gera sempre HTML standalone (arquivo único, self-contained) com cena 3D interativa, controles de câmera (mouse, touch, teclado), sidebar de parâmetros e botão de exportar a viewport como PNG.
A skill cobre cinco modos visuais consagrados em visualização de software, cada um com referência dedicada em references/:
| Modo | Quando usar | Referência |
|---|---|---|
| Code City | Visão geral de tamanho/complexidade de cada arquivo, padrão "cidade de código" | references/CODE_CITY.md |
| Dependency Graph 3D | Grafo de dependências com força repulsiva, nós em 3D | references/DEPENDENCY_GRAPH_3D.md |
| Layer Stack | Camadas arquiteturais (UI / Domain / Infra) empilhadas com setas de fluxo | references/LAYER_STACK.md |
| Call Graph 3D | Árvore de chamadas explorável em profundidade | references/CALL_GRAPH_3D.md |
| Architecture Tour | Câmera animada percorrendo a cena com overlay narrativo | references/ARCH_TOUR.md |
Padrões compartilhados de Three.js, lighting, controles e performance vivem em references/THREE_PATTERNS.md. Cenários de erro e tratamento em references/ERRORS.md.
Fluxo de Trabalho
1. Receber os dados
Os dados podem vir de:
- JSON inline: usuário fornece
modules.json(lista de módulos) e/oudeps.json(grafo de dependências). - Caminho de arquivo: usuário aponta para JSONs em
_reversa_docs/assets/data/(gerados pelo agente/reversa-documentation). - Solicitado ao usuário: se a skill é invocada sem dados, perguntar caminho ou pedir colagem inline.
Schema esperado de modules.json:
[
{
"name": "src/auth/login.ts",
"folder": "src/auth",
"loc": 142,
"complexity": 8,
"type": "code"
}
]
Schema esperado de deps.json (orientado):
{
"nodes": [{ "id": "src/auth/login.ts" }, { "id": "src/auth/jwt.ts" }],
"edges": [{ "from": "src/auth/login.ts", "to": "src/auth/jwt.ts", "weight": 1 }]
}
2. Escolher o modo
Se o usuário especificou o modo, usar aquele. Se não, sugerir 2 ou 3 opções com base nos dados:
| Tipo de dado | Modos recomendados |
|---|---|
modules.json com LOC + complexidade |
Code City (padrão), Layer Stack se houver pastas/camadas claras |
deps.json com muitas arestas |
Dependency Graph 3D, Code City colorindo hot path |
| Trace de execução ou call graph | Call Graph 3D |
| Pedido explícito de apresentação | Architecture Tour combinando duas das anteriores |
Quando o número de nós ultrapassa 500, aplicar agrupamento por pasta automaticamente e avisar o usuário (registrar a decisão no rodapé do HTML gerado).
3. Gerar o código
Consultar references/THREE_PATTERNS.md para setup base (renderer, cena, câmera, iluminação, OrbitControls). Consultar a referência específica do modo escolhido para o algoritmo de layout e materiais.
Regras fundamentais:
- HTML standalone: arquivo único
.htmlcom tudo embutido (CSS, JS, dados inline em<script id="data">). Quando rodada pelo Time Reversa Docs, os dados vêm dewindow.RV_DATA.modulesewindow.RV_DATA.deps(carregados peloassets/js/data.jsque o Publisher gera) e o<script id="data">fica vazio ou ausente. Páginas finais nunca fazemfetch()para arquivos locais (quebra viafile://). - Three.js local: usar
<script src="assets/vendor/three.min.js"></script>apontando para o arquivo baixado pelo Publisher (versão pinada emagents/reversa-docs-publisher/references/vendor-pins.yaml, hojethree@0.147.0IIFE). Em modo invocação isolada fora do time Docs, aceite CDN como fallback (https://unpkg.com/three@0.147.0/build/three.min.js), mas nunca misture versões. - OrbitControls local: usar
<script src="assets/vendor/OrbitControls.js"></script>(também IIFE, compatível comthree@0.147). Não useexamples/jsm/...enquanto a skill não migrar para importmap + ESM. - Renderer: WebGLRenderer com antialiasing, pixelRatio do device.
- Iluminação: HemisphereLight + DirectionalLight com sombras suaves. Para Code City, AmbientLight extra para preencher.
- Câmera: PerspectiveCamera, posição inicial olhando o centro da cena de cima e levemente angulada. Distância derivada do tamanho da cena.
- Performance: usar
InstancedMeshquando há mais de 200 elementos do mesmo tipo. Limite máximo de 5.000 prédios no Code City sem agrupamento. - Responsividade: handler de resize redimensiona renderer e ajusta aspect ratio da câmera.
- Sidebar: lado direito, controles sliders/checkboxes/botões em layout vertical. Cada controle tem ID estável para
localStorage. - Exportar PNG: botão captura o canvas via
renderer.domElement.toBlob().
4. Estrutura do HTML gerado
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Arquitetura 3D | <!-- PROJECT_NAME --></title>
<script src="assets/vendor/three.min.js"></script>
<script src="assets/vendor/OrbitControls.js"></script>
<script src="assets/js/data.js"></script>
<style>
body { margin: 0; overflow: hidden; font-family: system-ui, sans-serif; }
#scene { position: fixed; inset: 0; }
#sidebar { position: fixed; top: 0; right: 0; width: 280px; height: 100vh; padding: 16px; background: rgba(15,15,20,0.85); color: #eaeaea; overflow-y: auto; }
#loader { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; font-size: 18px; background: #0a0a10; color: #eaeaea; }
/* Estilo Reversa: variantes derivam de data-style do <body> via CSS externo do agente */
</style>
</head>
<body data-style="exploratory">
<div id="loader">Carregando cena 3D...</div>
<canvas id="scene"></canvas>
<aside id="sidebar">
<h3>Controles</h3>
<!-- SIDEBAR_CONTROLS -->
<button id="reset">Reset</button>
<button id="export-png">Exportar PNG</button>
</aside>
<script id="data" type="application/json"><!-- DATA_JSON --></script>
<script>
// OrbitControls IIFE expõe THREE.OrbitControls globalmente.
// 1. Carregar dados de window.RV_DATA quando rodando no time Docs,
// ou do <script id="data"> em modo standalone.
// 2. Configurar cena, câmera, renderer, iluminação
// 3. Construir geometria conforme o modo (Code City, Dep Graph, etc)
// 4. Conectar sidebar aos parâmetros da cena
// 5. Loop de renderização e tratamento de eventos
</script>
</body>
</html>
5. Salvar e entregar
O output é sempre HTML standalone. Salvar no caminho indicado pelo agente orquestrador (geralmente _reversa_docs/arquitetura.html).
Quando invocada fora do contexto do /reversa-documentation, perguntar caminho de destino ou usar <modo>-<timestamp>.html no diretório atual.
Diretrizes de qualidade
- Câmera intuitiva: posição inicial mostra a cena inteira; OrbitControls com damping para movimento suave.
- Materiais coesos: paleta limitada (5 a 8 cores no máximo); cores carregadas indicam atributo (ex: vermelho para hot path, azul para módulos leves).
- Labels legíveis: usar CSS2DRenderer ou sprites; labels só aparecem em hover ou zoom acima de um threshold para não poluir.
- Loader visível: cena começa com overlay "Carregando cena 3D..." que some quando o
requestAnimationFrameda primeira frame termina. - Fallback gracioso: se Three.js não carregar (sem internet), mostrar mensagem "Esta visualização requer carregar a biblioteca Three.js. Conecte-se à internet e recarregue."
- Acessibilidade básica: navegação por teclado nos botões da sidebar; foco visível.
- Idioma: comentários e textos visíveis em pt-br. Sem travessão.
Diretrizes de código
- Modularidade: separar criação da cena, construção da geometria e gerenciamento de interação em funções com nomes claros.
- Sem dependências além de Three.js e OrbitControls (locais em
assets/vendor/): não importar GSAP, dat.GUI, ou qualquer outra lib sem necessidade clara. - Constantes nomeadas no topo: cores, sizes, thresholds em um bloco de configuração visível.
- Dispose: ao trocar de modo ou regenerar, chamar
geometry.dispose()ematerial.dispose()para evitar vazamento. - Performance check: antes de renderizar, contar nós; se > 5.000 sem instanced mesh, abortar e mostrar aviso.
Tratamento de erros
Consultar references/ERRORS.md para cenários comuns (CDN inacessível, JSON malformado, projeto vazio, WebGL não suportado, etc).