Architecture Decision Records

Das Projekt führt Architecture Decision Records (ADRs) für nicht-triviale Design-Entscheidungen. Jeder ADR dokumentiert:

Die Entscheidung — was entschieden wurde.
Kontext — welches Problem die Wahl angestoßen hat.
Betrachtete Alternativen — was sonst zur Wahl stand.
Trade-offs — was aufgegeben vs. gewonnen wurde.
Konsequenzen — was das für die Codebase impliziert.

Für die meisten Nutzer sind ADRs optionale Lektüre — sie sind für Contributors + neugierige Nutzer, die das tiefe “Warum” wollen.

Wo sie leben

ADRs werden im Repo unter docs/adr/ geführt (falls vorhanden) oder als Long-Form-Kommentare in den relevanten Quelldateien.

Das Framework folgt dem ADR-Pattern locker — nicht jeder PR erzeugt einen ADR, aber große Entscheidungen schon.

Bestehende ADRs

(Die tatsächliche ADR-Liste ist im Repo; das ist ein hochrangiges Sample.)

ADR	Thema
001	Warum Bun als primäre Runtime.
002	Der TypeScript-First-Message-Vertrag (vs. Runtime-Checks).
003	HOCON über YAML für Konfiguration.
004	Die CRDT-Typ-Menge (welche auszuliefern, warum nicht mehr).
005	Single-Prozess vs. Multi-Prozess Clustering als Default.
006	Die `Lease`-Abstraktion (vs. eingebettete Koordination).
007	At-Least-Once-Delivery-Modell (vs. Exactly-Once-Versprechen).
008	Warum `ts-pattern` als Peer-Dependency, nicht gebündelt.
009	Das Schema-Migration-Envelope-Format.

Diese Namen sind illustrativ — das tatsächliche ADR-Repo hat seine eigene Nummerierung + Scope.

Wann ein neuer ADR hinzugefügt wird

Ein neuer ADR wird geschrieben, wenn:

Eine Design-Änderung mehrere Module betrifft.
Ein Trade-off nicht offensichtlich ist und zukünftige Contributors “warum?” fragen würden.
Eine API-Oberfläche verbindlich gemacht wird.

Triviale Refactors und Bugfixes bekommen keine ADRs. Der Maßstab ist “würde ein kluger Contributor in einem Jahr Dir danken, dass Du das aufgeschrieben hast?”

Einen ADR lesen

ADRs sind in einfachem Markdown geschrieben:

# ADR 005: Single-Prozess-Clustering

## Context
Akka and Pekko run a JVM cluster across processes.  For
TypeScript, single-process and multi-process are both
plausible defaults.

## Decision
Cluster across processes is the default.  Single-process
"worker mesh" is a separate opt-in.

## Alternatives
- Single-process default: simpler, less flexible.
- Worker-thread cluster: complex to debug.
- TCP-only cluster: today's default, most operationally
  familiar.

## Trade-offs
We gain operational simplicity (each process is independent).
We lose in-memory cluster-internal sharing.

## Consequences
- The cluster transport defaults to TCP.
- Worker-mesh has its own transport + setup.
- Tests use MultiNodeSpec (in-process) or
  ParallelMultiNodeSpec (process-isolated).

Lies den relevanten ADR, bevor Du Änderungen am selben Bereich vorschlägst — Kontext könnte Deinen Vorschlag abschrecken oder neu rahmen.

Beiträge zu ADRs

Wenn Du einen PR einreichst, der eine wesentliche Design-Entscheidung ändert, füge einen ADR bei. Reviewer werden um einen bitten, wenn er fehlt.

Vorlage:

# ADR NNN: <Titel>

## Context
<das Problem, das Du löst>

## Decision
<was Du entschieden hast>

## Alternatives
<was Du sonst betrachtet hast>

## Trade-offs
<was Du gewinnst vs. verlierst>

## Consequences
<was das impliziert>

Halte ADRs kurz (1-2 Seiten). Long-Form-Diskussion gehört in den PR oder in ein Design-Doc.

Wie es weitergeht

Design-Entscheidungen — kürzerer “Warum”-Inhalt.
FAQ — häufige Fragen zum Framework.
Versionspolitik — was stabil ist + die Upgrade-Geschichte.