Um insight em cada bit!

Criando Diagramas Profissionais com Mermaid

Mermaid é uma ferramenta baseada em JavaScript que permite criar diagramas e visualizações usando apenas texto simples. Em vez de arrastar e soltar elementos em uma interface gráfica, tipo Miro e Draw.io, você escreve código que é automaticamente convertido em diagramas visuais elegantes.

Por que usar Mermaid?
  1. Versionamento: Como é baseado em texto, pode ser versionado com Git
  2. Integração: Funciona nativamente em GitHub, GitLab, Notion, Obsidian e muitas outras plataformas
  3. Rapidez: Criar e modificar diagramas é muito mais rápido que ferramentas visuais
  4. Padronização: Mantém consistência visual em todos os seus diagramas
  5. Documentação como código: Seus diagramas vivem junto com seu código
Como Começar

Existem várias formas de usar Mermaid:

  1. Direto no Markdown (GitHub, GitLab, etc.)
  2. Mermaid Live Editor: https://mermaid.live/
  3. Em aplicações: VS Code, Obsidian, Notion
  4. Em páginas web: Usando a biblioteca JavaScript
Tipos de Diagramas

Vamos explorar os principais tipos de diagramas que você pode criar com Mermaid.

1. Fluxogramas (Flowcharts)

Fluxogramas são perfeitos para representar processos, algoritmos e fluxos de decisão. Abaixo tem um código que cria um fluxograma básico de processo de análise de dados:

flowchart TD
    A[Coleta de Dados] --> B{Dados Válidos?}
    B -->|Sim| C[Limpeza de Dados]
    B -->|Não| D[Revisar Fonte]
    D --> A
    C --> E[Análise Exploratória]
    E --> F[Modelagem]
    F --> G{Modelo Satisfatório?}
    G -->|Sim| H[Deploy]
    G -->|Não| I[Ajustar Parâmetros]
    I --> F

flowchart TD
    A[Coleta de Dados] --> B{Dados Válidos?}
    B -->|Sim| C[Limpeza de Dados]
    B -->|Não| D[Revisar Fonte]
    D --> A
    C --> E[Análise Exploratória]
    E --> F[Modelagem]
    F --> G{Modelo Satisfatório?}
    G -->|Sim| H[Deploy]
    G -->|Não| I[Ajustar Parâmetros]
    I --> F

Elementos principais:

  • TD ou TB: Top Down (de cima para baixo)
  • LR: Left to Right (da esquerda para direita)
  • []: Retângulo
  • {}: Losango (decisão)
  • (): Retângulo arredondado
  • -->: Seta de conexão
2. Diagramas de Sequência

Ideais para mostrar interações entre diferentes componentes ou atores ao longo do tempo. Abaixo um código que demonstra a interação em uma API REST:

sequenceDiagram
    participant Cliente
    participant API
    participant Banco
    participant Cache
    
    Cliente->>API: GET /dados/usuario/123
    API->>Cache: Verificar cache
    alt Cache hit
        Cache-->>API: Retorna dados
        API-->>Cliente: 200 OK (dados do cache)
    else Cache miss
        API->>Banco: SELECT * FROM usuarios WHERE id=123
        Banco-->>API: Dados do usuário
        API->>Cache: Armazenar no cache
        API-->>Cliente: 200 OK (dados do banco)
    end

sequenceDiagram
    participant Cliente
    participant API
    participant Banco
    participant Cache
    
    Cliente->>API: GET /dados/usuario/123
    API->>Cache: Verificar cache
    alt Cache hit
        Cache-->>API: Retorna dados
        API-->>Cliente: 200 OK (dados do cache)
    else Cache miss
        API->>Banco: SELECT * FROM usuarios WHERE id=123
        Banco-->>API: Dados do usuário
        API->>Cache: Armazenar no cache
        API-->>Cliente: 200 OK (dados do banco)
    end

Elementos principais:

  • participant: Define os atores
  • ->>: Mensagem síncrona
  • -->>: Resposta
  • alt/else/end: Estruturas condicionais
  • loop: Para repetições
3. Diagramas de Classes

Perfeitos para documentar estruturas orientadas a objetos. Abaixo um código que representa classes de um sistema de análise de dados:

classDiagram
    class DataProcessor {
        -data: DataFrame
        -config: Dict
        +load_data(path: str)
        +clean_data()
        +transform_data()
        +save_results(path: str)
    }
    
    class Visualizer {
        -processor: DataProcessor
        +create_plot(type: str)
        +save_figure(path: str)
        +show_dashboard()
    }
    
    class Model {
        <<abstract>>
        -parameters: Dict
        +train(data: DataFrame)
        +predict(data: DataFrame)
        +evaluate()
    }
    
    class RandomForest {
        -n_trees: int
        -max_depth: int
        +feature_importance()
    }
    
    DataProcessor <|-- Visualizer : usa
    Model <|-- RandomForest : herda
    DataProcessor <|-- Model : processa dados para

classDiagram
    class DataProcessor {
        -data: DataFrame
        -config: Dict
        +load_data(path: str)
        +clean_data()
        +transform_data()
        +save_results(path: str)
    }
    
    class Visualizer {
        -processor: DataProcessor
        +create_plot(type: str)
        +save_figure(path: str)
        +show_dashboard()
    }
    
    class Model {
        <<abstract>>
        -parameters: Dict
        +train(data: DataFrame)
        +predict(data: DataFrame)
        +evaluate()
    }
    
    class RandomForest {
        -n_trees: int
        -max_depth: int
        +feature_importance()
    }
    
    DataProcessor <|-- Visualizer : usa
    Model <|-- RandomForest : herda
    DataProcessor <|-- Model : processa dados paraclassDiagram
    class DataProcessor {
        -data: DataFrame
        -config: Dict
        +load_data(path: str)
        +clean_data()
        +transform_data()
        +save_results(path: str)
    }
    
    class Visualizer {
        -processor: DataProcessor
        +create_plot(type: str)
        +save_figure(path: str)
        +show_dashboard()
    }
    
    class Model {
        <<abstract>>
        -parameters: Dict
        +train(data: DataFrame)
        +predict(data: DataFrame)
        +evaluate()
    }
    
    class RandomForest {
        -n_trees: int
        -max_depth: int
        +feature_importance()
    }
    
    DataProcessor <|-- Visualizer : usa
    Model <|-- RandomForest : herda
    DataProcessor <|-- Model : processa dados para

Elementos principais:

  • +: Método/atributo público
  • -: Método/atributo privado
  • <<abstract>>: Classe abstrata
  • <|--: Herança
  • o--: Agregação
  • *--: Composição
4. Diagramas de Gantt

Excelentes para gerenciamento de projetos e cronogramas. 

gantt
    title Projeto de Análise Preditiva
    dateFormat YYYY-MM-DD
    
    section Preparação
    Definir escopo           :done, prep1, 2024-01-01, 7d
    Coletar dados           :done, prep2, 2024-01-08, 14d
    
    section Análise
    EDA                     :active, ana1, 2024-01-22, 10d
    Feature Engineering     :ana2, after ana1, 14d
    
    section Modelagem
    Treinar modelos base    :mod1, after ana2, 7d
    Otimização hiperparâm.  :mod2, after mod1, 10d
    Validação cruzada       :mod3, after mod1, 5d
    
    section Deploy
    Preparar API            :dep1, after mod2, 7d
    Testes                  :dep2, after dep1, 5d
    Documentação           :doc1, after mod3, 10d
    Go-live                :milestone, after dep2, 0d

gantt
    title Projeto de Análise Preditiva
    dateFormat YYYY-MM-DD
    
    section Preparação
    Definir escopo           :done, prep1, 2024-01-01, 7d
    Coletar dados           :done, prep2, 2024-01-08, 14d
    
    section Análise
    EDA                     :active, ana1, 2024-01-22, 10d
    Feature Engineering     :ana2, after ana1, 14d
    
    section Modelagem
    Treinar modelos base    :mod1, after ana2, 7d
    Otimização hiperparâm.  :mod2, after mod1, 10d
    Validação cruzada       :mod3, after mod1, 5d
    
    section Deploy
    Preparar API            :dep1, after mod2, 7d
    Testes                  :dep2, after dep1, 5d
    Documentação           :doc1, after mod3, 10d
    Go-live                :milestone, after dep2, 0d
5. Diagramas de Estado

Úteis para representar diferentes estados de um sistema e suas transições.

stateDiagram-v2
    [*] --> Idle
    Idle --> Coletando : Trigger manual/agendado
    Coletando --> Validando : Dados coletados
    Coletando --> Erro : Falha na coleta
    
    Validando --> Processando : Dados válidos
    Validando --> Erro : Dados inválidos
    
    Processando --> Armazenando : Processamento OK
    Processando --> Erro : Falha no processamento
    
    Armazenando --> Concluído : Sucesso
    Armazenando --> Erro : Falha no armazenamento
    
    Erro --> Idle : Retry/Reset
    Concluído --> Idle : Novo ciclo
    
    state Processando {
        [*] --> Limpeza
        Limpeza --> Transformação
        Transformação --> Agregação
        Agregação --> [*]
    }

stateDiagram-v2
    [*] --> Idle
    Idle --> Coletando : Trigger manual/agendado
    Coletando --> Validando : Dados coletados
    Coletando --> Erro : Falha na coleta
    
    Validando --> Processando : Dados válidos
    Validando --> Erro : Dados inválidos
    
    Processando --> Armazenando : Processamento OK
    Processando --> Erro : Falha no processamento
    
    Armazenando --> Concluído : Sucesso
    Armazenando --> Erro : Falha no armazenamento
    
    Erro --> Idle : Retry/Reset
    Concluído --> Idle : Novo ciclo
    
    state Processando {
        [*] --> Limpeza
        Limpeza --> Transformação
        Transformação --> Agregação
        Agregação --> [*]
    }
6. Diagramas de Pizza

Os famosos, controversos e simples gráficos de pizza usandos para mostrar proporções.

pie title Distribuição de Tempo em Projeto de DS
    "Coleta de Dados" : 15
    "Limpeza de Dados" : 25
    "Análise Exploratória" : 20
    "Modelagem" : 25
    "Deploy e Documentação" : 15

pie title Distribuição de Tempo em Projeto de DS
    "Coleta de Dados" : 15
    "Limpeza de Dados" : 25
    "Análise Exploratória" : 20
    "Modelagem" : 25
    "Deploy e Documentação" : 15
7. Git Graph

Perfeito para visualizar fluxos de trabalho Git dentro de documentações. 

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    branch feature/nova-analise
    checkout feature/nova-analise
    commit
    commit
    checkout develop
    merge feature/nova-analise
    checkout main
    merge develop
    commit
    branch hotfix/correcao-bug
    checkout hotfix/correcao-bug
    commit
    checkout main
    merge hotfix/correcao-bug

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    branch feature/nova-analise
    checkout feature/nova-analise
    commit
    commit
    checkout develop
    merge feature/nova-analise
    checkout main
    merge develop
    commit
    branch hotfix/correcao-bug
    checkout hotfix/correcao-bug
    commit
    checkout main
    merge hotfix/correcao-bug
8. Diagramas ER (Entity Relationship)

Aquela parte que é temida por muitos e adorada por outros: fazer o a modelagem de banco de dados. Com o Mermaid isso fica muito mais fácil, você foca no que é importante (e o próprio mermaid organiza as coisas).

erDiagram
    PROJETO ||--o{ DATASET : possui
    PROJETO ||--o{ MODELO : gera
    DATASET ||--o{ PREPROCESSAMENTO : passa_por
    PREPROCESSAMENTO ||--|| FEATURE_SET : produz
    FEATURE_SET ||--o{ MODELO : alimenta
    MODELO ||--o{ PREDICAO : realiza
    PREDICAO }o--|| METRICAS : gera
    
    PROJETO {
        int id PK
        string nome
        date data_inicio
        string status
    }
    
    DATASET {
        int id PK
        int projeto_id FK
        string fonte
        int num_linhas
        int num_colunas
    }
    
    MODELO {
        int id PK
        int projeto_id FK
        string algoritmo
        json parametros
        float acuracia
    }

erDiagram
    PROJETO ||--o{ DATASET : possui
    PROJETO ||--o{ MODELO : gera
    DATASET ||--o{ PREPROCESSAMENTO : passa_por
    PREPROCESSAMENTO ||--|| FEATURE_SET : produz
    FEATURE_SET ||--o{ MODELO : alimenta
    MODELO ||--o{ PREDICAO : realiza
    PREDICAO }o--|| METRICAS : gera
    
    PROJETO {
        int id PK
        string nome
        date data_inicio
        string status
    }
    
    DATASET {
        int id PK
        int projeto_id FK
        string fonte
        int num_linhas
        int num_colunas
    }
    
    MODELO {
        int id PK
        int projeto_id FK
        string algoritmo
        json parametros
        float acuracia
    }
Dicas pra ficar tudo muito melhor:
1. Temas e Estilos

Você pode personalizar a aparência dos seus diagramas:

%%{init: {'theme':'dark'}}%%
flowchart LR
    A[Início] --> B{Decisão}
    B -->|Opção 1| C[Processo 1]
    B -->|Opção 2| D[Processo 2]
    C --> E[Fim]
    D --> E

%%{init: {'theme':'dark'}}%%
flowchart LR
    A[Início] --> B{Decisão}
    B -->|Opção 1| C[Processo 1]
    B -->|Opção 2| D[Processo 2]
    C --> E[Fim]
    D --> E
2. Subgráficos

Para diagramas mais complexos, use subgráficos:

flowchart TB
    subgraph "Camada de Entrada"
        A1[API REST]
        A2[Arquivo CSV]
        A3[Banco de Dados]
    end
    
    subgraph "Processamento"
        B1[Validação]
        B2[Transformação]
        B3[Enriquecimento]
    end
    
    subgraph "Saída"
        C1[Dashboard]
        C2[Relatório]
        C3[API]
    end
    
    A1 & A2 & A3 --> B1
    B1 --> B2 --> B3
    B3 --> C1 & C2 & C3

flowchart TB
    subgraph "Camada de Entrada"
        A1[API REST]
        A2[Arquivo CSV]
        A3[Banco de Dados]
    end
    
    subgraph "Processamento"
        B1[Validação]
        B2[Transformação]
        B3[Enriquecimento]
    end
    
    subgraph "Saída"
        C1[Dashboard]
        C2[Relatório]
        C3[API]
    end
    
    A1 & A2 & A3 --> B1
    B1 --> B2 --> B3
    B3 --> C1 & C2 & C3
3. Estilos Customizados

Código que aplica estilos CSS personalizados:

flowchart LR
    A[Início]:::startClass --> B[Processo]
    B --> C{Decisão}:::decisionClass
    C -->|Sim| D[Sucesso]:::successClass
    C -->|Não| E[Falha]:::errorClass
    
    classDef startClass fill:#e1f5e1,stroke:#4caf50,stroke-width:2px
    classDef decisionClass fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    classDef successClass fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef errorClass fill:#f8d7da,stroke:#dc3545,stroke-width:2px

flowchart LR
    A[Início]:::startClass --> B[Processo]
    B --> C{Decisão}:::decisionClass
    C -->|Sim| D[Sucesso]:::successClass
    C -->|Não| E[Falha]:::errorClass
    
    classDef startClass fill:#e1f5e1,stroke:#4caf50,stroke-width:2px
    classDef decisionClass fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    classDef successClass fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef errorClass fill:#f8d7da,stroke:#dc3545,stroke-width:2px
4. Integração com R e Python

Código R que gera um diagrama Mermaid dinamicamente:

# Instalar e carregar pacote
install.packages("DiagrammeR")
library(DiagrammeR)

# Criar dados para o diagrama
processos <- c("Importar", "Limpar", "Analisar", "Visualizar")
conexoes <- data.frame(
  de = processos[-length(processos)],
  para = processos[-1]
)

# Gerar código Mermaid
codigo_mermaid <- paste0(
  "graph LR\n",
  paste(
    conexoes$de, "-->", conexoes$para,
    collapse = "\n"
  )
)

# Renderizar diagrama
DiagrammeR::mermaid(codigo_mermaid)

Código Python que gera diagramas Mermaid:

# Instalar biblioteca
# %pip install mermaid-py

import mermaid as md
from IPython.display import Image

# Criar diagrama programaticamente
def criar_fluxograma_ml(etapas):
    """
    Cria um fluxograma Mermaid para pipeline de ML
    """
    diagrama = "graph TD\n"
    
    for i, etapa in enumerate(etapas):
        if i == 0:
            diagrama += f"    A[{etapa}]\n"
        else:
            letra_atual = chr(65 + i)  # A, B, C, ...
            letra_anterior = chr(65 + i - 1)
            diagrama += f"    {letra_anterior} --> {letra_atual}[{etapa}]\n"
    
    return diagrama

# Usar a função
pipeline_ml = [
    "Coletar Dados",
    "Preprocessar",
    "Feature Engineering", 
    "Treinar Modelo",
    "Avaliar",
    "Deploy"
]

diagrama_ml = criar_fluxograma_ml(pipeline_ml)
print(diagrama_ml)

# Renderizar (em Jupyter)
mm = md.Mermaid(diagrama_ml)
mm.to_png('pipeline_ml.png')
5. Mermaid no Google

O Mermaid também pode ser utilizado dentro do Google Docs e Google Slides, basta adicionar o plugin.

Melhores Práticas
  1. Mantenha Simples: Diagramas muito complexos são difíceis de entender
  2. Use Cores com Propósito: Destaque elementos importantes
  3. Seja Consistente: Use o mesmo estilo em toda documentação
  4. Versione seus Diagramas: Guarde o código Mermaid, não apenas as imagens
  5. Documente o Contexto: Adicione descrições ao redor dos diagramas
Recursos Adicionais

Comentários

Um comentário a “Criando Diagramas Profissionais com Mermaid”

  1. Avatar de Thiago Toledo
    Thiago Toledo

    Gostei muito?

    Responder

Deixe um comentário

O seu endereço de email não será publicado. Campos obrigatórios marcados com *