spillwavesolutions/design-doc-mermaid

Mermaid Architect - Habilidade de Diagramação e Documentação Hierárquica

Sistema de diagramação e documentação Mermaid com guias especializados e capacidade de converter código em diagrama.

Índice

• Árvore de Decisão
• GitHub wiki, WikiTicket e Confluence
• Guias e Recursos Disponíveis
• Padrões de Uso
• Fluxo de Trabalho Resiliente
• Símbolos Semânticos Unicode
• Utilitários Python
• Exemplos da Árvore de Decisão
• Estilização de Alto Contraste
• Organização de Arquivos
• Resumo do Fluxo de Trabalho
• Quando Usar o Quê
• Melhores Práticas
• Trilha de Aprendizado

Árvore de Decisão

Como esta skill funciona:

1. Usuário faz uma solicitação → Skill analisa a intenção
2. Skill determina o tipo de diagrama/documento → Carrega o(s) guia(s) apropriado(s)
3. IA lê o guia especializado → Gera diagrama/documento usando modelos
4. Resultado entregue → Com validação e opções de exportação

Análise de Intenção do Usuário:

flowchart TD
    Start([Solicitação do Usuário]) --> Analyze{Analisar Intenção}

    Analyze -->|"workflow, processo, lógica de negócio"| Activity[Carregar Guia de Diagrama de Atividade<br/>references/guides/diagrams/activity-diagrams.md]
    Analyze -->|"infraestrutura, implantação, nuvem"| Deploy[Carregar Guia de Diagrama de Implantação<br/>references/guides/diagrams/deployment-diagrams.md]
    Analyze -->|"arquitetura de sistema, componentes"| Arch[Carregar Guia de Arquitetura<br/>references/guides/diagrams/architecture-diagrams.md]
    Analyze -->|"fluxo de API, interações"| Sequence[Carregar Guia de Diagrama de Sequência<br/>references/guides/diagrams/sequence-diagrams.md]
    Analyze -->|"classe, ER, estado, wiki, walkthrough"| WikiGuide[Carregar Guia WikiTicket GitHub<br/>references/guides/wiki-ticket-and-github.md]
    Analyze -->|"código para diagrama"| CodeToDiag[Carregar Guia Código-para-Diagrama<br/>references/guides/code-to-diagram/ + examples/]
    Analyze -->|"documento de design, documentação completa"| DesignDoc[Carregar Modelo de Documento de Design<br/>assets/*-design-template.md]
    Analyze -->|"símbolos unicode, ícones"| Unicode[Carregar Guia de Símbolos Unicode<br/>references/guides/unicode-symbols/guide.md]
    Analyze -->|"extrair, validar, converter"| Scripts[Usar Scripts Python<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py]

    Activity --> Generate[Gerar Diagrama]
    Deploy --> Generate
    Arch --> Generate
    Sequence --> Generate
    WikiGuide --> Generate
    CodeToDiag --> Generate
    DesignDoc --> Generate
    Unicode --> Generate
    Scripts --> Execute[Executar Script]

    Generate --> Validate{Validar?}
    Validate -->|Sim| RunValidation[Executar validação mmdc]
    Validate -->|Não| Output
    RunValidation --> Output[Exibir Resultado]
    Execute --> Output

    classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black
    classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue

    class Analyze,Validate decision
    class Activity,Deploy,Arch,Sequence,WikiGuide,CodeToDiag,DesignDoc,Unicode,Scripts guide
    class Generate,Execute,RunValidation,Output action

Guias e Recursos Disponíveis

Guias por Tipo de Diagrama (references/guides/diagrams/)

Guia	Caminho Completo	Carregar Quando o Usuário Quiser	Exemplos
Diagramas de Atividade	references/guides/diagrams/activity-diagrams.md	Fluxos de trabalho, processos, lógica de negócio, fluxos de usuário, árvores de decisão	"Mostrar fluxo de checkout", "Documentar pipeline ETL", "Criar fluxo de aprovação"
Diagramas de Implantação	references/guides/diagrams/deployment-diagrams.md	Infraestrutura, arquitetura em nuvem, K8s, serverless, topologia de rede	"Mostrar arquitetura AWS", "Documentar implantação GCP", "Criar diagrama K8s"
Diagramas de Arquitetura	references/guides/diagrams/architecture-diagrams.md	Arquitetura de sistema, design de componentes, estrutura de alto nível	"Mostrar componentes do sistema", "Documentar microsserviços", "Visão geral da arquitetura"
Diagramas de Sequência	references/guides/diagrams/sequence-diagrams.md	Interações de API, comunicação entre serviços, fluxos de requisição/resposta	"Mostrar sequência de chamadas de API", "Documentar fluxo de autenticação", "Interações entre serviços"
WikiTicket / GitHub / Confluence	references/guides/wiki-ticket-and-github.md	Documentos de design, walkthroughs, requisitos, publicação em wiki, imagens para Confluence	"documento de arquitetura", "walkthrough de código", "wiki", "Confluence"

Padrão para WikiTicket e wiki do GitHub é esta skill, incluindo classDiagram, erDiagram e stateDiagram-v2. Não envie esses para PlantUML. Se o GitHub falhar ao renderizar C4 / architecture-beta / block-beta, use flowchart TD como fallback.

Guia e Exemplos de Código para Diagrama

Recurso	Caminho Completo	O Que Oferece
Guia Mestre	references/guides/code-to-diagram/README.md	Fluxo completo para analisar qualquer base de código e extrair diagramas
Spring Boot	examples/spring-boot/README.md	Arquitetura Controller→Service→Repository, configuração de implantação, sequência a partir de métodos, atividade a partir de lógica de negócio
FastAPI	examples/fastapi/README.md	Padrões assíncronos Python, modelos Pydantic, injeção de dependência, implantação em nuvem
React	examples/react/README.md	Hierarquia de componentes, gerenciamento de estado, fluxo de dados, pipeline de build
Python ETL	examples/python-etl/README.md	Pipeline de dados, etapas de transformação, tratamento de erros, agendamento
Node/Express	examples/node-webapp/README.md	Cadeia de middlewares, manipuladores de rota, padrões assíncronos, implantação
Java Web App	examples/java-webapp/README.md	MVC tradicional, contêineres servlet, implantação WAR

Modelos de Documento de Design

Modelo	Caminho Completo	Usar Para	Carregar Quando
Design de Arquitetura	assets/architecture-design-template.md	Arquitetura de todo o sistema	"Criar documento de arquitetura", "Documentar design do sistema"
Design de API	assets/api-design-template.md	Especificações de API	"Documento de design de API", "Documentar API REST"
Design de Funcionalidade	assets/feature-design-template.md	Planejamento de funcionalidades	"Design de funcionalidade", "Planejar nova funcionalidade"
Design de Banco de Dados	assets/database-design-template.md	Esquema de banco de dados	"Design de banco de dados", "Documentar esquema"
Design de Sistema	assets/system-design-template.md	Sistema completo	"Documento de design do sistema", "Documentação completa do sistema"

Guia de Símbolos Unicode

Caminho Completo: references/guides/unicode-symbols/guide.md

Carregar quando o usuário mencionar: "símbolos unicode", "emoji em diagramas", "ícones semânticos", "adicionar símbolos"

Referência Rápida:

• 📦 Infraestrutura: ☁️ 🌐 🔌 📡 🗄️
• ⚙️ Computação: ⚙️ ⚡ 🔄 ♻️ 🚀 💨
• 💾 Dados: 💾 📦 📊 📈 🗃️ 🧊
• 📨 Mensageria: 📨 📬 📤 📥 🐰 📢
• 🔐 Segurança: 🔐 🔑 🛡️ 🚪 👤 🎫
• 📝 Monitoramento: 📝 📊 🚨 ⚠️ ✅ ❌

Scripts Python (scripts/)

Script	Usar Para	Carregar Quando
extract_mermaid.py	Extrair diagramas de Markdown, validar sintaxe, substituir por imagens	"extrair diagramas", "validar mermaid", "encontrar todos os diagramas"
mermaid_to_image.py	Converter .mmd para PNG/SVG, conversão em lote, temas personalizados	"converter para imagem", "renderizar diagrama", "criar PNG"
resilient_diagram.py	Fluxo completo: salvar .mmd, gerar imagem, validar, recuperar erros	"gerar diagrama", "criar diagrama com validação", "diagrama resiliente"

GitHub wiki, WikiTicket e Confluence

Carregue references/guides/wiki-ticket-and-github.md para documentos de design do WikiTicket, walkthroughs de código, requisitos, wiki do GitHub ou Confluence.

Destino	O que enviar
GitHub wiki / GFM	Bloco mermaid com cercaduras. GitHub renderiza: class, ER, state, sequence, flowchart, C4.
Confluence / Notion / Word / PDF	Renderize também PNG ou SVG (scripts/resilient_diagram.py ou mmdc) e faça upload da imagem. Não dependa do Confluence para renderizar Mermaid.

PlantUML é opcional para wireframes Salt, caso de uso, timing, ArchiMate, nwdiag e WBS. Esses sempre são enviados como PNG ou SVG.

Padrões de Uso

Padrões comuns de solicitação e seleção de guias. Veja Quando Usar o Quê para o mapeamento completo.

Padrão	Exemplo de Solicitação	Guias a Carregar
Diagrama Único	"Criar diagrama de atividade para fluxo de login"	Guia do tipo de diagrama + símbolos Unicode
Código para Diagrama	"Gerar implantação a partir do application.yml"	Exemplo do framework + Guia de implantação
Documento de Design	"Criar documento de design de API"	Modelo de assets/ + Guias de diagrama relevantes
Extrair/Validar	"Extrair diagramas do design.md"	Usar scripts/extract_mermaid.py
Conversão em Lote	"Converter todos os .mmd para PNG"	Usar scripts/mermaid_to_image.py

Fluxo de Trabalho Resiliente

CRÍTICO: Esta é a abordagem recomendada para TODA geração de diagramas. Garante validação, recuperação de erros e organização consistente de arquivos.

Guia Completo: references/guides/resilient-workflow.md

Visão Geral do Fluxo

flowchart LR
    A[1. Identificar Tipo] --> B[2. Salvar .mmd + Imagem]
    B --> C{3. Válido?}
    C -->|Sim| D[4. Adicionar ao Markdown]
    C -->|Não| E[5. Recuperação de Erro]
    E --> F{Correção Encontrada?}
    F -->|Sim| A
    F -->|Não| G[Buscar Externamente]
    G --> A

    classDef step fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,G step
    class C,F decision

Princípio Chave

NUNCA adicione um diagrama ao markdown até que ele passe na validação. Isso evita diagramas quebrados na documentação.

Usando o Script (Recomendado)

# Gerar com recuperação completa de erros
python scripts/resilient_diagram.py \
    --code "flowchart TD; A-->B" \
    --markdown-file design_doc \
    --diagram-num 1 \
    --title "process_flow" \
    --format png \
    --json

Saída: Arquivos .mmd e .png no diretório ./diagrams/.

Convenção de Nomenclatura de Arquivos

./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
./diagrams/<markdown_file>_<num>_<type>_<title>.png

Exemplo: ./diagrams/api_design_01_sequence_auth_flow.png

Prioridade de Recuperação de Erros

Quando a validação falha, o fluxo automaticamente:

1. Verificar guia de solução de problemas - references/guides/troubleshooting.md (28 erros documentados)
2. Pesquisar com perplexity - MCP perplexity_ask para dúvidas de sintaxe
3. Pesquisar com brave - MCP brave_web_search para soluções recentes
4. Perguntar ao gemini - Skill gemini para perspectiva alternativa
5. Pesquisa geral - Ferramenta WebSearch como fallback

Passos Manuais de Fallback

Se o script não estiver disponível:

1. Identificar o tipo de diagrama pela primeira linha (flowchart, sequence, etc.)
2. Carregar guia de referência de references/guides/diagrams/
3. Salvar em ./diagrams/<markdown_file>_<num>_<type>_<title>.mmd
4. Validar: mmdc -i file.mmd -o file.png -b transparent
5. Em caso de erro: Pesquisar em references/guides/troubleshooting.md pelo erro correspondente
6. Se não encontrado: Usar ferramentas de busca na ordem de prioridade acima
7. Adicionar referência: ![Descrição](./diagrams/filename.png)

Padrão 6: Geração Resiliente de Diagramas

Usuário: "Crie um diagrama de sequência e adicione ao documento de design"

Ações da Skill:

1. Identificar intenção: geração de diagrama + integração com markdown
2. Carregar guia de fluxo de trabalho: references/guides/resilient-workflow.md
3. Identificar tipo de diagrama: sequence
4. Carregar guia de diagrama: references/guides/diagrams/sequence-diagrams.md
5. Gerar código Mermaid usando modelos
6. Executar fluxo resiliente:

   python scripts/resilient_diagram.py \
       --code "[código gerado]" \
       --markdown-file design_doc \
       --diagram-num 1 \
       --title "api_sequence" \
       --json
   

7. Se a validação falhar → Aplicar correção de solução de problemas → Tentar novamente
8. Em caso de sucesso → Adicionar ![Sequência da API](./diagrams/design_doc_01_sequence_api_sequence.png) ao markdown

Símbolos Semânticos Unicode

Sempre use símbolos Unicode para melhorar a clareza dos diagramas. Padrões comuns:

Infraestrutura e Implantação

graph TB
    Client[👤 Usuário] --> LB[🌐 Balanceador de Carga]
    LB --> App1[⚙️ Servidor de Aplicação 1]
    LB --> App2[⚙️ Servidor de Aplicação 2]
    App1 --> DB[(💾 Banco de Dados)]
    App1 --> Cache[(⚡ Redis)]

Fluxo de Atividades com Estados

flowchart TD
    Start([🚀 Iniciar]) --> Process[⚙️ Processar Dados]
    Process --> Check{✓ Válido?}
    Check -->|Sim| Save[💾 Salvar]
    Check -->|Não| Error[❌ Erro]
    Save --> Complete([✅ Concluído])

Arquitetura de Microsserviços

graph TB
    API[🌐 Gateway de API] --> Auth[🔐 Serviço de Autenticação]
    API --> Orders[📋 Serviço de Pedidos]
    Orders --> Queue[📬 Fila de Mensagens]
    Queue --> Worker[⚙️ Trabalhador em Segundo Plano]
    Worker --> Storage[📦 Armazenamento de Objetos]

Para referência completa de símbolos, carregue: references/guides/unicode-symbols/guide.md

Utilitários Python

Extrair Diagramas Mermaid

# Listar todos os diagramas
python scripts/extract_mermaid.py document.md --list-only

# Extrair para arquivos separados
python scripts/extract_mermaid.py document.md --output-dir diagrams/

# Validar todos os diagramas
python scripts/extract_mermaid.py document.md --validate

# Substituir por referências de imagem (para upload no Confluence)
python scripts/extract_mermaid.py document.md --replace-with-images \
  --image-format png --output-markdown output.md

Converter para Imagens

# Conversão única
python scripts/mermaid_to_image.py diagram.mmd output.png

# Com configurações personalizadas
python scripts/mermaid_to_image.py diagram.mmd output.svg \
  --theme dark --background white --width 1200

# Conversão em lote de diretório
python scripts/mermaid_to_image.py diagrams/ output/ --format png --recursive

# A partir de stdin
echo "graph TD; A-->B" | python scripts/mermaid_to_image.py - output.png

Exemplos da Árvore de Decisão

Exemplo 1: Documentação de Microsserviços

Usuário: "Documente nossa arquitetura de microsserviços com deployment no Kubernetes"

Ações da Skill:

1. Analisar intenção: arquitetura de microsserviços + implantação
2. Carregar: references/guides/diagrams/architecture-diagrams.md
3. Carregar: references/guides/diagrams/deployment-diagrams.md
4. Carregar: references/guides/diagrams/sequence-diagrams.md (para interações de serviço)
5. Gerar documentos de design e diagramas usando o fluxo resiliente
6. Validar cada diagrama
7. Combinar em documento de design abrangente

Exemplo 2: Conversão de Aplicação Spring Boot

Usuário: "Extraia diagramas do nosso projeto Spring Boot e documente a arquitetura"

Ações da Skill:

1. Analisar intenção: código para diagrama + Spring Boot
2. Carregar: examples/spring-boot/README.md
3. Carregar: references/guides/code-to-diagram/README.md
4. Carregar: references/guides/diagrams/sequence-diagrams.md (para endpoints REST)
5. Carregar: references/guides/diagrams/class-diagrams.md (para estrutura de domínio)
6. Analisar pom.xml, controladores, serviços, repositórios
7. Gerar e validar diagramas

Exemplo 3: Documentação de Pipeline de Dados

Usuário: "Crie um diagrama para nossa pipeline ETL Python e documento de design"

Ações da Skill:

1. Analisar intenção: pipeline de dados + documento de design
2. Carregar: examples/python-etl/README.md
3. Carregar: references/guides/diagrams/activity-diagrams.md
4. Carregar: assets/architecture-design-template.md
5. Carregar: references/guides/unicode-symbols/guide.md
6. Analisar scripts Python, arquivos de configuração de pipeline
7. Gerar documentos de design e diagramas

Estilização de Alto Contraste

Para máxima visibilidade, use paletas de alto contraste:

flowchart TD
    Start([Iniciar]) --> Process{{Processar}}
    Process --> Decision{Decisão}
    Decision -->|Sim| Success([Sucesso])
    Decision -->|Não| End([Fim])

    classDef start fill:#00FF00,stroke:#006400,stroke-width:3px,color:#000000
    classDef process fill:#1E90FF,stroke:#00008B,stroke-width:3px,color:#FFFFFF
    classDef decision fill:#FFD700,stroke:#8B4500,stroke-width:3px,color:#000000
    classDef terminal fill:#FF6347,stroke:#8B0000,stroke-width:3px,color:#FFFFFF

    class Start start
    class Process process
    class Decision decision
    class Success,End terminal

Dicas de Acessibilidade:

• Use cores com alto contraste (proporção ≥ 4.5:1)
• Evite combinações vermelho/verde para daltonismo
• Adicione texto significativo às bordas das setas
• Use símbolos junto com texto codificado por cores
• Teste com simulador de daltonismo

Organização de Arquivos

📂 project/
├── 📝 design.md
├── 📂 diagrams/
│   ├── design_01_activity_checkout_flow.mmd
│   ├── design_01_activity_checkout_flow.png
│   ├── design_02_sequence_order_api.mmd
│   └── design_02_sequence_order_api.png
├── 📂 assets/               # Modelos de documento de design
│   ├── architecture-design-template.md
│   ├── api-design-template.md
│   ├── database-design-template.md
│   └── feature-design-template.md
├── 📂 scripts/              # Scripts Python
│   ├── extract_mermaid.py
│   ├── mermaid_to_image.py
│   └── resilient_diagram.py
├── 📂 references/
│   ├── 📂 guides/
│   │   ├── 📂 diagrams/
│   │   │   ├── activity-diagrams.md
│   │   │   ├── deployment-diagrams.md
│   │   │   ├── architecture-diagrams.md
│   │   │   └── sequence-diagrams.md
│   │   ├── 📂 code-to-diagram/
│   │   │   └── README.md
│   │   ├── 📂 unicode-symbols/
│   │   │   └── guide.md
│   │   ├── resilient-workflow.md
│   │   ├── using-claude-code.md
│   │   └── troubleshooting.md
│   └── 📂 conventions/
│       └── style-guide.md
└── 📂 examples/
    ├── spring-boot/README.md
    ├── fastapi/README.md
    ├── react/README.md
    ├── python-etl/README.md
    ├── node-webapp/README.md
    └── java-webapp/README.md

Resumo do Fluxo de Trabalho

Fluxo Ideal

1. Receber solicitação → Analisar e classificar
2. Carregar guias de diagrama com base na classificação
3. Carregar guias de suporte (símbolos, código para diagrama)
4. Carregar modelo de documento de design se aplicável
5. Gerar diagramas usando o fluxo resiliente
6. Validar antes da saída
7. Entregar com documentação de suporte

Ações Chave

Ação	Como	Quando
Analisar	Analisar palavras-chave linguísticas e técnicas	Toda solicitação
Carregar	Selecionar e carregar de /references/	Antes da geração
Gerar	Escrever dentro de cercaduras mermaid	Para diagramas
Validar	Usar mmdc ou script python	Para todos os diagramas
Entregar	Incorporar imagem ou bloco mermaid	Saída final

Quando Usar o Quê

Mapeamento de Tipo de Diagrama

Tipo de Diagrama	Melhor Para	Guia a Carregar
Sequence	Fluxo de API, interações entre serviços, fluxos de autenticação	sequence-diagrams.md
Flowchart	Fluxo de trabalho, processos de negócio, árvores de decisão	activity-diagrams.md
Class	Estruturas de domínio, relacionamentos de entidade, hierarquias de classe	Diagramas de classe (embutido)
ER	Esquemas de banco de dados, modelos de dados	Diagramas ER (embutido)`
State	Máquinas de estado, fluxos de workflow, transições de status	Diagramas de estado (embutido)
C4	Arquitetura de alto nível, contexto do sistema, contêineres	architecture-diagrams.md
Deployment	Infraestrutura em nuvem, K8s, topologia de rede	deployment-diagrams.md
Architecture	Design de microsserviços, componentes do sistema	architecture-diagrams.md
Activity	Lógica de processo, pipelines ETL, workflows de usuário	activity-diagrams.md

Quando Usar PlantUML (Opt-in)

Tipo de Diagrama	Quando Usar
Salt Wireframes	Mockups de interface do usuário
Caso de Uso	Diagramas de caso de uso UML
Timing	Diagramas de tempo UML
ArchiMate	Diagramas de arquitetura corporativa
nwdiag	Diagramas de rede
WBS	Estrutura Analítica do Projeto

Sempre rode scripts em lote para esses tipos e inclua PNG/SVG.

Melhores Práticas

1. Sempre use o fluxo resiliente para geração de diagramas
2. Valide antes de exibir - nunca mostre diagramas quebrados
3. Use símbolos Unicode para clareza visual
4. Mantenha acessibilidade - alto contraste, representação textual clara
5. Organize os arquivos - use convenção de nomenclatura consistente
6. Documente as decisões - explique por que um diagrama específico foi escolhido
7. Use modelos para documentos de design para garantir consistência
8. Aproveite exemplos de código para diagramas para acelerar a análise
9. Teste de acessibilidade - use ferramentas de simulação de daltonismo
10. Documento de referência - adicione links de volta para guias e exemplos

Trilha de Aprendizado

Nível 1: Noções Básicas

• Entender tipos de diagramas Mermaid: flowchart, sequence, class, ER, state, C4
• Praticar criação de diagramas simples
• Usar símbolos Unicode básicos

Nível 2: Intermediário

• Dominar o fluxo de trabalho resiliente
• Aprender scripts Python
• Usar modelos de documentos de design

Nível 3: Avançado

• Converter código em diagrama para múltiplos frameworks
• Criar diagramas de deploy complexos (K8s, cloud)
• Integração com GitHub wiki e Confluence

Nível 4: Especialista

• Otimizar documentação para automação completa
• Criar guias personalizados
• Contribuir com novos exemplos e modelos