📐 Geração de Diagramas UML, Topologias e Modelagem Visual a partir de Código

Esta skill orienta a inteligência artificial a atuar como Especialista em Engenharia Reversa e Geração Automatizada de Diagramas UML e Estruturais, traduzindo código-fonte e esquemas arquiteturais em diagramas de classes, sequências, componentes, pacotes e fluxos de estado.

🎨 1. Ecossistema de Modelagem como Código (Diagrams as Code)

A modelagem baseada em texto declarativo permite versionamento no Git, integração contínua e renderização automática em pipelines de documentação:

flowchart LR
    subgraph Code["Código-Fonte & Esquemas"]
        SRC["Classes, Interfaces, Enums & Structs"]
        DOCS["Docstrings & Javadoc / Doxygen"]
    end

    subgraph Generators["Mecanismos de Extração & Parse"]
        DOXYGEN["Doxygen + Graphviz (dot)"]
        UMLGRAPH["UMLGraph (Doclet Java)"]
        PYREVERSE["Pyreverse (Python AST)"]
    end

    subgraph Formats["Formatos Declarativos"]
        PLANTUML["PlantUML (.puml)"]
        MERMAID["Mermaid.js (.mermaid)"]
        GRAPHVIZ["Graphviz (.dot)"]
    end

    subgraph EnterpriseTools["Ferramentas CASE / IDEs"]
        VP["Visual Paradigm / StarUML / ObjectAid"]
    end

    SRC --> Generators
    Generators --> Formats
    SRC --> EnterpriseTools
    EnterpriseTools --> Formats

🛠️ 2. Ferramentas Especialistas de Geração de Diagramas

1. PlantUML

Conceito: Componente open-source baseado em texto para modelagem UML. Ele não lê o código diretamente sozinho, mas pode ser perfeitamente combinado com ferramentas livres (como o pyreverse para Python ou doclets Java) para extrair as classes e gerar os diagramas de forma totalmente automatizada. Suporta diagramas de Classes, Sequência, Componentes, Atividades, Estado, Casos de Uso e C4 Model.
Exemplo de Engenharia Reversa para Diagrama de Classes e Injeção de Dependência:

@startuml
skinparam style strictuml
skinparam classAttributeIconSize 0

interface PaymentGateway <<interface>> {
    +processPayment(amount: BigDecimal): PaymentResult
}

class StripeGateway implements PaymentGateway {
    -apiKey: String
    +processPayment(amount: BigDecimal): PaymentResult
}

class PayPalGateway implements PaymentGateway {
    -clientId: String
    +processPayment(amount: BigDecimal): PaymentResult
}

class OrderService {
    -gateway: PaymentGateway
    -repository: OrderRepository
    +OrderService(gateway: PaymentGateway, repo: OrderRepository)
    +checkout(order: Order): CheckoutResult
}

class Order {
    -id: UUID
    -totalAmount: BigDecimal
    -status: OrderStatus
    +calculateTotal(): BigDecimal
}

OrderService --> PaymentGateway : uses
OrderService --> Order : manages
@enduml

2. Doxygen + Graphviz (dot)

Conceito: Uma das ferramentas mais tradicionais do mercado para documentação técnica e engenharia reversa em C, C++, C#, Java e Python. Gera diagramas de herança, colaboração e dependência de funções utilizando o motor open-source Graphviz para renderizar os gráficos automaticamente a partir do código-fonte.
Configuração essencial no Doxyfile:

PROJECT_NAME           = "CoreArchitecture"
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
HAVE_DOT               = YES
CLASS_GRAPH            = YES
COLLABORATION_GRAPH    = YES
GROUP_GRAPHS           = YES
UML_LOOK               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
DOT_IMAGE_FORMAT       = svg
GENERATE_LATEX         = NO
GENERATE_HTML          = YES

3. UMLGraph

Conceito: Doclet para o compilador javadoc que analisa o código-fonte Java e anotações @opt, @hidden, @depend para gerar especificações Graphviz e renderizar diagramas de classe com precisão cirúrgica sem ferramentas externas.

4. Mermaid.js

Conceito: Sintaxe declarativa de diagramação integrada nativamente ao GitHub, GitLab, Notion e IDEs modernas.
Exemplo de Diagrama de Sequência de Checkout:

sequenceDiagram
    autonumber
    actor User as Cliente Web
    participant GW as API Gateway
    participant Order as OrderService
    participant Pay as PaymentService
    participant DB as PostgreSQL

    User->>GW: POST /orders/checkout
    GW->>Order: createOrder(items)
    Order->>DB: INSERT INTO orders
    DB-->>Order: order_id: 1042
    Order->>Pay: authorize(order_id, amount)
    alt Sucesso no Pagamento
        Pay-->>Order: 200 OK (TransactionID)
        Order->>DB: UPDATE orders SET status='PAID'
        Order-->>GW: OrderCreated (Success)
        GW-->>User: 201 Created
    else Falha no Pagamento
        Pay-->>Order: 402 Payment Required
        Order->>DB: UPDATE orders SET status='FAILED'
        Order-->>GW: PaymentError
        GW-->>User: 400 Bad Request
    end

5. StarUML & Visual Paradigm & ObjectAid

StarUML: Modelador UML 2.x com suporte a engenharia reversa para Java, C++, C# e geração de modelos em formato XMI e JSON.
Visual Paradigm: Suíte corporativa de engenharia de software com suporte a modelagem C4, SysML, BPMN, ERD e sincronização bidirecional de código (Round-trip Engineering).
ObjectAid UML Explorer: Plugin para o Eclipse IDE que desenha diagramas de classes e sequências em tempo real via drag-and-drop de arquivos .java.

6. Markmap (Interactive Markdown Mindmaps)

Conceito: Componente open-source de visualização que renderiza árvores hierárquicas de Markdown como mapas mentais interativos vetoriais (SVG/D3.js). Excelente para documentar a topologia e arquitetura de pastas, pacotes e fluxos de sistemas de forma dinâmica e navegável.
Uso CLI:

npx markmap-cli architecture.md -o architecture-mindmap.html --open

📊 3. Tipos de Diagramas e Casos de Uso Recomendados

Diagrama UML	Foco do Mapeamento	Notação Recomendada
Diagrama de Classes	Estrutura de tipos, herança, interfaces, atributos e métodos	PlantUML / Mermaid `classDiagram`
Diagrama de Sequência	Ordem temporal de troca de mensagens entre objetos e serviços	Mermaid `sequenceDiagram` / PlantUML
Diagrama de Componentes	Organização de bibliotecas, APIs e subsistemas de execução	PlantUML / C4 Model Component
Diagrama de Estado (FSM)	Ciclo de vida e transições de entidades (ex: Pedido, Pagamento)	PlantUML `stateDiagram-v2`
Call Graph / Inclusão	Árvore de chamadas de funções e dependências de cabeçalho	Doxygen + Graphviz DOT

🎯 4. Boas Práticas na Geração de Diagramas

Abstração Apropriada: Em diagramas de classes de alto nível, omita getters/setters e atributos utilitários privados para focar no domínio e nas interações essenciais.
Uso de Cores e Estilos Consistentes: Padronize interfaces com cores distintas de classes concretas e use estereótipos claros (<<entity>>, <<value object>>, <<aggregate root>>).
Documentação Viva no Repositório: Mantenha os fontes .puml e .mermaid no mesmo repositório do código para permitir revisão em Pull Requests.

uml-diagram-generation

SKILL.mdskills/mapping/uml-diagram-generation/SKILL.md