Review Software Architecture

Softwarearchitektur reviewen

Softwarearchitektur auf Systemebene hinsichtlich Qualitaetsattribute, Einhaltung von Designprinzipien und langfristiger Wartbarkeit bewerten.

Wann verwenden

• Bewertung einer vorgeschlagenen Architektur vor Beginn der Implementierung
• Einschaetzung eines bestehenden Systems auf Skalierbarkeit, Wartbarkeit oder Sicherheit
• Review von Architecture Decision Records (ADRs) fuer ein Projekt
• Durchfuehrung einer Technische-Schulden-Bestandsaufnahme
• Bewertung, ob ein System bereit fuer einen signifikanten Skalierungs- oder Funktionserweiterungsschritt ist
• Abgrenzung vom zeilenbasierten Code-Review (der sich auf Aenderungen auf PR-Ebene konzentriert)

Eingaben

• Erforderlich: System-Codebasis oder Architekturdokumentation (Diagramme, ADRs, README)
• Erforderlich: Kontext ueber Zweck, Groessenordnung und Einschraenkungen des Systems
• Optional: Nichtfunktionale Anforderungen (Latenz-, Durchsatz-, Verfuegbarkeitsziele)
• Optional: Teamgroesse und Kompetenzverteilung
• Optional: Technologische Einschraenkungen oder Praeferenzen
• Optional: Bekannte Schwachstellen oder Problembereiche

Vorgehensweise

Schritt 1: Systemkontext verstehen

Systemgrenzen und Schnittstellen erfassen:

## Systemkontext
- **Name**: [Systemname]
- **Zweck**: [Einzeilige Beschreibung]
- **Nutzer**: [Wer es nutzt und wie]
- **Groessenordnung**: [Anfragen/Sek., Datenvolumen, Nutzerzahl]
- **Alter**: [Jahre im Produktionsbetrieb, Hauptversionen]
- **Team**: [Groesse, Zusammensetzung]

## Externe Abhaengigkeiten
| Abhaengigkeit | Typ | Kritikalitaet | Anmerkungen |
|-----------|------|-------------|-------|
| PostgreSQL | Datenbank | Kritisch | Primaerer Datenspeicher |
| Redis | Cache | Hoch | Session-Speicher + Caching |
| Stripe | Externe API | Kritisch | Zahlungsabwicklung |
| S3 | Objektspeicher | Hoch | Datei-Uploads |

Erwartet: Klares Bild davon, was das System tut und wovon es abhaengt. Bei Fehler: Wenn die Architekturdokumentation fehlt, den Kontext aus Codestruktur, Konfigurationen und Deployment-Dateien ableiten.

Schritt 2: Strukturelle Qualitaet bewerten

Kopplungsbewertung

Untersuchen, wie stark Module voneinander abhaengen:

• Abhaengigkeitsrichtung: Fliessen Abhaengigkeiten in eine Richtung (geschichtet) oder sind sie zirkulaer?
• Schnittstellengrenzen: Sind Module ueber definierte Schnittstellen/Vertraege oder direkte Implementierungsreferenzen verbunden?
• Geteilter Zustand: Wird veraenderlicher Zustand zwischen Modulen geteilt?
• Datenbankkopplung: Lesen/schreiben mehrere Services direkt in dieselben Tabellen?
• Zeitliche Kopplung: Muessen Operationen in einer bestimmten Reihenfolge stattfinden ohne explizite Orchestrierung?

# Detect circular dependencies (JavaScript/TypeScript)
npx madge --circular src/

# Detect import patterns (Python)
# Look for deep cross-package imports
grep -r "from app\." --include="*.py" | sort | uniq -c | sort -rn | head -20

Kohaesionsbewertung

Bewerten, ob jedes Modul eine einzige, klare Verantwortung hat:

• Modulbenennung: Beschreibt der Name genau, was das Modul tut?
• Dateigroesse: Sind Dateien oder Klassen uebermaeßig gross (>500 Zeilen legt mehrere Verantwortlichkeiten nahe)?
• Aenderungshaeufigkeit: Erfordern nicht zusammenhaengende Features Aenderungen am selben Modul?
• God Objects: Gibt es Klassen/Module, von denen alles abhaengt?

Erwartet: Kopplung und Kohaesion mit spezifischen Beispielen aus der Codebasis bewertet. Bei Fehler: Wenn die Codebasis fuer ein manuelles Review zu gross ist, 3-5 Schluesselmodule und die am haeufigsten geaenderten Dateien stichprobenartig pruefen.

Schritt 3: SOLID-Prinzipien bewerten

## SOLID-Bewertung
| Prinzip | Status | Nachweis | Auswirkung |
|-----------|--------|----------|--------|
| SRP | Bedenken | UserService behandelt Auth, Profil, Benachrichtigungen und Abrechnung | Hoch — Aenderungen an der Abrechnung riskieren, Auth zu brechen |
| OCP | Gut | Plugin-System fuer Zahlungsanbieter | Niedrig |
| LSP | Gut | Keine Typ-Check-Anti-Patterns gefunden | Niedrig |
| ISP | Bedenken | IRepository hat 15 Methoden, die meisten Implementierungen nutzen 3-4 | Mittel |
| DIP | Bedenken | Controller instanziieren Datenbankrepositories direkt | Mittel |

Erwartet: Jedes Prinzip mit mindestens einem spezifischen Beispiel bewertet. Bei Fehler: Nicht alle Prinzipien gelten gleich fuer jeden Architekturstil. Vermerken, wenn ein Prinzip weniger relevant ist (z. B. ISP weniger wichtig in funktionalen Codebases).

Schritt 4: API-Design reviewen

Fuer Systeme, die APIs exponieren (REST, GraphQL, gRPC):

• Konsistenz: Namenskonventionen, Fehlerformate, Paginierungsmuster einheitlich
• Versionierung: Strategie vorhanden und angewendet (URL, Header, Content-Negotiation)
• Fehlerbehandlung: Fehlerantworten sind strukturiert, konsistent und lecken keine internen Details
• Authentifizierung/Autorisierung: Auf API-Ebene korrekt durchgesetzt
• Rate Limiting: Schutz vor Missbrauch
• Dokumentation: OpenAPI/Swagger, GraphQL-Schema oder Protobuf-Definitionen gepflegt
• Idempotenz: Mutierende Operationen (POST/PUT) behandeln Wiederholungsversuche sicher

## API-Design-Review
| Aspekt | Status | Anmerkungen |
|--------|--------|-------|
| Namenskonsistenz | Gut | Durchgaengige RESTful-Ressourcenbenennung |
| Versionierung | Bedenken | Keine Versionierungsstrategie — Breaking Changes betreffen alle Clients |
| Fehlerformat | Gut | RFC 7807 Problem Details konsistent verwendet |
| Auth | Gut | JWT mit rollenbasierten Scopes |
| Rate Limiting | Fehlend | Kein Rate Limiting an irgendeinem Endpunkt |
| Dokumentation | Bedenken | OpenAPI-Spec vorhanden, aber 6 Monate veraltet |

Erwartet: API-Design gegen gaengige Standards reviewed mit spezifischen Befunden. Bei Fehler: Wenn keine API exponiert wird, diesen Schritt ueberspringen und sich auf interne Modulschnittstellen konzentrieren.

Schritt 5: Skalierbarkeit und Zuverlaessigkeit bewerten

• Zustandslosigkeit: Kann die Applikation horizontal skalieren (kein lokaler Zustand)?
• Datenbankskalierbarkeit: Sind Abfragen indiziert? Ist das Schema fuer das Datenvolumen geeignet?
• Caching-Strategie: Wird Caching auf geeigneten Ebenen eingesetzt (Datenbank, Anwendung, CDN)?
• Fehlerbehandlung: Was passiert, wenn eine Abhaengigkeit nicht verfuegbar ist (Circuit Breaker, Retry, Fallback)?
• Observierbarkeit: Sind Logs, Metriken und Traces implementiert?
• Datenkonsistenz: Ist eventuelle Konsistenz akzeptabel oder ist starke Konsistenz erforderlich?

Erwartet: Skalierbarkeit und Zuverlaessigkeit relativ zu formulierten nichtfunktionalen Anforderungen bewertet. Bei Fehler: Wenn nichtfunktionale Anforderungen undokumentiert sind, deren Definition als ersten Schritt empfehlen.

Schritt 6: Technische Schulden bewerten

## Technische-Schulden-Inventar
| Punkt | Schweregrad | Auswirkung | Geschaetzter Aufwand | Empfehlung |
|------|----------|--------|-----------------|----------------|
| Keine Datenbankmigrationen | Hoch | Schaemaenderungen sind manuell und fehleranfaellig | 1 Sprint | Alembic/Flyway einfuehren |
| Monolithische Test-Suite | Mittel | Tests dauern 45 min, Entwickler ueberspringen sie | 2 Sprints | In Unit/Integration/E2E aufteilen |
| Hartcodierte Konfigurationswerte | Mittel | Umgebungsspezifische Werte im Quellcode | 1 Sprint | In Env-Variablen/Konfigurationsdienst auslagern |
| Keine CI/CD-Pipeline | Hoch | Manuelle Deployments fehleranfaellig | 1 Sprint | GitHub Actions einrichten |

Erwartet: Technische Schulden mit Schweregrad, Auswirkung und Aufwandsschaetzungen katalogisiert. Bei Fehler: Wenn das Schuldeninventar ueberwaetigend ist, die 5 wichtigsten Punkte nach Auswirkungs-/Aufwandsverhaeltnis priorisieren.

Schritt 7: Architecture Decision Records (ADRs) reviewen

Wenn ADRs vorhanden sind, beurteilen:

• Entscheidungen haben klaren Kontext (welches Problem geloest wurde)
• Alternativen wurden beruecksichtigt und dokumentiert
• Kompromisse sind explizit
• Entscheidungen sind noch aktuell (nicht ohne Dokumentation abgeloest)
• Neue wesentliche Entscheidungen haben ADRs

Wenn ADRs nicht vorhanden sind, deren Einfuehrung fuer Schluesselelentscheidungen empfehlen.

Schritt 8: Den Architektur-Review verfassen

## Architektur-Review-Bericht

### Zusammenfassung
[2-3 Saetze: Gesamtzustand, wesentliche Bedenken, empfohlene Massnahmen]

### Staerken
1. [Spezifische architektonische Staerke mit Nachweis]
2. ...

### Bedenken (nach Schweregrad)

#### Kritisch
1. **[Titel]**: [Beschreibung, Auswirkung, Empfehlung]

#### Wesentlich
1. **[Titel]**: [Beschreibung, Auswirkung, Empfehlung]

#### Geringfuegig
1. **[Titel]**: [Beschreibung, Empfehlung]

### Zusammenfassung technischer Schulden
[Top-5-Schulden mit priorisierten Empfehlungen]

### Empfohlene naechste Schritte
1. [Umsetzbare Empfehlung mit klarem Umfang]
2. ...

Erwartet: Review-Bericht ist umsetzbar mit priorisierten Empfehlungen. Bei Fehler: Wenn der Review zeitlich begrenzt ist, klar angeben, was abgedeckt wurde und was unbewertet bleibt.

Validierung

• Systemkontext dokumentiert (Zweck, Groessenordnung, Abhaengigkeiten, Team)
• Kopplung und Kohaesion mit spezifischen Codebeispielen bewertet
• SOLID-Prinzipien wo zutreffend ausgewertet
• API-Design reviewed (wenn zutreffend)
• Skalierbarkeit und Zuverlaessigkeit gegen Anforderungen bewertet
• Technische Schulden katalogisiert und priorisiert
• ADRs reviewed oder deren Fehlen vermerkt
• Empfehlungen sind spezifisch, priorisiert und umsetzbar

Haeufige Stolperfallen

• Code statt Architektur reviewen: Dieser Skill befasst sich mit systemweitem Design, nicht mit zeilenweiser Code-Qualitaet. code-reviewer fuer PR-Feedback verwenden.
• Spezifische Technologie vorschreiben: Architektur-Reviews sollten Probleme identifizieren, nicht bestimmte Tools vorschreiben, ausser es gibt einen klaren technischen Grund.
• Teamkontext ignorieren: Die "beste" Architektur fuer ein 3-koepfiges Team unterscheidet sich von der fuer ein 30-koepfiges Team. Organisatorische Einschraenkungen beruecksichtigen.
• Perfektionismus: Jedes System hat technische Schulden. Auf Schulden konzentrieren, die aktiv Schmerzen verursachen oder kuenftige Arbeit blockieren.
• Skalierung annehmen: Keine verteilten Systeme fuer eine App mit 100 Nutzern empfehlen. Architektur an tatsaechliche Anforderungen anpassen.

Verwandte Skills

• security-audit-codebase — sicherheitsfokussiertes Code- und Konfigurationsreview
• configure-git-repository — Repository-Struktur und Konventionen
• design-serialization-schema — Datenschema-Design und -Entwicklung
• review-data-analysis — Review auf analytische Korrektheit (ergaenzende Perspektive)