| name | cloud-solution-diagram |
| description | Mapeia uma arquitetura lógica aprovada para AWS, Azure, GCP, OCI ou on-premises e gera diagrama de solução. Use após uma proposta arquitetural. |
| compatibility | Requer Python 3.8+. PNG requer Graphviz e o pacote diagrams; sem eles, produz Mermaid sem instalar dependências automaticamente. |
| metadata | {"version":"0.3.0"} |
Diagrama de solução cloud
Converta uma arquitetura lógica aprovada em uma solução para uma plataforma específica,
preservando a intenção da arquitetura e tornando explícitas as decisões de mapeamento.
Regras de portabilidade
- Use o mecanismo de perguntas, arquivos e terminal disponível no host. Não mencione
nomes de ferramentas exclusivas de Claude, ChatGPT ou Codex.
- Localize o diretório raiz deste plugin pelo ancestral que contém
.claude-plugin e
.codex-plugin, guarde-o em ICEPANEL_PLUGIN_ROOT e use caminhos absolutos.
- Grave fontes e diagramas no workspace do usuário. Use diretório temporário obtido
pela biblioteca
tempfile; não presuma /tmp nem escreva no plugin instalado.
- Não instale pacotes, não execute
sudo e não altere o sistema. Se dependências
estiverem ausentes, ofereça instruções e produza Mermaid.
Execute o diagnóstico antes de escolher o renderizador:
python3 "$ICEPANEL_PLUGIN_ROOT/scripts/preflight.py" --json --cloud-diagram
Entrada
Prefira approved-architecture.json, produzido pela skill icepanel-proposal e
descrito em approved-architecture. Se ele não
existir, aceite um inventário equivalente fornecido pelo usuário. Consulte o IcePanel
somente quando o usuário indicar landscape e autorizar a leitura.
Não dependa da conversa anterior: materialize componentes, conexões, restrições,
decisões e dúvidas no arquivo de entrada.
Fluxo
1. Escolha a plataforma
Se ainda não estiver definida, solicite uma escolha entre AWS, Azure, GCP, OCI ou
on-premises/Kubernetes. Pergunte a preferência de compute somente se ela alterar a
solução: serverless, containers/Kubernetes ou VMs/aplicações gerenciadas.
2. Proponha o mapeamento
Leia cloud-mapping e apresente:
| Componente lógico | Serviço escolhido | Alternativa | Razão e trade-off |
|---|
Mapeie todos os elementos. Acrescente ingress, identidade, segredos, observabilidade,
DNS/CDN ou rede apenas quando necessários para uma implantação coerente, mantendo-os
visualmente secundários. Não transforme um diagrama de arquitetura em inventário de
todos os serviços possíveis.
Obtenha aprovação da tabela antes de renderizar.
3. Renderize
Quando Graphviz e diagrams estiverem disponíveis:
- gere um script Python autocontido;
- use
direction="LR", show=False e clusters por sistema ou zona de rede;
- rotule conexões pelo fluxo, não pelo protocolo apenas;
- renderize em um diretório criado por
tempfile.TemporaryDirectory;
- copie o PNG e o
.py para a pasta de entrega depois da renderização;
- confirme que os dois arquivos existem e têm tamanho maior que zero.
Quando qualquer dependência estiver ausente, gere solution-diagram.mmd com
flowchart LR, preservando os mesmos nós, fronteiras e conexões. Explique em uma frase
qual dependência impediu o PNG e forneça comandos de instalação como orientação, sem
executá-los.
4. Entregue e itere
Entregue pelo mecanismo de arquivos disponível no host e informe caminhos absolutos.
Inclua:
- diagrama PNG ou Mermaid;
- fonte usada para gerar o diagrama;
- tabela final de mapeamento e trade-offs;
- premissas e decisões ainda abertas.
Cada mudança de serviço ou fronteira deve atualizar tanto o diagrama quanto a tabela.
5. Retorno opcional ao IcePanel
Não escreva automaticamente os serviços escolhidos no IcePanel. Se o usuário pedir,
prepare um novo proposal-plan.json e encaminhe o fluxo para icepanel-proposal, que
aplicará confirmação, snapshot e ledger. A aprovação do diagrama cloud não equivale a
autorização para modificar o landscape.
Condições de parada
- Arquitetura ainda não aprovada: produza apenas opções e trade-offs.
- Plataforma indefinida: solicite a escolha antes do mapeamento detalhado.
- Dependências ausentes: use Mermaid.
- Componente sem equivalente direto: apresente duas opções e peça decisão; não esconda
a lacuna em um serviço genérico.
