Systemarchitektur ohne Chaos: Entscheidungen, Team und belastbare Nachweise

Eine Definition für die Praxis

Architektur umfasst Entscheidungen, die sich später schwer rückgängig machen lassen.

Ein Framework lässt sich wechseln, eine Buttonfarbe ändern, ein Endpoint umbenennen. Schwieriger sind Datenmodell, Verantwortungsgrenzen, Zahlungsintegration, Berechtigungspolitik, Deployment-Pipeline oder Beobachtbarkeitsregeln.

Ist eine Entscheidung teuer rückgängig zu machen, gehört sie in die Architekturarbeit. Ist sie es nicht, braucht es keine große Beratung. Diese einfache Regel schützt vor zwei Extremen: regellosem Chaos und wertloser Bürokratie.

Was benötigt wird

Fünf Dinge, ohne die Architektur nur eine Zeichnung bleibt.

Meist fehlt nicht Technologie, sondern Verantwortung. Das Team weiß, dass „eine Integration nötig ist“, aber niemand hält fest, wer Retries verantwortet, was bei Duplikaten passiert, wohin Fehler gelangen, wer das Ergebnis abnimmt und wann die Aufgabe abgeschlossen ist.

Architektur sollte deshalb kurz, lesbar und mit einem echten Ablauf verbunden sein. Bezahlt ein Kunde ein Audit, muss das System wissen, was die Zahlung bedeutet, wann die Messung startet, wie der Bericht gespeichert und die Nachricht versendet wird und was bei einem gescheiterten Schritt angezeigt wird.

Wann genügt leichte Ordnung, wann braucht es formale Architektur?

Menschen und Verantwortung

Wer sollte Architektur einführen, und wie viele Personen gehören dazu?

Das schlechteste Modell ist eine Person, die „die Architektur erfindet“ und sie dem Team als unumstößliche Wahrheit übergibt. Ebenso schlecht: zwölf Personen mit Meinungen, aber niemand mit Verantwortung.

Für die meisten Projekte reicht eine kleine Runde: fachliche Zielverantwortung, technische Verantwortung für Backend und Daten, jemand für Frontend oder Nutzererlebnis, Betrieb und Sicherheit sowie bei Bedarf Domänenwissen aus Vertrieb, Buchhaltung, Logistik oder Support.

Mehr Menschen bedeuten nicht bessere Architektur. Oft bedeuten sie langsamere Entscheidungen und verteilte Verantwortung. Besser ist ein kleines Team, das entscheiden, begründen und Ergebnisse nachweisen kann.

Wähle eine Entscheidung und prüfe ihre Konsequenz.

Beispiel aus dem Produktivbetrieb

Eine kleine Funktion wird teuer, wenn ihre Grenzen falsch liegen.

Stellen wir uns vor: Ein Kunde gibt eine URL ein, bezahlt ein Audit, das System analysiert, speichert das Ergebnis, verschickt eine E-Mail und zeigt den Bericht im Panel. Auf einer Folie klingt das einfach. In Produktion folgen sofort Fragen: Was bei zwei Stripe-Webhooks, fehlender E-Mail, längerer Analyse, Neuladen nach der Zahlung oder einem fertigen Bericht, dessen Datenbankspeicherung scheitert?

Genau hier beginnt Architektur. Nicht bei der Bibliothekswahl, sondern beim Verhalten in der realen Welt.

public async Task CompleteOrder(Guid orderId)
{
    var order = await db.Orders.FindAsync(orderId);
    order.Status = "Paid";

    var audit = await crawler.Run(order.TargetUrl);
    order.ReportJson = JsonSerializer.Serialize(audit);

    await email.Send(order.Email, "Raport gotowy", audit.Summary);
    await stripe.MarkProcessed(order.PaymentIntentId);
    await db.SaveChangesAsync();
}

public sealed record ConfirmAuditPayment(
    Guid OrderId,
    string PaymentIntentId,
    DateTimeOffset ConfirmedAt);

public sealed class ConfirmAuditPaymentHandler
{
    public async Task Handle(ConfirmAuditPayment command)
    {
        var order = await orders.Get(command.OrderId);

        order.MarkAsPaid(command.PaymentIntentId, command.ConfirmedAt);
        outbox.Add(new AuditRequested(order.Id, order.TargetUrl));
        outbox.Add(new CustomerNotificationRequested(order.Id));

        await unitOfWork.SaveChanges();
    }
}

SOLID ohne Glaubenskrieg

Prinzipien sollen helfen, nicht fehlende Entscheidungen verdecken.

Single Responsibility sagt: Wenn eine E-Mail-Änderung die Zahlung beschädigt, sind Verantwortungen vermischt. Open/Closed sagt: Wenn jeder neue Anbieter einen halben Systemumbau verlangt, fehlt ein Vertrag. Dependency Inversion sagt: Hängt die Domäne von technischen Details ab, bestimmen diese bald das Produkt.

Praktisch reichen zunächst einfache Verträge, die keine falschen Versprechen machen:

public interface AuditReportStore
{
    Task Save(AuditReport report, CancellationToken cancellationToken);
}

public interface AuditNotifier
{
    Task NotifyReportReady(Guid orderId, CancellationToken cancellationToken);
}

public sealed class CompleteAuditHandler
{
    public async Task Handle(AuditCompleted completed, CancellationToken ct)
    {
        await reports.Save(completed.Report, ct);
        await notifier.NotifyReportReady(completed.OrderId, ct);
    }
}

Ordne die Schritte. Beginne beim Ziel, nicht bei der Technologie.

Antworten löschen

Ein fremdes System übernehmen

Beginne nicht mit Refactoring. Verstehe zuerst, was nicht kaputtgehen darf.

Bestehenden Code zu übernehmen ist weder Schuldigensuche noch Jagd auf hässliche Klassen, sondern Detektivarbeit. Finde kritische Abläufe, Quelldaten, Integrationen, Entscheidungsverantwortliche und Stellen, an denen ein fehlender Test Kunden Geld kosten kann.

Ein Charakterisierungstest erklärt alten Code nicht für schön. Er sagt: „So arbeitet das System heute, und das dürfen wir nicht versehentlich ändern.“

[Fact]
public async Task Paid_order_requests_audit_only_once_for_duplicate_webhook()
{
    var paymentIntentId = "pi_123";

    await app.HandleStripeWebhook(paymentIntentId);
    await app.HandleStripeWebhook(paymentIntentId);

    var order = await app.FindOrderByPayment(paymentIntentId);

    Assert.Equal(OrderStatus.Paid, order.Status);
    Assert.Single(await app.Outbox.EventsOfType<AuditRequested>(order.Id));
}

Wähle eine Antwort und erfahre, was sie für die Wartung bedeutet.

ADR-004: Das Audit startet nach der Zahlung asynchron

Kontext:
Ein Website-Audit kann einige zehn Sekunden bis mehrere Minuten dauern.
Der Checkout muss schnell abgeschlossen sein.

Entscheidung:
Nach dem Stripe-Webhook speichern wir die Bestellung als bezahlt
und schreiben das Ereignis AuditRequested in die Outbox.

Folgen:
Das Panel zeigt den Status "in der Warteschlange".
Der Worker kann das Audit nach einem Fehler wiederholen.
Wir brauchen Monitoring für die Queue und gescheiterte Jobs.

Nachweis:
Test eines doppelten Webhooks, Test eines Worker-Neustarts,
Korrelationslog mit orderId.

Kontrollfragen

Kannst du sie nicht beantworten, ist die Architektur noch nicht fertig.

Erkenntnis

Gute Architektur zeigt sich besonders, wenn etwas schiefgeht.

Kann ein System seinen Status klar anzeigen, Vorgänge sicher wiederholen, Daten erhalten, Alarme senden, Änderungen zurücknehmen und Menschen an der richtigen Stelle entscheiden lassen, beginnt Architektur sich auszuzahlen.

Weil sie Chaoskosten reduziert und dem Team angstfreie Änderungen ermöglicht.