joshfinnie/mermaid-gen

Der Sinn dieser Diagramme ist, dass jemand, der neu im Repository ist, ihnen vertrauen kann. Ein Diagramm, das einen Service erfindet oder die Datenbank vergisst, ist schlimmer als keins, daher dreht sich hier alles darum, das zu zeichnen, was der Code tatsächlich zeigt.

1. Vor dem Zeichnen untersuchen

Führen Sie scripts/survey.py (Pfade in dieser Fähigkeit sind relativ zu ihrem Ordner) gegen das Repository-Stammverzeichnis aus:

python3 scripts/survey.py /path/to/repo > /tmp/mermaid-survey.txt

Es listet Module mit Dateizählungen, Manifeste, Einstiegspunkte, externe Services, die in deklarierten Abhängigkeiten gefunden wurden, Datenmodellquellen und den Importgraphen zwischen Modulen mit Zählungen auf. Jede Importkante stammt von echten Import-Anweisungen, verwenden Sie diese Kanten als Rückgrat des Architekturdiagramms. Wenn ein Modul den Großteil des Codes enthält und aufgeteilt werden muss, führen Sie es erneut mit --depth 3 aus.

Lesen Sie dann, was das Skript nicht sehen kann:

• die README und alle vorhandenen Dokumentationen, für die Namen, die das Team bereits verwendet
• Einstiegspunkte, um zu sehen, was als eigener Prozess läuft (Server, Worker, CLIs, Cron-Jobs, Lambdas)
• Bereitstellungskonfiguration (Dockerfile, compose-Dateien, fly.toml, serverless/CDK, Terraform), für das, was separat bereitgestellt wird und womit es kommuniziert
• Aufrufe, die eine Prozessgrenze überschreiten: HTTP-Clients und Basis-URLs, Queue-Publisher und -Consumer, SDK-Clients für externe Services

Behalten Sie eine kurze Notiz, welche Datei jede Box und jeden Pfeil unterstützt. Sie wird zur Quellenliste in der Ausgabe.

Wenn der Benutzer nur ein Diagramm möchte ("ein ER-Diagramm unserer Datenbank"), erstellen Sie nur das, aber untersuchen Sie trotzdem zuerst.

2. Architekturübersicht

Zeichnen Sie ein flowchart der bereitstellbaren Teile und der Module darin, zusammen mit den Datenspeichern und externen Services, die sie verwenden. Zielen Sie auf 6 bis 20 Knoten ab. Ein größeres Repository wird in Untergraphen pro bereitstellbarer Einheit gruppiert, nicht in mehr Boxen.

• Knoten sind Dinge, die ein Entwickler benennen würde: "API-Server", "Web-App", "Firehose-Consumer", "PostgreSQL", "Stripe". Verwenden Sie die Namen des Teams aus der README oder Paketnamen.
• Pfeile zeigen vom Aufrufer zum Aufgerufenen und sagen, wie es eine Prozessgrenze überschreitet ("REST /api", "SQL", "S3-Upload"). Lassen Sie prozessinterne Importe unbeschriftet.
• Lassen Sie weg, was das System nicht erklärt: Hilfsmodule, die jeder importiert, reine Typen-Pakete, Tests, Build-Skripte. Erwähnen Sie sie im Text, wenn sie wichtig sind.
• Zeichnen Sie nicht, worauf Sie nicht zeigen können. Wenn Sie eine Verbindung vermuten, aber keinen Code dafür finden, lassen Sie sie weg und erwähnen Sie dies im Text.

Form- und Stilkonventionen finden Sie in references/diagram-guide.md.

3. Datenmodell

Zeichnen Sie ein erDiagram nur, wenn die Untersuchung Datenmodellquellen auflistet; wenn keine vorhanden sind, sagen Sie dies in einem Satz und überspringen Sie es. Leiten Sie keine Tabellen aus API-Typen oder Variablennamen ab, da ein erratenes Schema genauso autoritär aussieht wie ein echtes.

• Migrationen sind die Wahrheit, wenn sie existieren. Wenden Sie sie in der Reihenfolge an, sodass spätere ALTER, DROP und Umbenennungen gewinnen. Wenn ORM-Modelle nicht mit den Migrationen übereinstimmen, folgen Sie den Migrationen und notieren Sie die Diskrepanz.
• Zwei Sätze von Migrationen (z. B. ein altes supabase/migrations/ und ein aktuelles drizzle/-Verzeichnis) bedeuten normalerweise, dass einer veraltet ist. Folgen Sie dem, auf den der Migrationsbefehl der App oder die ORM-Konfiguration zeigt (drizzle.config.*, prisma/schema.prisma, das migrate-Skript in package.json), und nennen Sie den veralteten im Text.
• Zeigen Sie Schlüssel und die Spalten, die eine Zeile identifizieren: Primärschlüssel, Fremdschlüssel, eindeutige Spalten und einige Spalten, die ein Leser benötigt, um die Entität zu erkennen. Überspringen Sie Zeitstempel und andere Buchhaltungsspalten, es sei denn, sie sind wichtig.
• Lesen Sie die Kardinalität aus den Constraints ab. Ein nicht-null Fremdschlüssel ist genau einer auf der übergeordneten Seite, ein nullable ist null oder eins, und ein eindeutiger Fremdschlüssel macht die Beziehung eins-zu-eins. Beschriften Sie jede Beziehung mit einer kurzen Verbphrase.
• Ab etwa 15 Entitäten teilen Sie das Diagramm nach Domäne auf, anstatt eine einzige Tabelle zu zeichnen.

4. Die Datei schreiben

Schreiben Sie docs/architecture.md, oder aktualisieren Sie sie, falls sie existiert. Wenn das Repository die Dokumentation an einem anderen Ort aufbewahrt, folgen Sie dem, und wenn der Benutzer einen Pfad angegeben hat, verwenden Sie seinen. Für jedes Diagramm:

## Architektur

Zwei oder drei Sätze darüber, was das Diagramm zeigt und was es auslässt.

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

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

Die Marker-Kommentare ermöglichen es einem späteren Durchlauf, nur das Diagramm zu ersetzen, ohne den Prosa zu berühren, der von Hand bearbeitet wurde. Wenn Sie eine vorhandene Datei aktualisieren, ändern Sie nur das, was zwischen den Markern steht, sowie die Erklärung und Quellen direkt um sie herum.

5. Überprüfen, ob es gerendert wird

Führen Sie scripts/lint_mermaid.py für die Datei aus:

python3 scripts/lint_mermaid.py /path/to/repo/docs/architecture.md

Es erfasst die Fehler, die das Rendern am häufigsten unterbrechen: Sonderzeichen in nicht zitierten Labels, reservierte Wörter wie end als Knoten-IDs, ein nicht geschlossenes subgraph und fehlerhafte ER-Beziehungen oder -Attribute. Beheben Sie jeden Fehler, bevor Sie fertig sind. Wenn mmdc (mermaid-cli) installiert ist, rendern Sie auch damit.

Beenden Sie, indem Sie dem Benutzer mitteilen, wo die Datei ist, was jedes Diagramm abdeckt und was Sie ausgelassen oder nicht bestätigen konnten.