claude-plugins/dev-tools/skills/diagrama/SKILL.md

---
name: diagrama
category: dev-tools
description: "Gera diagramas de arquitectura, fluxo, ER e sequência em três formatos: draw.io (.drawio), Excalidraw e Mermaid. Usar quando 'diagrama', 'arquitectura', 'draw.io', 'fluxo', 'ER', 'sequência', 'infra', 'componentes'."
version: "1.0.0"
created: 2026-04-04
tools: [mcp__claude_ai_Excalidraw__export_to_excalidraw, mcp__mcp-mermaid__generate, Write, Bash]
---

# Skill: /diagrama

Gera diagramas técnicos em três formatos consoante o caso de uso. Suporta arquitectura de sistemas, fluxogramas, diagramas ER, sequência, infra-estrutura e redes.

---

## Quando usar cada formato

| Formato | Quando usar | Output |
|---------|------------|--------|
| **draw.io** | Diagramas formais para documentação, propostas, clientes | `.drawio` (editável) |
| **Excalidraw** | Esboços rápidos, brainstorming visual, estilo whiteboard | `.excalidraw` / MCP |
| **Mermaid** | Diagramas como código, versionáveis em Git, embeds Markdown | `.svg` / `.png` |

---

## Processo de execução

### 1. Identificar pedido

Quando o utilizador pede um diagrama, detectar:
- **Tipo:** arquitectura | fluxo | ER | sequência | rede | organograma | classe
- **Formato pretendido:** draw.io (default para doc. formal) | excalidraw | mermaid
- **Contexto:** sistemas envolvidos, entidades, actores

Se não especificado, perguntar apenas: "draw.io (formal) ou Excalidraw (esboço)?"

### 2. Gerar conteúdo

---

## Geração draw.io (.drawio)

O formato draw.io é mxGraph XML. Gerar o XML e guardar como `.drawio`.

### Estrutura base

```xml
<mxfile host="Claude Code" modified="YYYY-MM-DDTHH:MM:SS" agent="Claude" version="21.0">
  <diagram name="Diagrama" id="diagram-1">
    <mxGraphModel dx="1422" dy="762" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <!-- elementos aqui -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>
```

### Templates de elementos mxGraph

**Rectângulo (componente/serviço):**
```xml
<mxCell id="2" value="Nome" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="160" y="160" width="120" height="60" as="geometry"/>
</mxCell>
```

**Seta/ligação:**
```xml
<mxCell id="10" edge="1" source="2" target="3" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>
```

**Cilindro (base de dados):**
```xml
<mxCell id="5" value="PostgreSQL" style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;fillColor=#f8cecc;strokeColor=#b85450;" vertex="1" parent="1">
  <mxGeometry x="320" y="160" width="80" height="80" as="geometry"/>
</mxCell>
```

**Cloud (serviço externo):**
```xml
<mxCell id="6" value="Cloudflare" style="shape=mxgraph.cisco.sites.generic_building;sketch=0;html=1;pointerEvents=1;dashed=0;fillColor=#036897;strokeColor=#ffffff;strokeWidth=2;verticalLabelPosition=bottom;verticalAlign=top;align=center;outlineConnect=0;" vertex="1" parent="1">
  <mxGeometry x="480" y="160" width="60" height="60" as="geometry"/>
</mxCell>
```

**Actor (pessoa/utilizador):**
```xml
<mxCell id="7" value="Utilizador" style="shape=mxgraph.flowchart.start_2;fillColor=#00BEF2;strokeColor=#006EAF;fontColor=#ffffff;fontStyle=1;fontSize=12;" vertex="1" parent="1">
  <mxGeometry x="40" y="170" width="60" height="40" as="geometry"/>
</mxCell>
```

**Swimlane (grupo/camada):**
```xml
<mxCell id="8" value="Camada Frontend" style="swimlane;startSize=20;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="400" height="200" as="geometry"/>
</mxCell>
```

### Paleta de cores Descomplicar

| Componente | fillColor | strokeColor |
|-----------|-----------|-------------|
| Serviço/App | `#dae8fc` | `#6c8ebf` |
| Base de dados | `#f8cecc` | `#b85450` |
| Fila/Queue | `#d5e8d4` | `#82b366` |
| Externo/Cloud | `#fff2cc` | `#d6b656` |
| Infra/Servidor | `#e1d5e7` | `#9673a6` |
| Claude/IA | `#f0f4ff` | `#4a6cf7` |

### Guardar ficheiro

Guardar em `/media/ealmeida/Dados/Hub/tmp/diagramas/` com nome descritivo:
```
YYYY-MM-DD-nome-diagrama.drawio
```

Abrir com:
```bash
drawio "/media/ealmeida/Dados/Hub/tmp/diagramas/NOME.drawio" &
```
(ou abrir manualmente com draw.io desktop / draw.io no browser)

---

## Geração Excalidraw

Usar o MCP `mcp__claude_ai_Excalidraw__export_to_excalidraw` para diagramas no estilo whiteboard.

### Fluxo

1. Chamar `mcp__claude_ai_Excalidraw__create_view` para iniciar sessão
2. Chamar `mcp__claude_ai_Excalidraw__export_to_excalidraw` com o conteúdo estruturado
3. Informar o utilizador do link/path gerado

### Casos de uso preferidos

- Brainstorming e exploração rápida
- Diagramas de fluxo com estilo manual
- Esboços para reuniões
- Arquitecturas de alto nível para comunicação interna

---

## Geração Mermaid

Usar o MCP `mcp__mcp-mermaid__generate` para diagramas como código.

### Tipos suportados

**Fluxograma:**
```
flowchart TD
    A[Início] --> B{Condição}
    B -->|Sim| C[Acção]
    B -->|Não| D[Fim]
```

**Sequência:**
```
sequenceDiagram
    participant U as Utilizador
    participant A as Claude Code
    participant N as n8n
    U->>A: Pedido
    A->>N: Trigger workflow
    N-->>A: Resultado
    A-->>U: Resposta
```

**ER:**
```
erDiagram
    CLIENTE ||--o{ PROJECTO : tem
    PROJECTO ||--o{ TAREFA : contém
    TAREFA {
        int id
        string nome
        string estado
    }
```

**Arquitectura de componentes (C4):**
```
C4Context
    title Stack Descomplicar
    Person(eal, "Emanuel", "Utilizador principal")
    System(cc, "Claude Code", "Interface interactiva")
    System(clip, "Paperclip", "Agentes autónomos")
    System(n8n, "n8n", "Automação determinística")
    Rel(eal, cc, "usa directamente")
    Rel(cc, clip, "delega tarefas complexas")
    Rel(cc, n8n, "activa workflows")
```

### Guardar output

Guardar o código Mermaid em `/media/ealmeida/Dados/Hub/tmp/diagramas/NOME.mmd` e renderizar para SVG/PNG via MCP.

---

## Templates prontos por contexto

### Arquitectura StackDescomplicar

Gerar diagrama com as três camadas do stack:
- **Camada 1:** Claude Code (trabalho interactivo)
- **Camada 2:** n8n (automação determinística)
- **Camada 3:** Paperclip (raciocínio autónomo)

### Proposta comercial

Diagrama da solução para o cliente com:
- Infra-estrutura actual (antes)
- Solução proposta (depois)
- Componentes e integrações

### Pipeline de dados

Diagrama de fluxo com:
- Fonte → Processamento → Destino
- Triggers, transformações, outputs

### Diagrama ER Desk CRM

Entidades principais: Lead → Customer → Estimate → Invoice → Payment

---

## Boas práticas

- **Máx. 10-15 elementos** por diagrama (mais → dividir em sub-diagramas)
- **Labels curtos:** 2-4 palavras por elemento
- **Setas com label** quando o fluxo não é óbvio
- **Cor consistente** por tipo de componente (seguir paleta Descomplicar)
- **Nome descritivo** no ficheiro (não "diagrama1.drawio")
- **Guardar em Hub/tmp/diagramas/** para fácil acesso

---

## Instalar draw.io MCP (opcional, para funcionalidades avançadas)

O vídeo #210 do Stack_Pesquisa_Videos.md demonstra um MCP draw.io com geração automática a partir de análise de código. Para instalar:

```bash
# Verificar se há MCP draw.io disponível no gateway
# Ver: Hub/04-Stack/claude-code-context-hygiene.md → secção MCPs
```

Alternativa: usar draw.io via browser em https://app.diagrams.net (gratuito, sem instalação) e importar o `.drawio` gerado.

---

## Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

```jsonl
{"date":"","issue":"","fix":"","source":"user|auto"}
```

*Adicionar nova linha após cada erro corrigido.*