Orchestrator/bahn/aisupport/steering/onboarding-dokumentation.md

inclusion

inclusion
manual

Onboarding-Dokumentation erstellen

Nutzung: Referenziere diese Datei mit #onboarding-dokumentation im Chat und sage: "Erstelle eine Onboarding-Dokumentation für dieses Projekt anhand des Plans."

---

Ziel

Automatische Erstellung einer Onboarding-/Migrationsdokumentation mit Fokus auf:

• Fachliche End-to-End-Flüsse
• Externe Schnittstellen
• Zentrale Datenobjekte

Diagramm-Standard

WICHTIG: Alle Diagramme MÜSSEN als Mermaid-Diagramme erstellt werden. PlantUML ist NICHT erlaubt. Mermaid-Diagramme werden direkt in Markdown-Dateien als Codeblöcke eingebettet ( `mermaid ). Es werden KEINE separaten Diagramm-Dateien erzeugt.

Ausgabestruktur

docs/
 index.md                    # Überblick, Schnellstart
 assumptionAndRisks.md       # Annahmen, Risiken, offene Fragen
 architecture/
    context.md              # Architekturkontext (mit eingebetteten Mermaid-Diagrammen)
 domain/
    data_model.md           # Datenmodell (mit eingebetteten Mermaid-Diagrammen)
 processes/
    [prozessname].md        # Je ein Dokument pro Fluss (mit eingebetteten Mermaid-Diagrammen)
 interfaces/
    external.md             # Externe Schnittstellen
 nfr.md                      # Nicht-funktionale Anforderungen

---

Fortschritt

Task	Status	Ergebnis
1. Inventar & Autodetektion	Offen	-
2. Architektur-Kontext	Offen	-
3. Fachliche Flüsse	Offen	-
4. Externe Schnittstellen	Offen	-
5. Datenmodell	Offen	-
6. NFRs & Monitoring	Offen	-
7. Abschluss & Konsolidierung	Offen	-

Legende: Offen | In Arbeit | Erledigt | Blockiert

Ermittelte Systeminfos (Task 1 ausfüllen):

• Systemname: [wird ermittelt]
• Systemtyp: [wird ermittelt]
• Haupttechnologien: [wird ermittelt]

---

Task 1: Inventar & Autodetektion

Aufgaben

• 1.1 Systemname ermitteln (aus pom.xml, package.json, .csproj, oder Verzeichnisname)
• 1.2 Systemtyp bestimmen (Integrationssystem / Microservices / Monolith / Batch)
• 1.3 Repository scannen nach Quellcode und Konfigurationen
• 1.4 Technologien erkennen (Sprachen, Frameworks, Integrationsplattformen)
• 1.5 Inventar-Tabelle erstellen
• 1.6 docs/index.md erstellen
• 1.7 docs/assumptionAndRisks.md erstellen

Suchmuster für Technologien

Typ	Dateien/Patterns
Java	.java, pom.xml, build.gradle
.NET	.cs, .csproj, .sln
JavaScript/TypeScript	.js, .ts, package.json
Python	.py, requirements.txt, pyproject.toml
TIBCO	.process, .xpdl, Adapter-Configs
Integration	WSDL, XSD, JMS/JDBC/HTTP/FTP Configs

Systemtyp-Heuristik

Indikator	Systemtyp
TIBCO .process, MuleSoft, Camel	Integrationssystem
Mehrere Services, Docker/K8s	Microservices
Ein Deployment, klare Module	Modularer Monolith
Ein Deployment, keine Module	Monolith
Scheduler, Jobs	Batch-System

Ausgabe: docs/index.md

# Projektdokumentation: [Systemname]

## Überblick
| Attribut | Wert |
|----------|------|
| Systemname | ... |
| Systemtyp | ... |
| Hauptsprache(n) | ... |
| Frameworks | ... |

[2-3 Sätze zum Projektzweck]

## Modulübersicht
| Modul | Zweck | Technologie | Pfad |
|-------|-------|-------------|------|

## Dokumentation
- [Architektur](architecture/context.md)
- [Datenmodell](domain/data_model.md)
- [Prozesse](processes/)
- [Schnittstellen](interfaces/external.md)
- [NFRs](nfr.md)

Nach Abschluss: Status auf , Systeminfos eintragen, weiter mit Task 2

---

Task 2: Architektur-Kontext

Aufgaben

• 2.1 Externe Systeme identifizieren (HTTP, Messaging, DB, Datei, Mail)
• 2.2 Interne Komponenten gruppieren (Core, Integration, Data Access)
• 2.3 Kommunikationsarten dokumentieren (Protokoll, Richtung, sync/async)
• 2.4 docs/architecture/context.md erstellen (mit eingebetteten Mermaid-Diagrammen)

Suchmuster

Typ	Suche nach
HTTP/SOAP	URLs, WSDL, REST-Clients, @WebService
Messaging	JMS-Queues, Kafka-Topics, RV-Subjects
Datenbank	JDBC-URLs, DataSource-Configs
Datei/FTP	FTP-Hosts, SFTP-Configs, Dateipfade
Mail	SMTP/IMAP-Server

Mermaid-Template: Architekturkontext

graph TB
    subgraph system["[Systemname]"]
        core["Core Processing"]
        integration["Integration Layer"]
        data["Data Access"]
    end

    subgraph external["Externe Systeme"]
        http["HTTP/SOAP Endpoint"]
        mq["Message Broker"]
        db[("Datenbank")]
    end

    integration -->|REST/SOAP| http
    integration -->|JMS| mq
    data -->|JDBC| db

Nach Abschluss: Status auf , weiter mit Task 3

---

Task 3: Fachliche Flüsse

Aufgaben

• 3.1 Zentrale End-to-End-Flüsse identifizieren (3-7 Stück)
• 3.2 Pro Fluss: Trigger, Schritte, Entscheidungen, Fehlerbehandlung analysieren
• 3.3 Pro Fluss: docs/processes/[name].md erstellen (mit eingebetteten Mermaid-Diagrammen)

Priorisierung

1. Geschäftskritische Prozesse
2. Häufig ausgeführte Flüsse
3. Komplexe Integrationsflüsse

Analyse pro Fluss

Aspekt	Fragen
Trigger	Was startet den Fluss?
Eingaben	Welche Daten?
Schritte	Welche Verarbeitung?
Entscheidungen	Welche Verzweigungen?
Fehler	Wie behandelt?
Ausgaben	Was produziert?

Mermaid-Template: Prozessfluss (Flowchart)

WICHTIG: Prozessdiagramme MÜSSEN als Mermaid Flowcharts erstellt werden.

flowchart TD
    start([Start]) --> trigger["Trigger empfangen<br/><i>System A</i>"]
    trigger --> validate["Daten validieren<br/><i>System B</i>"]
    validate --> check{Validierung OK?}

    check -->|ja| transform["Daten transformieren<br/><i>System B</i>"]
    transform --> external["Externe Verarbeitung<br/><i>System C</i>"]
    external --> result["Ergebnis zurückliefern<br/><i>System C</i>"]
    result --> process["Ergebnis verarbeiten<br/><i>System B</i>"]
    process --> respond["Ergebnis an Aufrufer senden<br/><i>System A</i>"]
    respond --> ende([Ende])

    check -->|nein| logError["Fehler loggen<br/><i>System B</i>"]
    logError --> notify["Fehlerbenachrichtigung<br/><i>System A</i>"]
    notify --> fehlerEnde([Ende])

    style start fill:#2d6a4f,color:#fff
    style ende fill:#2d6a4f,color:#fff
    style fehlerEnde fill:#d00000,color:#fff
    style check fill:#ffd166,color:#000

Alternativ: Mermaid Sequenzdiagramm (für Nachrichtenflüsse)

sequenceDiagram
    participant A as System A
    participant B as System B
    participant C as System C

    A->>B: Trigger senden
    B->>B: Daten validieren
    alt Validierung OK
        B->>C: Externe Verarbeitung
        C-->>B: Ergebnis
        B-->>A: Erfolgsantwort
    else Validierung fehlgeschlagen
        B-->>A: Fehlerbenachrichtigung
    end

Mermaid Flowchart-Elemente

Element	Syntax	Verwendung
Start/Ende	([Text])	Prozessbeginn/-ende (Stadion-Form)
Aktion	["Text"]	Einzelner Schritt (Rechteck)
Entscheidung	{Text}	Verzweigung (Raute)
Richtung	--> / `-->	Label
Subgraph	subgraph Name ... end	Gruppierung/Swimlane
Styling	style nodeId fill:#color	Visuelle Hervorhebung

Nach Abschluss: Status auf , weiter mit Task 4

---

Task 4: Externe Schnittstellen

Aufgaben

• 4.1 Alle Schnittstellen aus Task 2 detailliert dokumentieren
• 4.2 Pro Schnittstelle: Endpunkt, Format, Auth, Operationen erfassen
• 4.3 Fehlerbehandlung dokumentieren (Retry, DLQ, Timeout)
• 4.4 docs/interfaces/external.md erstellen

Dokumentation pro Schnittstelle

Feld	Beschreibung
ID	IF-001, IF-002, ...
Name	Sprechender Name
Typ	HTTP/JMS/JDBC/FTP/SMTP
Richtung	IN/OUT/BIDI
Endpunkt	URL/Queue/Tabelle/Pfad
Format	XML/JSON/CSV
Auth	Basic/OAuth/Cert
Fehlerbehandlung	Retry, Timeout, DLQ

Nach Abschluss: Status auf , weiter mit Task 5

---

Task 5: Datenmodell

Aufgaben

• 5.1 Domänenobjekte identifizieren (Entities, Value Objects, DTOs)
• 5.2 Nach Domänenbereichen gruppieren
• 5.3 Beziehungen analysieren (Assoziation, Aggregation, Vererbung)
• 5.4 docs/domain/data_model.md erstellen (mit eingebetteten Mermaid-Diagrammen)

Quellen

• Java/C# Klassen
• XML/XSD Schemata
• WSDL Types
• DB-Tabellen/Views
• JSON Schemas

Mermaid-Template: Datenmodell (Klassendiagramm)

classDiagram
    class Entity {
        <<Entity>>
        +String id
        +String name
    }

    class ValueObject {
        <<ValueObject>>
        +Type field
    }

    Entity "1" *-- "*" ValueObject

    note for Entity "Quelle: path/to/file"

Mermaid-Template: Entity-Relationship-Diagramm

erDiagram
    ENTITY ||--o{ VALUE_OBJECT : enthält
    ENTITY {
        string id PK
        string name
    }
    VALUE_OBJECT {
        string field
    }

Nach Abschluss: Status auf , weiter mit Task 6

---

Task 6: Nicht-funktionale Anforderungen & Monitoring

Aufgaben

• 6.1 Performance-Configs suchen (Timeouts, Pools, Caching)
• 6.2 Resilienz-Configs suchen (Retry, Circuit Breaker, DLQ)
• 6.3 Sicherheits-Configs suchen (Auth, Verschlüsselung, Audit)
• 6.4 Observability-Configs suchen (Logging, Metriken, Health)
• 6.5 Monitoring & Alerting analysieren (siehe unten)
• 6.6 docs/nfr.md erstellen

Wichtig: Nur explizit konfigurierte NFRs dokumentieren!

Monitoring & Alerting

Hinweis: Dieser Bereich wird nur dokumentiert, wenn im Projekt tatsächlich Monitoring- oder Alerting-Konfigurationen vorhanden sind. Nicht alle Projekte haben dies implementiert — das ist ein valides Ergebnis und sollte als Lücke in docs/assumptionAndRisks.md festgehalten werden.

Suchmuster

Typ	Dateien/Patterns
Metriken	Prometheus-Configs, Micrometer, @Timed, @Counted, Custom Metrics
Health Checks	/actuator/health, Liveness/Readiness Probes, Health-Endpoints
Alerting	Alert-Rules, Grafana-Dashboards, PagerDuty/OpsGenie-Configs
Logging	Log-Level-Configs, Structured Logging, ELK/Splunk-Configs
Tracing	OpenTelemetry, Jaeger, Zipkin, Correlation-IDs

Dokumentation (falls vorhanden)

Feld	Beschreibung
Metriken	Welche Metriken werden exponiert?
Dashboards	Gibt es vorkonfigurierte Dashboards?
Alerts	Welche Alert-Regeln sind definiert?
Health Checks	Welche Health-Endpoints existieren?
Log-Strategie	Structured Logging, Log-Level, Ziel-System

Nach Abschluss: Status auf , weiter mit Task 7

---

Task 7: Abschluss & Konsolidierung

Aufgaben

• 7.1 docs/assumptionAndRisks.md aktualisieren mit Erkenntnissen aus allen Tasks
• 7.2 Alle <!-- TODO: --> aus Dokumenten sammeln
• 7.3 Querverweise zwischen Dokumenten prüfen
• 7.4 docs/index.md finalisieren
• 7.5 Gesamtdokumentation auf Vollständigkeit prüfen

Checkliste für Annahmen/Risiken

Task	Typische Themen
1	Unklare Modulzwecke, veraltete Abhängigkeiten
2	Unbekannte externe Systeme
3	Fehlende Fehlerbehandlung, unklare Regeln
4	Fehlende Auth-Doku, unklare SLAs
5	Inkonsistente Schemata
6	Implizite Annahmen

Nach Abschluss: Alle Status auf , Dokumentation fertig!

---

Globale Regeln

Diagramme

Alle Diagramme MÜSSEN als Mermaid-Diagramme erstellt werden. PlantUML ist NICHT erlaubt. Diagramme werden direkt in die jeweiligen Markdown-Dokumente eingebettet keine separaten Diagramm-Dateien.

Empfohlene Mermaid-Diagrammtypen:

Zweck	Mermaid-Typ	Syntax
Architekturübersicht	Flowchart	graph TB / graph LR
Komponentenbeziehungen	Klassendiagramm	classDiagram
Prozessflüsse	Flowchart	flowchart TD
Nachrichtenflüsse	Sequenzdiagramm	sequenceDiagram
Datenmodell	Klassendiagramm / ER	classDiagram / erDiagram
Zustandsübergänge	State-Diagramm	stateDiagram-v2

Quellenverweise

Jede Aussage mit Dateipfad belegen: [Quelle: path/to/file:zeile]

Unklarheiten

Mit <!-- TODO: Beschreibung --> markieren

---

Offene Fragen

ID	Task	Frage	Priorität