panfu/arch-diagram

Was macht arch-diagram?

Zwei Methoden, einzeln oder verkettet nutzbar (natürliche Sprache → Mermaid → HTML).

• nl2mmd: Natürliche Sprache → Mermaid-Dialekt
• mmd2html: Mermaid-Dialekt → interaktives HTML (Vorlage: assets/template.html im Skill-Verzeichnis)

Gemeinsame Konvention: Mermaid-Dialekt

Struktur (drei Ebenen, korrespondierend mit Server → Dienst → Subdienst im HTML):

• Top-Level subgraph = Server, darin direction TB
• Zweite Ebene subgraph = Dienst (nur wenn der Dienst Subdienste hat; ansonsten wird der Dienst direkt als Knoten geschrieben)
• Knoten innerhalb eines Dienst-Subgraphen = Subdienste
• Alle Titel mit einfachen Anführungszeichen: subgraph X["Titel"], N["Titel"]

Anmerkungen (Meta): Im Titel trennt | den Namen von der Anmerkung; nach der HTML-Generierung wird die Anmerkung als heller, kleiner Text neben dem Namen angezeigt (z.B. Server-Spezifikationen, Ports, Aufgaben, Parameter). Ohne Anmerkung wird | weggelassen:

• subgraph WEB["Web Edge | Dual-Active · LAN"] → Servername "Web Edge", Anmerkung "Dual-Active · LAN"
• WEB_GW["API Gateway | QPS 3k"] → Dienstname + Anmerkung
• Parsing-Regel: Das letzte | trennt; links davon steht der Name, rechts die Anmerkung

Kantentypen werden durch Linienart ausgedrückt (fest):

Typ	Linie	Bedeutung
sync (Synchronisation)	==>	Datensynchronisation / Rückschreiben
call (Aufruf)	-->	API / RPC / WS
job (Job)	-.->	cron / geplante Aufgabe / Push
data (Lesen)	-.-	Schreibgeschützte Datenbankabfrage

• Kantenbeschriftung: ==>|"type · Zeitpunkt oder Frequenz"|, z.B. ==>|"sync · 07:10 4×/Tag"|; -->|"call"| kann weggelassen werden, wenn eindeutig.
• Knoten-IDs in Großschreibung mit Unterstrich: <Server>_<Dienst>_<Subdienst>, z.B. NAS_SCHED_FLAT
• Kanten können an Subgraphen (Dienst-/Server-Ebene) verankert werden – die Kante gilt dann auf dieser Granularität.
• Beginnt mit flowchart LR; interne Kanten innerhalb desselben Hosts werden normal geschrieben (im HTML erscheinen sie rechtsseitige Schleifen).

Methode 1: nl2mmd (Natürliche Sprache → Mermaid)

1. Entitätenerkennung: Maschinen/Hosts/Umgebungen → Server; darauf installierte oder laufende Software → Dienste; Komponenten/Funktionen/Aufgaben/Bibliotheken innerhalb der Software → Subdienste.
2. Beziehungserkennung: Verben werden konvertiert – Sync/Rückschreiben/Spiegelung → sync; Aufruf/Anfrage/Senden/Empfangen → call; täglich/geplant/cron/xx:xx/Push → job; Lesen/Abfragen/Whitebox → data. Zeit und Frequenz in die Kantenbeschriftung.
3. Bei Unsicherheit bezüglich der Hierarchie auf Dienstebene bleiben, keine künstlichen Subdienste erfinden.
4. Zahlen und Spezifikationen (Ports, Größen, Aufgaben, IP-Bereiche etc.) in die Knotenanmerkung: ["Name | Anmerkung"]; Zeit und Frequenz in die Kantenbeschriftung. Nichts verlieren.
5. Ausgabe eines vollständigen flowchart LR-Codeblocks, ohne Erläuterung.

Methode 2: mmd2html (Mermaid → interaktives HTML)

Schritte

1. assets/template.html vollständig einlesen (~38 KB, Single-File, Standarddaten entsprechen dem Inhalt von examples/sample.mmd).
2. Mermaid parsen (gemäß obiger Konvention), eine Mermaid-ID → Hierarchie-Pfad-Abbildung erzeugen: Der Pfad ist der per Punkt verbundene Server.Dienst.Subdienst (abgeschnitten nach der Verschachtelungstiefe). Wenn eine Kante an einem Subgraphen verankert ist, stoppt der Pfad auf der entsprechenden Ebene.
3. Den gesamten Block zwischen /*==DATA==*/ und /*==DATA-END==*/ im Template durch den neuen Datenblock ersetzen, den restlichen Code kein weiteres Zeichen ändern:

/*==DATA==*/
var ARCH_TITLE='Diagrammtitel (Terminaltitelzeile & standalone <title>)';
var ARCH_LSKEY='arch-<slug>';   // localStorage-Schlüssel, pro Diagramm eindeutig
var TYPE={sync:{c:'#3ecf8e',dash:'10 4',dur:'1.5s',label:'Sync'},
 call:{c:'#58a6ff',dash:'6 5',dur:'1.1s',label:'Aufruf'},
 job :{c:'#f0a942',dash:'2 4',dur:'0.85s',label:'Job'},
 data:{c:'#b18cff',dash:'14 5',dur:'1.9s',label:'Daten'}};
var COLS=[['srvA','srvB'],['srvC']];   // Standard-Spaltenlayout: Jede Array-Entspricht einer Gruppe von Server-IDs
var SERVERS=[
 {id:'srvA',short:'A',name:'A · Anzeigename',meta:'Anmerkung',ac:'#b18cff',svc:[
   {id:'svc1',short:'svc1',name:'Dienst1',meta:'',subs:[
     {id:'sub1',short:'sub1',name:'Subdienst1',meta:''}]},
   {id:'svc2',short:'svc2',name:'Dienst2'}]},
];
var EDGES=[
 {from:'srvA.svc1.sub1',to:'srvC.svc2',type:'sync',sched:'07:10 4×/Tag'},
];
/*==DATA-END==*/

Feldregeln:

• id in ASCII (Punkt-Pfad wird daraus gebildet); name kann Chinesisch enthalten; short ist der Kurzname in Verbindungen/Logs.
• meta stammt vom Teil nach dem letzten | im Knoten-/Subgraphentitel; falls nicht vorhanden, weglassen.
• ac aus der Farbpalette rotieren: #b18cff #3ecf8e #39d0c4 #58a6ff #f0a942
• type ∈ sync|call|job|data (entspricht den Mermaid-Linienarten); sched stammt vom Teil nach dem Typ in der Kantenbeschriftung, falls nicht vorhanden, schreibe Echtzeit
• COLS: grobe Anordnung nach Kantenfluss (Quellen links, Senken rechts); der Spaltengenerator für Einzelserver zentriert automatisch vertikal

4. Das Ergebnis in den Zielpfad schreiben (Fragment-Version). Für Doppelklick-Nutzung einmal einpacken:

<!doctype html><html lang="de"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{ARCH_TITLE}</title>
<style>html,body{margin:0;padding:0;background:#080b12}#svcarch{min-height:100vh}</style></head><body>
{fragment}</body></html>

QA

1. Pflicht: <script> extrahieren und mit node --check prüfen; Daten validieren – Anzahl Server/Dienste/Subdienste mit Mermaid abgleichen; Kantenanzahl = Mermaid-Kantenanzahl; Anzahl Standard-View-Verbindungen = Anzahl eindeutige (from,to,type)-Gruppen.
2. Wenn ein Browser verfügbar ist: Einen lokalen Server zwingend mit charset-Header starten (python3 -m http.server setzt keinen charset-Header, was zu chinesischen Zeichenfehlern führt; einen benutzerdefinierten Handler benötigen, der für .html den Header Content-Type: text/html; charset=utf-8 setzt). Titel, Zählung, ▾ servers-Granularitätswechsel und Collapse-Funktion prüfen.
3. Das Template nur im DATA-Block ändern; den restlichen Code (Drag & Drop, Collapsible & Auto-Layout, Persistenz) nicht neu implementieren.

Beispiele

• examples/sample.mmd — vollständiges Beispiel des Dialekts (4 Server, 9 Kanten, alle 4 Linienarten und interne Host-Kanten enthalten)
• examples/sample.html — aus dem Template generiertes Endprodukt (doppelklickfähig)

Integrierte Fähigkeiten des generierten HTML (nicht außerhalb des Templates neu implementieren)

Drag & Drop (Griffe oben, Alt-Taste zeigt alle Griffe), rechte Kante zum Breitenanpassen, Collapsible & Auto-Layout, drei Granularitätsstufen (servers/services/leaves), Edge-Log/Inspector, Layout- und Kollapszustand in localStorage gespeichert (Schlüssel = ARCH_LSKEY). Oberflächentexte auf Englisch.

• Zoom & Pan: Strg+Mausrad zoomt um den Cursor (0.4–2.5×), gedrückt halten von Strg + Mausbewegung = Pan; unten rechts die Prozentanzeige, Klick setzt zurück. Zoom/Pan werden ebenfalls in localStorage persistiert.
• Eingebauter Editor: Alt + Klick auf eine beliebige Knotenüberschrift (alle drei Ebenen) → Name/Anmerkung/Server-Rahmenfarbe ändern, Untergeordnete hinzufügen, löschen (zweistufige Bestätigung, kaskadierend Subgraphen und Kanten löschen); Alt + Klick auf eine Kante → Typ/Zeitpunkt ändern oder löschen; während Alt gedrückt ist, erscheint oben rechts ⇱ Export, öffnet ein Dialogfenster mit dem aktuellen Mermaid (Syntax-Highlight + Kopieren), darin enthalten: ⟲ Relayout & ↺ Daten zurücksetzen. Editor-Ergebnisse werden in localStorage persistiert.