UML-Architect

UML-Architect Skill Anleitung

Diese Anleitung weist den AI Agent an, Architekturanalyse- und UML-Diagrammausgaben zu generieren, die 100% identisch und konsistent mit der deterministischen Ausgabe des UML-Architect MCP Servers sind.

---

1. 5-Phasen-Ausführungsprotokoll (Execution Pipeline)

Phase 1: Zielauflösung & Codebasis-Erkennung

1. Ziel identifizieren:
   • Handelt es sich um einen API-Endpunkt (z. B. POST /api/v1/orders/checkout), einen Funktionsnamen (z. B. processPayment) oder einen Datei-/Modulpfad (z. B. src/controllers/order.controller.ts)?
2. Manifest-Scan (ohne Kompilierung):
   • Überprüfen Sie die Manifestdateien im Projekt: package.json, go.mod, pom.xml, pyproject.toml, Cargo.toml, composer.json, Gemfile oder *.csproj.
   • Erkennen Sie das verwendete Framework: Express/NestJS, FastAPI/Django, Gin/Fiber, Spring Boot, Axum/Actix, ASP.NET, Laravel oder Rails.

Phase 2: Echter Call-Graph-Tracing (Strict Tracing - Zero Hallucination)

Verfolgen Sie den Ausführungsablauf aus dem tatsächlichen Quellcode:

1. Einstiegspunkt (Entrypoint): Öffnen Sie die zugehörige Routen-/Controller-Datei.
2. Middleware & Guards: Verfolgen Sie JWT-Token-Prüfungen, Sessions, Schema-Validierungen (Zod, Joi, Pydantic, DTO-Validator).
3. Controller / Handler: Überprüfen Sie die Logik zur Extraktion von Request-Parametern und die Delegation an die Service-Schicht.
4. Service / Domain Layer: Verfolgen Sie die Kern-Geschäftslogik, Hilfsfunktionen und Datenberechnungen.
5. Datenbank & ORM: Verfolgen Sie Abfrage-/Mutationsoperationen (SELECT, INSERT, UPDATE, Transaktionen Commit/Rollback).
6. Externe Integrationen: Verfolgen Sie HTTP-Aufrufe (Stripe, Bank-API, SendGrid, OAuth) oder RPC-Aufrufe.
7. Message Queue / Event: Verfolgen Sie asynchrone Event-Publikationen zu Kafka, RabbitMQ, SQS, Redis PubSub oder Celery.
8. Fehlerzweige: Bilden Sie try/catch-Blöcke, if err != nil, except oder Fehler-Guards auf alternative Zweige (alt) ab.

---

2. Standard-Partizipationsalias & Diagramm-Alias

Verwenden Sie das standardisierte Schema für Partizipationsnamen, damit Diagramme sauber, konsistent und gut lesbar sind:

Kategorie	Partizipations-ID	Partizipations-Label-Format	Partizipationstyp
Client / Aufrufer	Client	Client / Frontend App (oder User / Mobile App)	actor
Controller / Handler	Ctrl	<Dateiname/Controller> (Controller)	participant
Service Layer	Svc	<Service-Name> (Beispiel: OrderService)	participant
Drittanbieter / Extern	ExtAPI	<Anbieter/Gateway> (External API) (Beispiel: Stripe API)	participant
Datenbank / Speicher	DB	Database (Storage / ORM) (Beispiel: PostgreSQL Database)	participant
Warteschlange / Event Broker	Queue	Message Broker (Kafka / Queue)	participant

---

3. Syntax- & visuelle Theme-Regeln für Mermaid.js

1. Theme Directive (Pflicht in der ersten Zeile des Diagramms): Verwenden Sie standardmäßig das moderne tokyo-night-Theme:

   %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
   

2. Sequenzdiagramm:
   • Fügen Sie immer sequenceDiagram und autonumber ein.
   • Verwenden Sie ->> für synchron, -->> für Antwort/Rückgabe und -) für asynchron/Queue-Event.
   • Verpacken Sie Verzweigungen (fehlgeschlagene vs. erfolgreiche Validierung) in alt- und else-Blöcke:

     alt Validierung Input / Auth fehlgeschlagen
         Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
     else Validierung erfolgreich (Happy Path)
         Ctrl->>Svc: processRequest(payload)
         ...
     end
     

3. Self-Healing Syntax (Anti-Fehler):
   • Vermeiden Sie eckige Klammern ohne Anführungszeichen in Nachrichten.
   • Verwenden Sie keinen Schrägstrich (/) direkt in Partizipations-IDs (verwenden Sie immer saubere Aliase wie Ctrl, Svc).

---

4. Pflichtformat des Ausgabevertrags (Canonical Output Contract)

Jede Diagramm-Antwort MUSS exakt der folgenden Markdown-Struktur entsprechen, um mit der Ausgabe des MCP Servers identisch zu sein:

# UML Diagramm: <Target / Endpunkt-Name>

> *Automatisch generiert von **UML-Architect Skill Agent** (v1.0.0)*

## Visuelles Diagramm
```mermaid
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
sequenceDiagram
    autonumber
    actor Client as Client / Frontend App
    participant Ctrl as <ControllerName> (Controller)
    participant Svc as <ServiceName>
    participant DB as Database (Storage / ORM)
    participant Queue as Message Broker (Kafka / Queue)

    Client->>Ctrl: <HTTP_METHOD> <URL_PATH>
    alt Validierung Input / Auth fehlgeschlagen
        Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
    else Validierung erfolgreich (Happy Path)
        Ctrl->>Svc: processRequest(payload)
        Svc->>DB: Save / Query Transaction Record
        DB-->>Svc: DB Commit Success
        Ctrl-)Queue: publish("event.completed", payload)
        Ctrl-->>Client: 200 OK / 201 Created (Success Payload)
    end
```

<details>
<summary>Alternatives Format anzeigen (PlantUML)</summary>

```puml
@startuml
autonumber
skinparam BoxPadding 10
skinparam ParticipantPadding 10
actor "Client / Frontend App" as Client
participant "<ControllerName> (Controller)" as Ctrl
participant "<ServiceName>" as Svc
participant "Database (Storage / ORM)" as DB
participant "Message Broker (Kafka / Queue)" as Queue

Client -> Ctrl: <HTTP_METHOD> <URL_PATH>
alt Validierung Input / Auth fehlgeschlagen
Ctrl --> Client: 400 Bad Request / 401 Unauthorized
else Validierung erfolgreich (Happy Path)
Ctrl -> Svc: processRequest(payload)
Svc -> DB: Save / Query Transaction Record
DB --> Svc: DB Commit Success
Ctrl -> Queue: publish("event.completed", payload)
Ctrl --> Client: 200 OK / 201 Created (Success Payload)
end
@enduml
```
</details>

### Erläuterung des Architekturflusses (<Target / Endpunkt-Name>)

Dieser Ausführungsablauf umfasst **<N> Hauptkomponenten**:

* **Client / Frontend App** (`Client`): Fungiert als aufrufende Benutzerentität.
* **<ControllerName> (Controller)** (`Ctrl`): Fungiert als Entität zur Steuerung von Anfrage und Antwort.
* **<ServiceName>** (`Svc`): Fungiert als Bereitsteller der fachlichen Geschäftslogik.
* **Database (Storage / ORM)** (`DB`): Fungiert als Medium zur Persistierung von Transaktionsdaten.
* **Message Broker (Kafka / Queue)** (`Queue`): Fungiert als Empfänger asynchroner Events.

#### Detaillierte Ausführungsschritte:
1. **Client** sendet eine Anfrage `<HTTP_METHOD> <URL_PATH>` an **Ctrl**.
   * *Bedingungsprüfung*: Wenn Parameter ungültig sind oder die Authentifizierung fehlschlägt, wird der Ablauf mit einer HTTP-Antwort 400/401 abgebrochen.
2. **Ctrl** delegiert die gültige Payload an **Svc**.
3. **Svc** führt eine Abfrage/Mutation an **DB** durch und erhält eine Bestätigung der Speicherung.
4. **Ctrl** sendet ein Event an **Queue**.
5. **Ctrl** gibt eine erfolgreiche HTTP-Antwort 200/201 an **Client** zurück.

#### Fehlerbehandlung & Ausnahmen (Error Pathways):
* **ValidationException**: Führt zu einer HTTP-Antwort `400`, wenn die Payload nicht den Schema-Anforderungen entspricht.
* **UnauthorizedException**: Führt zu einer HTTP-Antwort `401`, wenn das Autorisierungstoken ungültig oder abgelaufen ist.
* **InternalException**: Führt zu einer HTTP-Antwort `500` bei Netzwerkfehlern oder Datenbank-Rollbacks.

---

5. Weitere Diagrammtypen (auf Benutzerwunsch)

• Flussdiagramm / Aktivitätsdiagramm: Verwenden Sie flowchart TD mit runden Start-/Endknoten ([ ... ]), Entscheidungsraute { "Bedingung?" } und Prozessbox [ ... ].
• Zustandsdiagramm: Verwenden Sie stateDiagram-v2 mit Startzustand [*], Zustandsübergängen, Guard-Bedingungen und Endzustand [*].
• Komponenten-/Architekturdiagramm: Verwenden Sie graph TD mit verschachtelten subgraph (Presentation Layer, Business Logic Layer, Data & Persistence Layer).