Skip to main content

Model Artifact: Architecture Decision Record

Scenario​

A Semester 7 learner records a decision for asynchronous email delivery in a modular monolith.

Completed learner-quality example​

ADR-004: Use an internal outbox for email dispatch​

Status: Accepted

Date: 2026-03-18

Context​

Order placement currently sends confirmation email during the request. When the email provider is slow, checkout latency rises and occasional provider failures force users to retry orders that were already committed.

Decision​

Persist email work in an email_outbox table inside the same transaction as order creation. A background worker reads pending rows, sends email, records provider response metadata, and retries transient failures with bounded backoff.

Alternatives considered​

  1. Keep synchronous email: simplest code, but checkout remains coupled to provider latency.
  2. Publish directly to a broker: good long-term direction, but introduces new infrastructure before the team has operational experience with it.
  3. Transactional outbox: preserves atomic recording of work and can later feed a broker.

Consequences​

  • Checkout latency no longer depends on the provider's response time.
  • Email becomes eventually delivered, so UI copy must say “confirmation email is on its way.”
  • The team must operate a worker, retry policy, dead-letter view, and alert for stuck rows.

Fitness checks​

  • New order creation writes exactly one outbox row in the same transaction.
  • Worker retry tests cover transient and permanent provider failures.
  • Alert fires when pending rows older than 10 minutes exceed threshold.

How to read this example​

  • Passing: Records context, decision, alternatives, and consequences.
  • Strong: Makes the tradeoff explicit instead of presenting the accepted option as obviously correct.
  • Portfolio-worthy: Adds fitness checks that keep the architecture decision testable over time.