joshfinnie/mermaid-gen

O objetivo destes diagramas é que alguém novo no repositório possa confiar neles. Um diagrama que inventa um serviço ou perde o banco de dados é pior do que nenhum, então tudo aqui é sobre desenhar o que o código realmente mostra.

1. Levantamento antes de desenhar

Execute scripts/survey.py (os caminhos nesta skill são relativos à sua pasta) na raiz do repositório:

python3 scripts/survey.py /caminho/para/repositorio > /tmp/mermaid-survey.txt

Ele lista módulos com contagens de arquivos, manifestos, pontos de entrada, serviços externos encontrados em dependências declaradas, fontes de modelo de dados e o grafo de importação entre módulos com contagens. Cada aresta de importação vem de comandos de importação reais, portanto, use essas arestas como a espinha dorsal do diagrama de arquitetura. Se um módulo contiver a maior parte do código e precisar ser dividido, execute novamente com --depth 3.

Em seguida, leia o que o script não pode ver:

• o README e quaisquer documentos existentes, para os nomes que a equipe já usa
• pontos de entrada, para ver o que é executado como seu próprio processo (servidores, workers, CLIs, cron jobs, lambdas)
• configuração de implantação (Dockerfile, arquivos compose, fly.toml, serverless/CDK, Terraform), para o que é implantado separadamente e com o que se comunica
• chamadas que cruzam um limite de processo: clientes HTTP e URLs base, publicadores e consumidores de fila, clientes SDK para serviços externos

Mantenha uma breve nota de qual arquivo suporta cada caixa e seta. Ela se torna a lista de Fontes na saída.

Se o usuário pedir apenas um diagrama ("um diagrama ER do nosso banco de dados"), faça apenas esse, mas ainda assim faça o levantamento primeiro.

2. Visão geral da arquitetura

Desenhe um flowchart das peças implantáveis e dos módulos dentro delas, mais os armazenamentos de dados e serviços externos que usam. Mire em 6 a 20 nós. Um repositório maior é agrupado em subgráficos por unidade implantável, não mais caixas.

• Nós são coisas que um desenvolvedor nomearia: "Servidor API", "aplicativo web", "consumidor firehose", "PostgreSQL", "Stripe". Use os nomes da equipe do README ou nomes de pacotes.
• Setas apontam do chamador para o chamado e dizem como quando cruzam um processo ("REST /api", "SQL", "upload S3"). Deixe as importações dentro do processo sem rótulo.
• Remova o que não explica o sistema: módulos utilitários que todos importam, pacotes apenas de tipos, testes, scripts de construção. Mencione-os no texto se forem importantes.
• Não desenhe o que não pode apontar. Se suspeitar de uma conexão, mas não conseguir encontrar o código para ela, deixe-a de fora e diga isso no texto.

As convenções de forma e estilo estão em references/diagram-guide.md.

3. Modelo de dados

Desenhe um erDiagram apenas quando o levantamento listar fontes de modelo de dados; sem nenhuma, diga isso em uma frase e pule. Não infira tabelas a partir de tipos de API ou nomes de variáveis, porque um esquema adivinhado parece tão autoritativo quanto um real.

• Migrações são a verdade quando existem. Aplique-as em ordem, para que comandos posteriores ALTER, DROP e renomeações prevaleçam. Se os modelos ORM discordarem das migrações, siga as migrações e anote a incompatibilidade.
• Dois conjuntos de migrações (por exemplo, um antigo supabase/migrations/ e uma pasta drizzle/ ativa) geralmente significa que um está desatualizado. Siga aquele para o qual o comando de migração do aplicativo ou a configuração ORM aponta (drizzle.config.*, prisma/schema.prisma, o script migrate no package.json) e nomeie o desatualizado no texto.
• Mostre chaves e as colunas que identificam uma linha: chaves primárias, chaves estrangeiras, colunas únicas e algumas colunas que um leitor precisa para reconhecer a entidade. Pule carimbos de data/hora e outras colunas de registro, a menos que sejam importantes.
• Leia a cardinalidade das restrições. Uma chave estrangeira não nula é exatamente uma no lado pai, uma anulável é zero ou uma, e uma chave estrangeira única torna o relacionamento um-para-um. Rotule cada relacionamento com uma frase verbal curta.
• Acima de cerca de 15 entidades, divida o diagrama por domínio em vez de desenhar uma parede de tabelas.

4. Escreva o arquivo

Escreva docs/architecture.md ou atualize-o se existir. Se o repositório mantiver documentos em outro lugar, siga isso e, se o usuário nomeou um caminho, use o dele. Para cada diagrama:

## Arquitetura

Duas ou três frases sobre o que o diagrama mostra e o que ele omite.

<!-- mermaid-gen:start architecture -->
```mermaid
flowchart LR
  ...
```
<!-- mermaid-gen:end architecture -->

**Fontes:** `cmd/server/main.go`, `internal/handler/`, `fly.toml`

Os comentários de marcador permitem que uma execução posterior substitua apenas o diagrama sem tocar na prosa editada manualmente. Ao atualizar um arquivo existente, altere apenas o que está entre os marcadores, mais a explicação e as fontes diretamente ao redor deles.

5. Verifique se renderiza

Execute scripts/lint_mermaid.py no arquivo:

python3 scripts/lint_mermaid.py /caminho/para/repositorio/docs/architecture.md

Ele detecta os erros que mais frequentemente quebram a renderização: caracteres especiais em rótulos não citados, palavras reservadas como end como IDs de nós, um subgraph não fechado e relacionamentos ou atributos ER malformados. Corrija todos os erros antes de terminar. Se mmdc (mermaid-cli) estiver instalado, renderize com ele também.

Termine informando ao usuário onde está o arquivo, o que cada diagrama cobre e o que você deixou de fora ou não pôde confirmar.