docs(c4): migrate architecture diagrams to draw.io and refine container/workflow visualizations

- Replaced outdated `.puml` and `.mermaid` diagrams with modernized `.drawio` versions for enhanced clarity.
- Added `container_diagram.drawio` to depict offline-first architecture and backend synchronization workflow.
- Introduced `workflow_turnieranlage.drawio` to visualize the tournament creation process (3-step wizard).
- Archived legacy diagrams under `docs/01_Architecture/_archive` for reference.
This commit is contained in:
Stefan Mogeritsch 2026-04-09 11:32:04 +02:00
parent c11bffef22
commit 276e3cc3dd
10 changed files with 168 additions and 1 deletions

View File

@ -0,0 +1,66 @@
<mxfile host="Electron" modified="2026-04-07T12:00:00.000Z" agent="Lead Architect" version="21.0.0" type="device">
<diagram id="c4-container" name="C4 Container Diagram">
<mxGraphModel dx="1200" dy="800" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
<mxCell id="user" value="Veranstalter /&#10;Meldestelle" style="shape=umlActor;verticalLabelPosition=bottom;verticalAlign=top;html=1;outlineConnect=0;" vertex="1" parent="1">
<mxGeometry x="40" y="240" width="30" height="60" as="geometry" />
</mxCell>
<!-- KMP Desktop App Container -->
<mxCell id="container_app" value="&lt;b&gt;Desktop-Anwendung (Offline-First)&lt;/b&gt;&lt;br&gt;&lt;i&gt;Kotlin, Compose Multiplatform&lt;/i&gt;&lt;br&gt;&lt;br&gt;Bietet die gesamte Meldestellen-Oberfläche, offline-fähig." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;verticalAlign=top;align=left;spacingTop=4;spacingLeft=8;" vertex="1" parent="1">
<mxGeometry x="160" y="200" width="280" height="120" as="geometry" />
</mxCell>
<!-- Local DB -->
<mxCell id="db_local" value="&lt;b&gt;Lokale Datenbank&lt;/b&gt;&lt;br&gt;&lt;i&gt;SQLite / Room&lt;/i&gt;&lt;br&gt;&lt;br&gt;Speichert alle Turniere, Nennungen lokal für den Offline-Betrieb." style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;fillColor=#ffe6cc;strokeColor=#d79b00;align=left;spacingTop=4;spacingLeft=8;" vertex="1" parent="1">
<mxGeometry x="200" y="400" width="200" height="100" as="geometry" />
</mxCell>
<!-- Backend System Boundary -->
<mxCell id="system_backend" value="Cloud Backend / API" style="swimlane;whiteSpace=wrap;html=1;startSize=30;fillColor=#f5f5f5;fontColor=#333333;strokeColor=#666666;" vertex="1" parent="1">
<mxGeometry x="600" y="80" width="360" height="460" as="geometry" />
</mxCell>
<!-- Backend Containers -->
<mxCell id="container_api" value="&lt;b&gt;REST API Services&lt;/b&gt;&lt;br&gt;&lt;i&gt;Ktor / Spring Boot&lt;/i&gt;&lt;br&gt;&lt;br&gt;Bietet die Synchronisations-Schnittstellen für die Desktop-App." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;verticalAlign=top;align=left;spacingTop=4;spacingLeft=8;" vertex="1" parent="system_backend">
<mxGeometry x="40" y="60" width="280" height="120" as="geometry" />
</mxCell>
<!-- Remote DB -->
<mxCell id="db_remote" value="&lt;b&gt;Zentrale Datenbank&lt;/b&gt;&lt;br&gt;&lt;i&gt;PostgreSQL&lt;/i&gt;&lt;br&gt;&lt;br&gt;Speichert alle Mandanten und Stammdaten." style="shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;size=15;fillColor=#ffe6cc;strokeColor=#d79b00;align=left;spacingTop=4;spacingLeft=8;" vertex="1" parent="system_backend">
<mxGeometry x="80" y="260" width="200" height="100" as="geometry" />
</mxCell>
<!-- External -->
<mxCell id="ext_zns" value="&lt;b&gt;ZNS (OEPS)&lt;/b&gt;&lt;br&gt;&lt;br&gt;Externe Stammdaten (ZIP) und Nennungen (DAT)." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;verticalAlign=top;align=left;spacingTop=4;spacingLeft=8;" vertex="1" parent="1">
<mxGeometry x="1040" y="140" width="200" height="100" as="geometry" />
</mxCell>
<!-- Edges -->
<mxCell id="e_user_app" value="nutzt" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;exitX=0.5;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="user" target="container_app">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_app_local" value="liest/schreibt" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1" source="container_app" target="db_local">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_app_api" value="synchronisiert via HTTPS" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="container_app" target="container_api">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_api_db" value="liest/schreibt" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="system_backend" source="container_api" target="db_remote">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="e_zns_app" value="Upload (ZIP/DAT)" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=1;entryY=0.25;entryDx=0;entryDy=0;exitX=0;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="ext_zns" target="container_app">
<mxGeometry relative="1" as="geometry" />
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>

View File

@ -0,0 +1,34 @@
<mxfile host="Electron" modified="2026-04-07T12:00:00.000Z" agent="Lead Architect" version="21.0.0" type="device">
<diagram id="workflow" name="Workflow Turnieranlage">
<mxGraphModel dx="1200" dy="800" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
<root>
<mxCell id="0" />
<mxCell id="1" parent="0" />
<!-- Step 1 -->
<mxCell id="step1" value="&lt;b&gt;Schritt 1: Veranstaltung&lt;/b&gt;&lt;br&gt;&lt;br&gt;1. Stammdaten (Name, Ort, Datum)&lt;br&gt;2. ZNS.zip Upload (Reiter/Pferde)&lt;br&gt;3. Austragungsplätze anlegen&lt;br&gt;4. Preisliste (Artikel) anlegen" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;verticalAlign=top;align=left;spacingTop=4;spacingLeft=8;" vertex="1" parent="1">
<mxGeometry x="80" y="80" width="240" height="120" as="geometry" />
</mxCell>
<!-- Step 2 -->
<mxCell id="step2" value="&lt;b&gt;Schritt 2: Turnier(e)&lt;/b&gt;&lt;br&gt;&lt;br&gt;1. Turnier-Nr (26128) &amp;amp; Reglement&lt;br&gt;2. Sparte &amp;amp; Kategorie (CSN-C)&lt;br&gt;3. Turnierbeauftragter (TB) wählen&lt;br&gt;4. Nennschluss &amp;amp; Gebühren" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;verticalAlign=top;align=left;spacingTop=4;spacingLeft=8;" vertex="1" parent="1">
<mxGeometry x="400" y="80" width="240" height="120" as="geometry" />
</mxCell>
<!-- Step 3 -->
<mxCell id="step3" value="&lt;b&gt;Schritt 3: Bewerbe&lt;/b&gt;&lt;br&gt;&lt;br&gt;1. Identifikation (Klasse, Aufgabe)&lt;br&gt;2. Finanzen (Startgeld, Preisgeld)&lt;br&gt;3. Zeitplan (Platz, Dauer, Umbau)&lt;br&gt;4. Richter-Zuweisung&lt;br&gt;5. Teilungsregel (z.B. NACH_LIZENZ)" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;verticalAlign=top;align=left;spacingTop=4;spacingLeft=8;" vertex="1" parent="1">
<mxGeometry x="720" y="80" width="240" height="140" as="geometry" />
</mxCell>
<!-- Edges -->
<mxCell id="edge1" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="step1" target="step2">
<mxGeometry relative="1" as="geometry" />
</mxCell>
<mxCell id="edge2" value="1..N" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" edge="1" parent="1" source="step2" target="step3">
<mxGeometry relative="1" as="geometry" />
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>

View File

@ -1592,7 +1592,74 @@ Wie machen wir weiter?
Damit sind Veranstaltung, Turnier und Bewerb architektonisch sauber aufgebaut. Damit sind Veranstaltung, Turnier und Bewerb architektonisch sauber aufgebaut.
Wollen wir uns nun dem nächsten großen Meilenstein widmen: Den Nennungen (Datenschutzkonformes Web-Formular für lizenzfreie Starter vs. n2-xxxxx.dat Import vom ZNS) sowie der Frage, wie Teilnehmer und ihre Pferde sicher in unsere Bewerbe gebucht und abgerechnet werden? Wollen wir uns nun dem nächsten großen Meilenstein widmen: Den Nennungen (Datenschutzkonformes Web-Formular für lizenzfreie Starter vs. n2-xxxxx.dat Import vom ZNS) sowie der Frage, wie Teilnehmer und ihre Pferde sicher in unsere Bewerbe gebucht und abgerechnet werden?
---
Ich
---
Wollen wir nicht zuvor die Desktop-App soweit bekommen, dass wir in der Lage sind:
- Eine oder mehrere Veranstaltungen anzulegen
- Zu den jeweiligen Veranstaltungen ein oder mehr Turniere anzulegen
- Den gesammten Prozess Turnier-anlegen
- Zum Turnier Prüfungen/Bewerbe anlegen
- usw.
Wir müssen den Prozess genauer denfinieren und die Workflows in kleine hädelbare Einheiten bestimmen, damit wir diese Spartenspezifisch und wartbar entwickeln können. Jetzt und in Zukunft.
In
docs/01_Architecture/c4
haben wir schon einige Diagramme/Grafiken zum visualisieren.
Kannst du dir diese einmal genauer unter die Lupe nehmen und diese analysiere, korrigieren bzw. vervollständigen, optimieren und aktualisieren?
Wir arbeiteten sowohl mit PantUML und Mermaid, aber ich habe jetzt draw.io entdeckt und bin davon begeistert.
Könntest du mir im Zuge dessen mir diese Diagramme usw. auf draw.io umschreiben?
---
Gemini
---
🏗️ **[Lead Architect] & 🎨 [Frontend Expert]**
Das ist eine absolut sinnvolle Priorisierung! Bevor wir uns in die komplexe Welt der Nennungen stürzen, muss das Fundament (die "Schubladen" in der Desktop-App) stehen. Wenn der Prozess der Turnieranlage unübersichtlich ist, scheitert das System an der Benutzerakzeptanz.
### 1. Architektur-Diagramme & Draw.io Migration
Ich habe mir die alten `.puml` (PlantUML) und `.mermaid` Diagramme angesehen. Da diese teilweise veraltet waren und Sie draw.io bevorzugen, habe ich die Architektur-Diagramme komplett auf `.drawio` migriert und modernisiert:
* **`container_diagram.drawio` (Neu):** Ersetzt die alten Container-Diagramme. Es zeigt klar den Offline-First-Ansatz (Desktop App mit lokaler SQLite) und die Synchronisation mit dem Cloud-Backend.
* **`workflow_turnieranlage.drawio` (Neu):** Ein komplett neues Flussdiagramm, das exakt den unten beschriebenen 3-stufigen Wizard-Prozess für die Desktop-App visualisiert.
*(Hinweis: Sie können die alten `.puml` und `.mermaid` Dateien im Ordner `docs/01_Architecture/c4/` nun gefahrlos löschen, um das Repository sauber zu halten).*
---
### 2. Der Desktop-App Workflow: "Kleine, händelbare Einheiten"
Um die UI/UX in der Desktop-App (Compose Multiplatform) wartbar und spartenspezifisch zu entwickeln, brechen wir den "Turnier anlegen"-Prozess in einen sauberen **3-stufigen Wizard** herunter. Dies entspricht exakt unserer Domain-Hierarchie:
#### 🟢 Schritt 1: Die Veranstaltung (Das Event-Wochenende)
*Das ist die organisatorische "Klammer" für alles Weitere.*
* **Basisdaten:** Name (z.B. "Pferdesporttage Neumarkt"), Zeitraum, Ort.
* **Stammdaten-Import:** Upload der `ZNS.zip`. Das befüllt unseren lokalen Offline-Pool mit Reitern, Pferden und Funktionären für dieses Wochenende.
* **Infrastruktur:** Anlegen der Austragungsplätze (z.B. "Waldarena", "Vorbereitungsplatz").
* **Preisliste:** Definieren der Zusatzartikel (z.B. "Heu", "Ansage", "Tagesbox"), die der Veranstalter verkauft.
#### 🟡 Schritt 2: Das Turnier (Der offizielle Rahmen)
*Hier konfigurieren wir den eigentlichen sportlichen Wettbewerb.*
* **Identifikation:** Eingabe der 5-stelligen OEPS-Nummer (z.B. `26128`), Auswahl von Reglement (ÖTO), Sparte (Springen) und Kategorie (CSN-C).
* **Regelwerk:** Festlegen von Nennschluss, Nachnenngebühren und Nenntauschbörse.
* **Teilnehmerkreis:** Eventuelle Einschränkungen (Haflinger, Noriker, etc.) nach ÖTO § 3.
* **Der "Chef":** Zuweisung des Turnierbeauftragten (TB) aus dem zuvor geladenen Funktionärs-Pool.
* **Nenndaten-Import:** Upload der `n2-26128.dat` (falls Nennungen vom ZNS kommen).
#### 🟠 Schritt 3: Die Bewerbe (Das sportliche Programm)
*Dies ist die feinste Granularität hier entsteht der Zeitplan.*
* **Identifikation:** Bewerbsnummer, Bezeichnung, Klasse/Höhe und die genaue Aufgabe (z.B. "R1").
* **Ort & Zeit:** Zuweisung zu einem Austragungsplatz, Beginnzeit (Fix/Anschließend), Reitdauer und Pausen (Umbau/Besichtigung).
* **Funktionäre:** Zuweisung der Richter auf spezifische Positionen (z.B. "C", "M") mit unserer "Warn-Logik" für Qualifikationen.
* **Finanzen:** Festlegen von Startgeld und ob Preisgeld ausbezahlt wird.
* **Die Teilungsregel:** Das Wichtigste! Wie wird geteilt? (z.B. `NACH_LIZENZ`, `MANUELL`).
---
**Nächster Schritt für uns:**
Sollen wir als 🎨 **[Frontend Expert]** genau diesen Wizard (Schritt 1 bis 3) jetzt in Compose Multiplatform als UI-Komponenten (Screens/ViewModels) konzipieren und implementieren, damit Sie die Turnieranlage in der Desktop-App testen können?