joshfinnie/mermaid-gen

Ces diagrammes ont pour but qu'un nouveau venu dans le dépôt puisse leur faire confiance. Un diagramme qui invente un service ou oublie la base de données est pire que rien, donc tout ici consiste à dessiner ce que le code montre réellement.

1. Analyser avant de dessiner

Exécutez scripts/survey.py (les chemins dans cette compétence sont relatifs à son dossier) à la racine du dépôt :

python3 scripts/survey.py /chemin/vers/le/depot > /tmp/mermaid-survey.txt

Il liste les modules avec le nombre de fichiers, les manifestes, les points d'entrée, les services externes trouvés dans les dépendances déclarées, les sources du modèle de données et le graphe d'importation entre les modules avec des compteurs. Chaque arête d'importation provient de déclarations d'import réelles, utilisez donc ces arêtes comme colonne vertébrale du diagramme d'architecture. Si un module contient la plupart du code et doit être divisé, relancez avec --depth 3.

Ensuite, lisez ce que le script ne peut pas voir :

• le README et toute documentation existante, pour les noms déjà utilisés par l'équipe
• les points d'entrée, pour voir ce qui s'exécute comme processus séparé (serveurs, workers, CLI, cron jobs, lambdas)
• la configuration de déploiement (Dockerfile, fichiers compose, fly.toml, serverless/CDK, Terraform), pour ce qui est déployé séparément et à quoi il parle
• les appels qui traversent une frontière de processus : clients HTTP et URL de base, éditeurs et consommateurs de files d'attente, clients SDK pour les services externes

Gardez une courte note du fichier qui supporte chaque boîte et flèche. Elle devient la liste des Sources dans la sortie.

Si l'utilisateur demande un seul diagramme ("un diagramme ER de notre base de données"), faites uniquement celui-là, mais analysez d'abord.

2. Vue d'architecture

Dessinez un flowchart des éléments déployables et des modules qu'ils contiennent, ainsi que des bases de données et des services externes qu'ils utilisent. Visez 6 à 20 nœuds. Un dépôt plus grand est regroupé en sous-graphes par unité déployable, pas en plus de boîtes.

• Les nœuds sont des choses qu'un développeur nommerait : "Serveur API", "application web", "consommateur firehose", "PostgreSQL", "Stripe". Utilisez les noms de l'équipe provenant du README ou des noms de packages.
• Les flèches pointent de l'appelant vers l'appelé et précisent comment lorsque cela traverse un processus ("REST /api", "SQL", "upload S3"). Laissez les importations intra-processus sans étiquette.
• Supprimez ce qui n'explique pas le système : les modules utilitaires que tout le monde importe, les packages de types uniquement, les tests, les scripts de construction. Mentionnez-les dans le texte s'ils sont importants.
• Ne dessinez pas ce que vous ne pouvez pas pointer. Si vous suspectez une connexion mais ne trouvez pas le code correspondant, laissez-la de côté et mentionnez-le dans le texte.

Les conventions de forme et de style se trouvent dans references/diagram-guide.md.

3. Modèle de données

Dessinez un erDiagram uniquement lorsque l'analyse liste des sources de modèle de données ; sinon, dites-le en une phrase et passez. N'inférez pas de tables à partir de types d'API ou de noms de variables, car un schéma deviné semble tout aussi faisant autorité qu'un vrai.

• Les migrations sont la vérité lorsqu'elles existent. Appliquez-les dans l'ordre, donc les ALTER, DROP et renommages ultérieurs l'emportent. Si les modèles ORM sont en désaccord avec les migrations, suivez les migrations et notez l'incohérence.
• Deux ensembles de migrations (par exemple, un ancien supabase/migrations/ et un dossier drizzle/ actif) signifient généralement que l'un est obsolète. Suivez celui vers lequel pointent la commande de migration de l'application ou la configuration ORM (drizzle.config.*, prisma/schema.prisma, le script migrate dans package.json), et nommez l'obsolète dans le texte.
• Affichez les clés et les colonnes qui identifient une ligne : clés primaires, clés étrangères, colonnes uniques et quelques colonnes dont un lecteur a besoin pour reconnaître l'entité. Ignorez les horodatages et autres colonnes de comptabilité sauf si elles sont importantes.
• Lisez la cardinalité à partir des contraintes. Une clé étrangère non nulle est exactement un du côté parent, une nullable est zéro ou un, et une clé étrangère unique rend la relation un-à-un. Étiquetez chaque relation avec une courte phrase verbale.
• Au-delà d'environ 15 entités, divisez le diagramme par domaine au lieu de dessiner un mur de tables.

4. Écrire le fichier

Écrivez docs/architecture.md, ou mettez-le à jour s'il existe. Si le dépôt conserve les documents ailleurs, suivez cela, et si l'utilisateur a nommé un chemin, utilisez le leur. Pour chaque diagramme :

## Architecture

Deux ou trois phrases sur ce que le diagramme montre et ce qu'il omet.

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

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

Les commentaires marqueurs permettent à une exécution ultérieure de remplacer uniquement le diagramme sans toucher à la prose modifiée manuellement. Lors de la mise à jour d'un fichier existant, modifiez uniquement ce qui se trouve entre les marqueurs, ainsi que l'explication et les sources directement autour d'eux.

5. Vérifier le rendu

Exécutez scripts/lint_mermaid.py sur le fichier :

python3 scripts/lint_mermaid.py /chemin/vers/le/depot/docs/architecture.md

Il détecte les erreurs qui cassent le plus souvent le rendu : caractères spéciaux dans les étiquettes non guillemetées, mots réservés comme end comme identifiants de nœud, un subgraph non fermé, et des relations ou attributs ER mal formés. Corrigez chaque erreur avant de terminer. Si mmdc (mermaid-cli) est installé, faites également le rendu avec.

Terminez en indiquant à l'utilisateur où se trouve le fichier, ce que couvre chaque diagramme, et tout ce que vous avez omis ou n'avez pas pu confirmer.