Architektur und Entscheidungen dokumentieren

Architecture & Decision Records

Explain the system's structure, data flow and invariants so a developer knows where new behavior belongs, which boundaries must hold, and why significant technical decisions were made.

1. Architecture overviews that trace real boundaries

• System map: name the runtime processes, packages or services (server, ui, workers, database, external providers) and state the single responsibility of each.
• Data and control flow: walk through the main end-to-end flows (such as an incoming HTTP request, a background job lifecycle or a real-time event stream) from entry point to storage and back.
• State and ownership: state where each kind of state lives (database tables, in-memory caches, URL/client state, filesystem artifacts) and which module is allowed to mutate it.
• Invariants and constraints: highlight the rules that must never be violated (security invariants, transaction boundaries, tenant isolation, idempotency, ordering guarantees).
• Ground every diagram or module list in actual directory paths and entry files; never draw boxes for layers that do not exist in the repository.

2. Architecture Decision Records (ADRs)

Record an ADR whenever a choice has lasting consequences across modules, data models, dependencies, security or operations. Each ADR must state:

1. Title and status: Proposed, Accepted, Superseded by ADR-NNN or Deprecated, with the date or change context.
2. Context and problem: the technical, product and operational forces at play, stated neutrally without pre-judging the answer.
3. Alternatives considered: the realistic options evaluated (including doing nothing or extending an existing pattern) and their trade-offs.
4. Decision: the chosen approach and the concrete reason it won over the alternatives.
5. Consequences: what becomes easier, what becomes harder, what risks or limits remain, and how the decision is enforced or verified.

3. Keep architecture docs alive

• When a new ADR supersedes an earlier decision, keep the old ADR for historical context, mark its status as Superseded by ..., and update the active architecture overview to reflect current reality.
• Never present an unaccepted proposal or future target architecture as the system that runs today.

Before you finish

• Every module, package and boundary named in the overview points to real paths in the repo.
• End-to-end data flow and state ownership are clear.
• Each ADR records status, context, alternatives considered, decision and consequences.
• Accepted decisions, open proposals and superseded historical records are clearly distinguished.