Skip to main content

Module 5: Architecture Decisions & Reviews: Worked Examples

Example 1: Rewrite a Non-Decision as an ADR​

Weak record: “We chose Kafka because it is scalable.” It contains no context, alternatives, or consequences.

Reviewable record: “For order-domain events we need replay for seven days, per-order ordering, and 5k events/s. We will use the existing managed Kafka platform with order_id as partition key. We reject direct HTTP fan-out because consumers need independent replay, and reject a new broker because operating a second platform exceeds team capacity. Consequences include schema governance, consumer lag monitoring, partition hot-spot risk, and at-least-once handling.”

The second record is falsifiable and can be superseded when its forces change.

Example 2: Run a Risk-Driven Review​

Start with business goal and quality scenarios, then inspect the riskiest claims: data loss, authorization boundary, recovery time, peak-load behavior, and irreversible coupling. Assign findings an owner, evidence request, severity, and due date. A review that produces only opinions or a pass/fail label is not complete.

Example 3: Turn a Quality Claim Into a Fitness Function​

If modules must not bypass APIs, enforce forbidden imports and database-schema ownership in CI. If p99 latency must stay below 300 ms, run a representative performance gate with documented noise bounds. Fitness functions monitor a specific architectural characteristic; they do not prove the whole architecture correct.

Completion Standard​

  • Write three ADRs with alternatives and consequences.
  • Conduct a review that closes evidence-backed findings.
  • Automate one architecture rule and document its blind spots.