cloud-solution-diagram

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:

1. diagrama PNG ou Mermaid;
2. fonte usada para gerar o diagrama;
3. tabela final de mapeamento e trade-offs;
4. 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.