Diagramação
Visão Geral
Crie diagramas técnicos claros e de fácil manutenção usando sintaxe Mermaid. Esta skill abrange diagramas de arquitetura, diagramas de sequência, diagramas entidade-relacionamento, fluxogramas e diagramas de estado para documentar sistemas de software.
Instruções
1. Escolha o Tipo de Diagrama Correto
| Tipo de Diagrama | Use Quando |
|---|---|
| Arquitetura/C4 | Mostrando estrutura e componentes do sistema |
| Sequência | Mostrando interações ao longo do tempo |
| DER | Mostrando modelos de dados e relacionamentos |
| Fluxograma | Mostrando lógica de decisão e processos |
| Estado | Mostrando transições de estado |
2. Princípios Gerais do Mermaid
- Mantenha os diagramas focados em um conceito
- Use convenções de nomenclatura consistentes
- Adicione rótulos descritivos aos relacionamentos
- Limite a complexidade (divida diagramas grandes)
- Use comentários para documentação
Melhores Práticas
- Simplicidade: Um diagrama, um conceito
- Consistência: Mesma nomenclatura em diagramas relacionados
- Legibilidade: Fluxo da esquerda para a direita ou de cima para baixo
- Rótulos: Sempre rotule relacionamentos e transições
- Contexto: Inclua um título e uma breve descrição
Exemplos
Diagramas de Arquitetura (Modelo C4)
Diagrama de Contexto (Nível 1)
C4Context
title Diagrama de Contexto do Sistema para Plataforma de E-Commerce
Person(cliente, "Cliente", "Um usuário que compra produtos")
Person(admin, "Admin", "Gerencia produtos e pedidos")
System(ecommerce, "Plataforma de E-Commerce", "Permite que clientes naveguem e comprem produtos")
System_Ext(pagamento, "Gateway de Pagamento", "Processa pagamentos")
System_Ext(entrega, "Provedor de Entrega", "Gerencia o envio de pedidos")
System_Ext(email, "Serviço de Email", "Envia notificações")
Rel(cliente, ecommerce, "Navega, compra")
Rel(admin, ecommerce, "Gerencia")
Rel(ecommerce, pagamento, "Processa pagamentos")
Rel(ecommerce, entrega, "Cria remessas")
Rel(ecommerce, email, "Envia emails")
Diagrama de Container (Nível 2)
C4Container
title Diagrama de Container para Plataforma de E-Commerce
Person(cliente, "Cliente")
Container_Boundary(ecommerce, "Plataforma de E-Commerce") {
Container(web, "Aplicação Web", "React", "Interface do cliente")
Container(api, "Gateway de API", "Node.js", "API REST")
Container(carrinho, "Serviço de Carrinho", "Node.js", "Gerenciamento do carrinho de compras")
Container(catalogo, "Serviço de Catálogo", "Python", "Catálogo de produtos")
Container(pedido, "Serviço de Pedido", "Java", "Processamento de pedidos")
ContainerDb(db, "Banco de Dados", "PostgreSQL", "Armazena todos os dados")
ContainerQueue(fila, "Fila de Mensagens", "RabbitMQ", "Mensageria assíncrona")
}
Rel(cliente, web, "Usa", "HTTPS")
Rel(web, api, "Chama", "JSON/HTTPS")
Rel(api, carrinho, "Roteia para")
Rel(api, catalogo, "Roteia para")
Rel(api, pedido, "Roteia para")
Rel(carrinho, db, "Lê/escreve")
Rel(catalogo, db, "Lê")
Rel(pedido, db, "Lê/escreve")
Rel(pedido, fila, "Publica eventos")
Diagrama de Componente (Nível 3)
flowchart TB
subgraph "Serviço de Pedido"
controller[Controlador de Pedido]
service[Serviço de Pedido]
repo[Repositório de Pedido]
validator[Validador de Pedido]
publisher[Publicador de Eventos]
end
subgraph "Externo"
db[(PostgreSQL)]
queue[RabbitMQ]
end
controller --> service
service --> validator
service --> repo
service --> publisher
repo --> db
publisher --> queue
Diagramas de Sequência
Fluxo Básico de Requisição
sequenceDiagram
autonumber
participant C as Cliente
participant G as Gateway de API
participant A as Serviço de Autenticação
participant S as Serviço
participant D as Banco de Dados
C->>G: POST /api/recurso
G->>A: Validar token
A-->>G: Token válido
G->>S: Encaminhar requisição
S->>D: Consultar dados
D-->>S: Retornar resultados
S-->>G: Resposta (200 OK)
G-->>C: Resposta com dados
Fluxo de Tratamento de Erros
sequenceDiagram
participant C as Cliente
participant S as Serviço
participant D as Banco de Dados
C->>S: POST /api/usuarios
S->>S: Validar entrada
alt Validação falha
S-->>C: 400 Requisição Inválida
else Validação passa
S->>D: INSERT usuário
alt Erro de banco de dados
D-->>S: Violação de restrição
S-->>C: 409 Conflito
else Sucesso
D-->>S: Usuário criado
S-->>C: 201 Criado
end
end
Processamento Assíncrono
sequenceDiagram
participant C as Cliente
participant API as API
participant Q as Fila
participant T as Trabalhador
participant N as Notificação
C->>API: Enviar job
API->>Q: Enfileirar job
API-->>C: 202 Aceito (ID do job)
Note over Q,T: Processamento assíncrono
Q->>T: Desenfileirar job
T->>T: Processar job
T->>N: Enviar notificação
N-->>C: Notificação de conclusão do job
Diagramas Entidade-Relacionamento
DER Básico
erDiagram
USUARIO ||--o{ PEDIDO : faz
USUARIO {
uuid id PK
string email UK
string nome
timestamp criado_em
}
PEDIDO ||--|{ ITEM_PEDIDO : contém
PEDIDO {
uuid id PK
uuid usuario_id FK
decimal total
string status
timestamp criado_em
}
ITEM_PEDIDO }|--|| PRODUTO : referencia
ITEM_PEDIDO {
uuid id PK
uuid pedido_id FK
uuid produto_id FK
int quantidade
decimal preco
}
PRODUTO ||--o{ PRODUTO_CATEGORIA : "pertence a"
PRODUTO {
uuid id PK
string nome
text descricao
decimal preco
int estoque
}
CATEGORIA ||--o{ PRODUTO_CATEGORIA : contém
CATEGORIA {
uuid id PK
string nome
uuid categoria_pai_id FK
}
PRODUTO_CATEGORIA {
uuid produto_id PK,FK
uuid categoria_id PK,FK
}
DER com Relacionamentos Explicados
erDiagram
CLIENTE ||--o{ PEDIDO : "faz (1:N)"
PEDIDO ||--|{ ITEM_LINHA : "contém (1:N, obrigatório)"
PRODUTO ||--o{ ITEM_LINHA : "aparece em (1:N)"
CLIENTE }|--|| ENDERECO : "tem cobrança (N:1, obrigatório)"
CLIENTE }o--o{ ENDERECO : "tem entrega (N:N)"
Notação de relacionamentos:
||exatamente umo|zero ou um}|um ou mais}ozero ou mais
Fluxogramas
Lógica de Decisão
flowchart TD
A[Início: Login do Usuário] --> B{Credenciais válidas?}
B -->|Sim| C{2FA habilitado?}
B -->|Não| D[Mostrar mensagem de erro]
D --> A
C -->|Sim| E[Enviar código 2FA]
E --> F{Código válido?}
F -->|Sim| G[Criar sessão]
F -->|Não| H{Tentativas < 3?}
H -->|Sim| E
H -->|Não| I[Bloquear conta]
C -->|Não| G
G --> J[Redirecionar para dashboard]
J --> K[Fim]
I --> K
Fluxo de Processo
flowchart LR
subgraph "Pipeline CI"
A[Enviar Código] --> B[Executar Testes]
B --> C{Testes Passam?}
C -->|Sim| D[Construir Imagem]
C -->|Não| E[Notificar Desenvolvedor]
D --> F[Enviar para Registro]
end
subgraph "Pipeline CD"
F --> G[Implantar em Staging]
G --> H[Executar Testes E2E]
H --> I{Testes Passam?}
I -->|Sim| J[Implantar em Produção]
I -->|Não| K[Rollback]
end
Diagramas de Estado
Máquina de Estado de Pedido
stateDiagram-v2
[*] --> Rascunho: Criar pedido
Rascunho --> Pendente: Enviar
Rascunho --> Cancelado: Cancelar
Pendente --> Confirmado: Pagamento recebido
Pendente --> Cancelado: Pagamento falhou
Pendente --> Cancelado: Timeout (24h)
Confirmado --> Em Processamento: Iniciar atendimento
Confirmado --> Cancelado: Cancelamento pelo cliente
Em Processamento --> Enviado: Enviar pedido
Em Processamento --> Cancelado: Fora de estoque
Enviado --> Entregue: Entrega confirmada
Enviado --> Devolvido: Devolução iniciada
Entregue --> Devolvido: Devolução solicitada
Entregue --> [*]: Completo
Devolvido --> Reembolsado: Processar reembolso
Reembolsado --> [*]: Completo
Cancelado --> [*]: Completo
Máquina de Estado de Conexão
stateDiagram-v2
[*] --> Desconectado
Desconectado --> Conectando: connect()
Conectando --> Conectado: sucesso
Conectando --> Desconectado: falha
Conectado --> Desconectado: disconnect()
Conectado --> Reconectando: conexão perdida
Reconectando --> Conectado: sucesso
Reconectando --> Desconectado: máx. tentativas
note right of Reconectando
Backoff exponencial
Máx. 5 tentativas
end note
Diagramas de Classes
classDiagram
class Repositorio~T~ {
<<interface>>
+buscarPorId(id: string) T
+buscarTodos() Lista~T~
+salvar(entidade: T) T
+deletar(id: string) void
}
class RepositorioUsuario {
-db: BancoDeDados
+buscarPorId(id: string) Usuario
+buscarTodos() Lista~Usuario~
+salvar(entidade: Usuario) Usuario
+deletar(id: string) void
+buscarPorEmail(email: string) Usuario
}
class Usuario {
+id: string
+email: string
+nome: string
+criadoEm: Data
+validar() boolean
}
Repositorio~T~ <|.. RepositorioUsuario
RepositorioUsuario --> Usuario