arc42 Sektion 8: Querschnittliche Konzepte schreiben
Zweck
Übergreifende, generelle Prinzipien und Lösungsansätze, die in vielen Teilen der Architektur einheitlich benutzt werden (→ cross-cutting). Konzepte bilden die Basis für konzeptionelle Integrität (Konsistenz, Homogenität) der Architektur.
Dies ist eine der Kernsektionen der arc42-Dokumentation.
Typische Themengebiete:
- Domänenmodell
- Persistenz/Datenzugriff
- Benutzeroberfläche/UX
- Geschäftsregeln/Validierung
- Fehlerbehandlung
- Logging/Monitoring
- Sicherheit/Autorisierung
- Kommunikation/Integration
- Testbarkeit
- Build/Deployment
- Konfigurationsmanagement
Dateistruktur
08-Konzepte/
├── 08-01-Domaenenmodell.md
├── 08-02-Persistenz.md
├── 08-03-Fehlerbehandlung.md
├── 08-04-Logging.md
├── 08-05-Sicherheit.md
├── 08-06-Testbarkeit.md
└── 08-XX-<Weiteres-Konzept>.md
Ein File pro Konzept. Nur die relevanten Konzepte erstellen — nicht alle möglichen Themen abdecken!
Interaktive Fragen an den User
- Gibt es ein Domänenmodell? Welche Kernentitäten und deren Beziehungen gibt es?
- Wie wird Persistenz gehandhabt? (ORM, Repository-Pattern, Event-Sourcing etc.)
- Wie werden Fehler behandelt? (Globaler Error-Handler, Error-Codes, Retry-Strategien)
- Wie wird geloggt/gemonitort? (Log-Framework, Log-Level-Strategie, Monitoring-Stack)
- Wie ist die Sicherheit umgesetzt? (Authentifizierung, Autorisierung, Verschlüsselung)
- Wie wird getestet? (Test-Pyramide, Test-Strategien, Mocking-Ansatz)
- Gibt es ein einheitliches UI/UX-Konzept?
- Welche übergreifenden Architekturmuster werden verwendet? (z.B. CQRS, Event-Sourcing, Saga-Pattern)
Codebase-Analyse-Hinweise
- Domänenmodell: Aus Entity-Klassen, Domain-Packages, @Entity/@Document-Annotationen
- Persistenz: Aus Repository-Interfaces, ORM-Konfigurationen, Migration-Scripts
- Fehlerbehandlung: Aus GlobalExceptionHandler, ErrorController, error-handling-Middleware
- Logging: Aus logback.xml, log4j2.xml, Winston/Pino-Konfiguration, Logging-Interceptors
- Sicherheit: Aus SecurityConfig, JWT-Filter, RBAC-Policies, CORS-Konfiguration
- Testbarkeit: Aus Test-Verzeichnisstruktur, Testcontainers, Mock-Konfigurationen
- Patterns: Aus Code-Strukturen (Strategy-Pattern, Factory, Observer etc.)
Templates
08-XX-Konzept.md (Generisches Template)
# <Konzeptname>
## Problemstellung
<Welches übergreifende Problem löst dieses Konzept?>
## Lösung
<Wie wird das Problem gelöst? Welcher Ansatz/welches Pattern wird verwendet?>
## Umsetzung
<Konkrete Umsetzungsdetails, ggf. mit Code-Beispielen>
```<sprache>
// Beispielcode (optional)
Geltungsbereich
<Für welche Bausteine/Teile des Systems gilt dieses Konzept?>
Alternativen
<Welche Alternativen wurden betrachtet? Warum wurde dieser Ansatz gewählt?>
### 08-01-Domaenenmodell.md (Spezifisches Template)
```markdown
# Domänenmodell
## Übersicht
```mermaid
classDiagram
class Entity1 {
+id: UUID
+name: String
}
class Entity2 {
+id: UUID
}
Entity1 "1" --> "*" Entity2
Kernentitäten
| Entität |
Beschreibung |
Wichtige Attribute |
| <Entity 1> |
|
|
| <Entity 2> |
|
|
Beziehungen
- <Entity 1> hat viele <Entity 2>
- <Entity 3> gehört zu <Entity 1>
Invarianten/Geschäftsregeln
- <Regel 1: z.B. "Eine Bestellung muss mindestens eine Position enthalten">
- <Regel 2>
## Best Practices (aus arc42-Tipps)
- **Nur relevante Konzepte**: Nicht alle möglichen Themen abdecken, nur die systemrelevanten
- **HOW erklären**: Konzepte erklären WIE etwas funktioniert, nicht nur WAS
- **Code-Beispiele**: Technische Konzepte mit konkretem Code illustrieren
- **Domänenmodell ist oft das wichtigste Konzept**: Mindestens das Datenmodell dokumentieren
- **Abgrenzung zu Entscheidungen (S9)**: Konzepte beschreiben HOW (Umsetzung), Entscheidungen beschreiben WHAT/WHY (Entscheidungsgrund)
- **Querverlinkung zu Bausteinen**: Welche Bausteine verwenden welches Konzept?
- **Checkliste nutzen**: arc42 bietet eine Themen-Checkliste als Inspiration
## Querverweise
- ← **Sektion 5** (Bausteinsicht): Konzepte erklären gemeinsame Muster der Bausteine
- ← **Sektion 4** (Lösungsstrategie): Konzepte detaillieren die Strategieansätze
- ↔ **Sektion 9** (Entscheidungen): Klare Abgrenzung: Konzept = HOW, Entscheidung = WHAT+WHY
- → **Sektion 12** (Glossar): Domänenbegriffe aus dem Domänenmodell ins Glossar aufnehmen
1---2name: arc42-write-s08-concepts3description: Schreibt arc42 Sektion 8 (Querschnittliche Konzepte): Übergreifende Lösungsansätze, Muster, Regeln, Domänenmodelle, technische Konzepte. Use when: Sektion 8 schreiben, Konzepte, Crosscutting Concepts, Querschnitt, Muster, Domänenmodell, Logging, Security, Fehlerbehandlung dokumentieren.4---5
6# arc42 Sektion 8: Querschnittliche Konzepte schreiben
7
8## Zweck
9
10Übergreifende, generelle Prinzipien und Lösungsansätze, die in vielen Teilen der Architektur einheitlich benutzt werden (→ cross-cutting). Konzepte bilden die Basis für konzeptionelle Integrität (Konsistenz, Homogenität) der Architektur.
11
12**Dies ist eine der Kernsektionen der arc42-Dokumentation.**
13
14Typische Themengebiete:
15- Domänenmodell
16- Persistenz/Datenzugriff
17- Benutzeroberfläche/UX
18- Geschäftsregeln/Validierung
19- Fehlerbehandlung
20- Logging/Monitoring
21- Sicherheit/Autorisierung
22- Kommunikation/Integration
23- Testbarkeit
24- Build/Deployment
25- Konfigurationsmanagement
26
27## Dateistruktur
28
29```
3008-Konzepte/
31├── 08-01-Domaenenmodell.md
32├── 08-02-Persistenz.md
33├── 08-03-Fehlerbehandlung.md
34├── 08-04-Logging.md
35├── 08-05-Sicherheit.md
36├── 08-06-Testbarkeit.md
37└── 08-XX-<Weiteres-Konzept>.md
38```
39
40Ein File pro Konzept. Nur die relevanten Konzepte erstellen — nicht alle möglichen Themen abdecken!
41
42## Interaktive Fragen an den User
43
441. **Gibt es ein Domänenmodell?** Welche Kernentitäten und deren Beziehungen gibt es?
452. **Wie wird Persistenz gehandhabt?** (ORM, Repository-Pattern, Event-Sourcing etc.)
463. **Wie werden Fehler behandelt?** (Globaler Error-Handler, Error-Codes, Retry-Strategien)
474. **Wie wird geloggt/gemonitort?** (Log-Framework, Log-Level-Strategie, Monitoring-Stack)
485. **Wie ist die Sicherheit umgesetzt?** (Authentifizierung, Autorisierung, Verschlüsselung)
496. **Wie wird getestet?** (Test-Pyramide, Test-Strategien, Mocking-Ansatz)
507. **Gibt es ein einheitliches UI/UX-Konzept?**
518. **Welche übergreifenden Architekturmuster werden verwendet?** (z.B. CQRS, Event-Sourcing, Saga-Pattern)
52
53## Codebase-Analyse-Hinweise
54
55- **Domänenmodell**: Aus Entity-Klassen, Domain-Packages, @Entity/@Document-Annotationen
56- **Persistenz**: Aus Repository-Interfaces, ORM-Konfigurationen, Migration-Scripts
57- **Fehlerbehandlung**: Aus GlobalExceptionHandler, ErrorController, error-handling-Middleware
58- **Logging**: Aus logback.xml, log4j2.xml, Winston/Pino-Konfiguration, Logging-Interceptors
59- **Sicherheit**: Aus SecurityConfig, JWT-Filter, RBAC-Policies, CORS-Konfiguration
60- **Testbarkeit**: Aus Test-Verzeichnisstruktur, Testcontainers, Mock-Konfigurationen
61- **Patterns**: Aus Code-Strukturen (Strategy-Pattern, Factory, Observer etc.)
62
63## Templates
64
65### 08-XX-Konzept.md (Generisches Template)
66
67```markdown
68# <Konzeptname>
69
70## Problemstellung
71
72<Welches übergreifende Problem löst dieses Konzept?>
73
74## Lösung
75
76<Wie wird das Problem gelöst? Welcher Ansatz/welches Pattern wird verwendet?>
77
78## Umsetzung
79
80<Konkrete Umsetzungsdetails, ggf. mit Code-Beispielen>
81
82```<sprache>
83// Beispielcode (optional)
84```
85
86## Geltungsbereich
87
88<Für welche Bausteine/Teile des Systems gilt dieses Konzept?>
89
90## Alternativen
91
92<Welche Alternativen wurden betrachtet? Warum wurde dieser Ansatz gewählt?>
93```
94
95### 08-01-Domaenenmodell.md (Spezifisches Template)
96
97```markdown
98# Domänenmodell
99
100## Übersicht
101
102```mermaid
103classDiagram
104 class Entity1 {
105 +id: UUID
106 +name: String
107 }
108 class Entity2 {
109 +id: UUID
110 }
111 Entity1 "1" --> "*" Entity2
112```
113
114## Kernentitäten
115
116| Entität | Beschreibung | Wichtige Attribute |
117|---------|-------------|-------------------|
118| <Entity 1> | <Beschreibung> | <Attribute> |
119| <Entity 2> | <Beschreibung> | <Attribute> |
120
121## Beziehungen
122
123- <Entity 1> hat viele <Entity 2>
124- <Entity 3> gehört zu <Entity 1>
125
126## Invarianten/Geschäftsregeln
127
128- <Regel 1: z.B. "Eine Bestellung muss mindestens eine Position enthalten">
129- <Regel 2>
130```
131
132## Best Practices (aus arc42-Tipps)
133
134- **Nur relevante Konzepte**: Nicht alle möglichen Themen abdecken, nur die systemrelevanten
135- **HOW erklären**: Konzepte erklären WIE etwas funktioniert, nicht nur WAS
136- **Code-Beispiele**: Technische Konzepte mit konkretem Code illustrieren
137- **Domänenmodell ist oft das wichtigste Konzept**: Mindestens das Datenmodell dokumentieren
138- **Abgrenzung zu Entscheidungen (S9)**: Konzepte beschreiben HOW (Umsetzung), Entscheidungen beschreiben WHAT/WHY (Entscheidungsgrund)
139- **Querverlinkung zu Bausteinen**: Welche Bausteine verwenden welches Konzept?
140- **Checkliste nutzen**: arc42 bietet eine Themen-Checkliste als Inspiration
141
142## Querverweise
143
144- ← **Sektion 5** (Bausteinsicht): Konzepte erklären gemeinsame Muster der Bausteine
145- ← **Sektion 4** (Lösungsstrategie): Konzepte detaillieren die Strategieansätze
146- ↔ **Sektion 9** (Entscheidungen): Klare Abgrenzung: Konzept = HOW, Entscheidung = WHAT+WHY
147- → **Sektion 12** (Glossar): Domänenbegriffe aus dem Domänenmodell ins Glossar aufnehmen
aibot88