Aula 18 - Diagramação Nível Expert com Mermaid 📊

📑 1. Fundamentos Teóricos & Análise Técnica

Arquiteturas de software sofrem mutações contínuas. Documentações visuais criadas através de capturas de tela de ferramentas gráficas manuais (Visio, draw.io) tornam-se obsoletas rapidamente, pois a alteração de um nó exige abrir a ferramenta, editar, reexportar e substituir o arquivo de imagem.

O paradigma Diagrams-as-Code (DaC) com Mermaid resolve essa deficiência mantendo os diagramas como texto puro dentro dos arquivos Markdown: 1. Vantagens do Modelo Docs-as-Code: - Versionamento no Git: Toda alteração no diagrama gera um diff legível linha a linha em Pull Requests, facilitando a revisão de arquitetura. - Renderização Dinâmica: Os diagramas adaptam-se automaticamente ao tema do site (alternando cores dinamicamente entre tema claro e escuro). - Zero Dependências de Binários: Nenhuma ferramenta proprietária é necessária para atualizar um fluxo. 2. Tipologias Avançadas Suportadas: - sequenceDiagram: Mensageria síncrona/assíncrona, blocos condicionais (alt/else) e ativacão de linha do tempo. - stateDiagram-v2: Modelagem de máquinas de estados finitas com transições concorrentes e estados compostos. - gantt: Cronogramas executivos com marcos e dependências de tarefas. - gitGraph: Representação exata de fluxos de branches e merges.

📐 Arquitetura Conceitual & Diagrama de Fluxo

sequenceDiagram
    autonumber
    actor Dev as Engenheiro de Software
    participant Git as Repositório Git (docs/*.md)
    participant CI as Pipeline de Build (MkDocs)
    participant Browser as Portal de Documentação
    Dev->>Git: Commit de diagrama em texto Mermaid
    Note over Git: Pull Request exibe diff claro em texto puro!
    Git->>CI: Dispara build do site estático
    CI->>CI: Valida sintaxe do Mermaid
    CI->>Browser: Publica página com SVG renderizado dinamicamente
    Browser->>Browser: Adapta cores conforme tema escuro/claro

🔍 Pilares e Diretrizes Técnicas

Nesta unidade, aprofundamos os seguintes conceitos fundamentais: - Versionamento Textual no Git: Rastreabilidade de alterações de arquitetura através do histórico clássico de commits. - Adaptação Dinâmica ao Tema: Renderização em SVG vetorial que respeita as variáveis CSS do modo escuro/claro. - Automação de Verificação de Sintaxe: Validação durante o CI impedindo a publicação de páginas com diagramas quebrados. - Redução do Débito de Documentação: Facilidade para qualquer desenvolvedor atualizar o diagrama editando poucas palavras de texto.

🛠️ 2. Implementação Prática em Documentação como Código (Docs-as-Code) e Mermaid JS

Abaixo está a implementação técnica de referência, estruturada com padrões de engenharia de software e foco em robustez:

// architecture_sequence.mermaid (Exemplo de Diagrama de Sequência Avançado com Loops e Alts)
sequenceDiagram
    autonumber
    actor User as Cliente Mobile
    participant Edge as API Gateway (Kong)
    participant Auth as AuthService (JWT/OAuth2)
    participant Order as OrderService (Microsserviço)
    participant DB as PostgreSQL (Cluster)

    User->>Edge: POST /api/v1/checkout (Bearer Token)
    Edge->>Auth: Validar Token JWT
    alt Token Válido
        Auth-->>Edge: Assinatura Válida (Tenant ID: 10)
        Edge->>Order: Criar Pedido (Payload JSON)
        Order->>DB: INSERT INTO orders (Transação ACID)
        DB-->>Order: Confirmação de Commit
        Order-->>Edge: Pedido Criado com Sucesso (HTTP 201)
        Edge-->>User: Retorno { status: "CRIADO", id: 1045 }
    else Token Expirado ou Inválido
        Auth-->>Edge: Falha na Validação (HTTP 401)
        Edge-->>User: Erro 401 Unauthorized (Renovação Necessária)
    end

💡 Análise Passo a Passo do Código

1. Uso de autonumber: Insere numeração sequencial automática nos passos para fácil referência cruzada no texto explicativo.
2. Blocos alt / else: Documenta visualmente o caminho de sucesso versus o fluxo de tratamento de exceções de negócio.
3. Atores e Participantes Claros: Identifica a fronteira física e lógica entre clientes externos, gateways e microsserviços internos.

🎯 3. Próximos Passos & Sequência Didática