ADR-001 — Uso de Mermaid para diagramas de arquitetura¶

Status: ✅ Aceito Data: 2026-06-10

Contexto¶

A documentação de arquitetura do AMia requer diagramas C4 (Contexto e Containers) que sejam: - Versionados junto ao código-fonte da documentação (não imagens estáticas) - Renderizados automaticamente no site MkDocs sem dependências externas de servidor - Editáveis em texto puro por qualquer membro do time

As alternativas consideradas foram: 1. Mermaid — diagramas como código, renderizados client-side via JavaScript 2. PlantUML — diagramas como código, mas requer servidor externo (planttext.com ou servidor próprio) 3. draw.io / Lucidchart — ferramentas visuais, exportam SVG/PNG (imagens estáticas) 4. Structurizr — ferramenta específica para C4, mas requer conta e servidor

Decisão¶

Adotar Mermaid como ferramenta de diagramação para toda a documentação arquitetural do repositório AMia-Roadmap.

Justificativa¶

• Mermaid tem suporte nativo no tema Material para MkDocs via mkdocs-mermaid2-plugin, sem necessidade de servidor externo
• Diagramas são texto puro — versionados no Git, revisáveis via Pull Request, diff legível
• C4 Diagrams são suportados nas versões recentes do Mermaid (C4Context, C4Container)
• Zero dependências de infraestrutura adicionais em comparação ao PlantUML

Consequências¶

Positivas: - Pipeline CI/CD mais simples — sem dependência de servidor PlantUML - Diagramas sempre atualizados junto com o código da documentação - Qualquer desenvolvedor pode editar diagramas sem ferramentas especiais

Negativas: - Sintaxe Mermaid é menos expressiva que PlantUML para diagramas complexos - Suporte a C4 no Mermaid ainda é relativamente novo (menos recursos que Structurizr) - Alguns tipos de diagrama avançados (sequência complexa, deployment) têm limitações visuais