lidorshimoni/visualize

Visualize: Muster für Architektur- und Ablaufvisualisierung

Zielsetzung

Textuelle Architekturen, komplexe Algorithmen, Multi-Agent-Interaktionen und Datenmodelle unter Verwendung der standardisierten Mermaid-Syntax in eindeutige visuelle Diagramme umwandeln.

Theoretische Grundlage

Verwurzelt in der Cognitive-Load-Theorie und dem C4-Modell für Softwarearchitektur (Brown, 2018). Visuelle Modelle verankern abstrakte Systembeschreibungen, sodass Grenzen, Datenflüsse und Zustandsübergänge sowohl von Menschen als auch von Agenten sofort überprüfbar werden.

Standard-Diagramm-Archetypen

1. Komponenten- und Grenzarchitektur (C4 Container / Component)

Verwenden Sie flowchart TD oder flowchart LR mit Subgraphen, um Architekturschichten darzustellen:

flowchart TD
    subgraph Client["Client-Schicht"]
        Web["Webanwendung (React)"]
        CLI["CLI-Tool (Python)"]
    end

    subgraph Gateway["API-Gateway"]
        Proxy["Reverse Proxy / Nginx"]
        Auth["Authentifizierungsdienst (JWT)"]
    end

    subgraph Core["Kerndienste"]
        App["Anwendungs-Engine"]
        Worker["Asynchroner Hintergrund-Worker"]
    end

    subgraph Data["Persistenzschicht"]
        DB[("PostgreSQL")]
        Queue[("Redis Queue")]
    end

    Web --> Proxy
    CLI --> Proxy
    Proxy --> Auth
    Auth --> App
    App --> Queue
    Queue --> Worker
    Worker --> DB
    App --> DB

2. Anfrage-/Antwort- und Protokollablauf (Sequenzdiagramm)

Verwenden Sie sequenceDiagram mit Aktivierungslebenslinien, um chronologische Interaktionen darzustellen:

sequenceDiagram
    autonumber
    actor Benutzer
    participant Agent as Codierungs-Agent
    participant Werkzeug as Werkzeug-Ausführer
    participant Git as Versionskontrolle

    Benutzer->>Agent: Feature-Implementierung anfordern
    Agent->>Werkzeug: Fehlschlagenden Test ausführen (Rot)
    Werkzeug-->>Agent: Test wie erwartet fehlgeschlagen
    Agent->>Werkzeug: Minimalen Code schreiben (Grün)
    Agent->>Werkzeug: Testsuite ausführen
    Werkzeug-->>Agent: Alle Tests bestanden
    Agent->>Git: Atomare Änderung committen
    Git-->>Agent: Commit-Hash erzeugt
    Agent-->>Benutzer: Abgeschlossene Aufgabe melden

3. Zustandsautomaten und Lebenszyklen (Zustandsdiagramm)

Verwenden Sie stateDiagram-v2 für Entitätszustände, Aufgabenstatus oder Verbindungslebenszyklen:

stateDiagram-v2
    [*] --> Entwurf
    Entwurf --> InPrüfung: Zur Prüfung einreichen
    InPrüfung --> Genehmigt: Verifikation bestanden
    InPrüfung --> ÄnderungenErforderlich: Blocker gefunden
    ÄnderungenErforderlich --> InPrüfung: Korrektur erneut einreichen
    Genehmigt --> InUmsetzung: Implementierung starten
    InUmsetzung --> Abgeschlossen: Alle Tests bestanden
    Abgeschlossen --> [*]

4. Datenmodelle und Beziehungen (Entity-Relationship-Diagramm)

Verwenden Sie erDiagram für relationale Schemata und Domänenmodelle:

erDiagram
    PROJEKT ||--o{ SPEZIFIKATION : enthält
    SPEZIFIKATION ||--o{ TICKET : zerlegt_in
    TICKET ||--o{ COMMIT : implementiert_durch
    TICKET {
        string id PK
        string titel
        string status
        string blockiert_von
    }

Mermaid-Syntax-Sicherheitsregeln

1. Knotenbeschriftungen mit Sonderzeichen immer in Anführungszeichen setzen:
   • id["Beschriftung (Zusatzinfo)"] anstelle von id[Beschriftung (Zusatzinfo)].
2. Nur unterstützte Diagrammtypen verwenden:
   • Flussdiagramme (flowchart TD), Sequenzdiagramme (sequenceDiagram), Zustandsdiagramme (stateDiagram-v2), Klassendiagramme (classDiagram), ER-Diagramme (erDiagram).
3. Rohes HTML in Knotentexten vermeiden: Reines Markdown oder sauberen Text innerhalb von Knotenstrings verwenden.

---

Quellenangaben & Herkunft

1. Das C4-Modell für Softwarearchitektur: Brown, S. (2018). Software Architecture for Developers: Visualise, document and explore your software architecture. Leanpub.
2. Mermaid-Graphing-Standard: Sveidqvist, K., et al. (2014-2026). Mermaid: Markdown-inspired syntax for generating charts and diagrams (https://mermaid.js.org/).
3. Cognitive Load Theory in der Softwarevisualisierung: Sweller, J. (2011). Cognitive Load Theory. Psychology of Learning and Motivation, Vol. 55.