arc42-write-s05-building-blocks

name	arc42-write-s05-building-blocks
description	Schreibt arc42 Sektion 5 (Bausteinsicht): Statische Zerlegung, Blackbox/Whitebox-Beschreibungen, Hierarchieebenen, Schnittstellen. Use when: Sektion 5 schreiben, Bausteinsicht, Building Block View, Blackbox, Whitebox, Komponentenzerlegung, Module dokumentieren.

arc42 Sektion 5: Bausteinsicht schreiben

Zweck

Die Bausteinsicht zeigt die statische Zerlegung des Systems in Bausteine (Module, Komponenten, Subsysteme, Klassen, Packages, Libraries, Frameworks) sowie deren Abhängigkeiten.

Dies ist eine Pflichtsektion und eine der Kernsektionen der arc42-Dokumentation.

Die Bausteinsicht ist hierarchisch aufgebaut:

• Ebene 1: Whitebox des Gesamtsystems (Zerlegung in Blackboxes)
• Ebene 2: Whitebox einzelner Bausteine aus Ebene 1
• Ebene 3+: Weitere Verfeinerung bei Bedarf

Dateistruktur

05-Bausteinsicht/
├── 05-01-Ebene-1.md
├── 05-02-Ebene-2-<Baustein-A>.md (optional)
├── 05-03-Ebene-2-<Baustein-B>.md (optional)
└── 05-0X-Ebene-3-<Detail>.md (selten nötig)

Interaktive Fragen an den User

Für Ebene 1 (Whitebox Gesamtsystem)

1. Aus welchen Hauptbausteinen besteht das System? (Top-Level-Module/Komponenten/Services)
2. Was ist die Verantwortlichkeit jedes Bausteins? (Ein Satz pro Baustein)
3. Welche Abhängigkeiten bestehen zwischen den Bausteinen?
4. Gibt es eine Zerlegungsmotivation? (Warum genau diese Aufteilung?)
5. Welche wichtigen Schnittstellen gibt es zwischen Bausteinen?

Für Ebene 2 (bei Bedarf)

1. Welche Bausteine aus Ebene 1 sind komplex genug für eine Verfeinerung?
2. Wie sind diese intern aufgebaut? (Submodule, Klassen, Layer)
3. Gibt es überraschende oder risikobehaftete innere Strukturen?

Codebase-Analyse-Hinweise

• Ebene 1: Aus Top-Level-Packages, Gradle/Maven-Module, Monorepo-Packages, Service-Verzeichnisse
• Verantwortlichkeiten: Aus Package-Namen, README-Dateien in Modulen, Hauptklassen
• Abhängigkeiten: Aus Import-Statements, Module-Dependencies, API-Aufrufe zwischen Services
• Schnittstellen: Aus öffentlichen Interfaces, API-Definitionen, Shared-DTOs
• Ebene 2: Aus Sub-Packages innerhalb der Top-Level-Module

Templates

05-01-Ebene-1.md

# Bausteinsicht — Ebene 1

## Whitebox Gesamtsystem

### Übersichtsdiagramm

<!-- Zeigt die Zerlegung des Gesamtsystems in seine Hauptbausteine -->

```mermaid
graph TB
    subgraph System
        A[Baustein A]
        B[Baustein B]
        C[Baustein C]
    end
    A --> B
    B --> C
    EXT1[Externes System] --> A
    C --> EXT2[Datenbank]

Motivation

<Warum wurde das System genau so zerlegt? Welches Prinzip liegt zugrunde?>

Enthaltene Bausteine

Baustein	Verantwortlichkeit	Schnittstellen
	<1-2 Sätze: Was macht dieser Baustein?>

Baustein A (Blackbox)

Zweck/Verantwortlichkeit: <Was macht dieser Baustein?>

Schnittstellen:

• <Interface 1>:
• <Interface 2>:

Code-Location: <Pfad im Repository>

### 05-02-Ebene-2.md (Template)

```markdown
# Bausteinsicht — Ebene 2: <Bausteinname>

## Whitebox <Bausteinname>

### Übersichtsdiagramm

```mermaid
graph TB
    subgraph Baustein
        S1[Sub-Baustein 1]
        S2[Sub-Baustein 2]
        S3[Sub-Baustein 3]
    end

Motivation

<Warum wurde dieser Baustein so zerlegt?>

Enthaltene Bausteine

Sub-Baustein	Verantwortlichkeit
<Sub 1>
<Sub 2>

## Best Practices (aus arc42-Tipps)

- **Ebene 1 ist Pflicht**: Immer mindestens die Top-Level-Zerlegung dokumentieren
- **Hierarchisch aufbauen**: Blackboxes in Ebene N werden in Ebene N+1 als Whitebox verfeinert
- **Konsistenz mit Kontext**: Externe Schnittstellen aus Sektion 3 müssen in Ebene 1 auftauchen
- **Verantwortlichkeit pro Blackbox**: Jeder Baustein braucht eine klare Verantwortlichkeitsbeschreibung
- **Inneres verbergen**: Blackboxes zeigen nur die Außensicht, keine internen Details
- **Tabellen für Effizienz**: Bustistein-Tabellen sind kompakter als Fließtext
- **Motivation bei Whitebox**: Jede Whitebox-Zerlegung braucht eine Begründung
- **Nur wenige Bausteine verfeinern**: Nicht alles auf Ebene 2+ verfeinern, nur das Wichtige/Risikobehaftete
- **Quellcode-Mapping**: Erklären, wo im Repository die Bausteine zu finden sind
- **Kohäsion als Treiber**: Bausteine sollten nach Kohäsion geschnitten sein

## Querverweise

- ← **Sektion 3** (Kontextabgrenzung): Externe Schnittstellen müssen konsistent sein
- → **Sektion 6** (Laufzeitsicht): Szenarien verwenden die Bausteine aus dieser Sicht
- → **Sektion 7** (Verteilungssicht): Mapping der Bausteine auf Infrastruktur
- → **Sektion 8** (Konzepte): Querschnittliche Konzepte erklären gemeinsame Muster der Bausteine