The Complete Responsive CMS Blog created by Francesco Malagrino

Beyond the Template: Writing Architecture Decision Records as Engineering Stories

Category: Software Architecture & Written by Francesco Malagrino On July-27-2026 14:00:48

---

An Architecture Decision Record should not read like a compliance form nobody wants to open.

At its core, an ADR captures a difficult engineering decision: the problem, the alternatives, the chosen approach, and the consequences that follow.

When turning an ADR into an engineering article, the goal is not to reduce the technical depth. It is to expand the reasoning behind the decision in a way that is clear, credible, and useful to other engineers.

A strong architecture article usually follows four stages:

1. Context


2. Alternatives


3. Decision


4. Consequences

The order-processing scenario used throughout this article is illustrative, but it reflects constraints commonly found in production distributed systems.

Start with the engineering problem

Before describing the architecture, explain what forced the decision.

Imagine an order-processing platform struggling during peak traffic. Requests are timing out, database connections are being exhausted, and failures in the payment service are leaving orders in inconsistent states.

That is more useful than opening with:

We decided to implement the Saga pattern.

The reader first needs to understand the constraints that shaped the decision.

Perhaps the platform had to meet a strict response-time target. Maybe the engineering team consisted of only four developers. The existing database might not have supported additional write traffic, while individual services still needed to be deployed independently.

Architecture does not happen in a vacuum.

A design that works for a large platform organisation may be unsuitable for a small product team working under strict delivery deadlines.

A useful ADR makes those constraints clear from the beginning.

Explain the rejected alternatives

The alternatives that were not selected are often one of the most valuable parts of an ADR.

They show that the final architecture was chosen after comparing multiple approaches against the actual system constraints.

For example, the team might have considered a distributed transaction based on Two-Phase Commit.

Two-Phase Commit can provide atomic coordination between participating systems that support it. However, it also introduces blocking coordination, tighter operational coupling, and availability concerns when a coordinator or participant becomes unavailable.

The team might also have considered a centrally orchestrated Saga.

An orchestrator would make the workflow easier to follow and provide a clear location for coordination and compensation logic. However, it could also become a shared dependency across multiple domains, concentrate too much business logic in one component, and reduce the autonomy of teams that need to evolve their services independently.

Neither option is inherently wrong.

The important question is why each alternative was unsuitable for this particular system.

A credible ADR does not simply defend the selected solution. It shows that the benefits, limitations, and operational consequences of the alternatives were understood.

State the decision clearly

Once the context and alternatives have been established, the decision should be direct.

For example:

We adopted Saga choreography using Kafka events because it allowed each domain service to own its business logic, data, deployment lifecycle, and compensating actions without depending on a central workflow coordinator.

The explanation should connect the decision directly to the original constraints.

In this scenario, choreography allowed the order, payment, inventory, and shipping services to evolve independently. It also reduced runtime coupling because services reacted to published events rather than calling one another through a long synchronous chain.

The following TypeScript-like pseudocode illustrates a simplified event-processing boundary:

await database.transaction(async (transaction) => {

  // 1. Atomically claim the event inside the transaction.

  // This represents an operation such as:

  // INSERT ... ON CONFLICT DO NOTHING

  const claimed =

    await transaction.processedEvents.insertIfAbsent(event.id);



  if (!claimed) {

    return;

  }



  // 2. Apply the domain state modification.

  await orderService.confirmPayment(

    event.orderId,

    transaction

  );



  // 3. Store the outgoing event in the outbox.

  await transaction.outbox.insert(

    new OrderConfirmed(event.orderId)

  );

});

insertIfAbsent() is illustrative pseudocode rather than a specific library method. In a production implementation, it should map to an atomic database operation such as INSERT ... ON CONFLICT DO NOTHING, or the equivalent provided by the selected database.

The processed-event identifier must also be protected by a unique database constraint. This prevents two consumers from claiming and processing the same event concurrently.

The event claim, domain update, and outbox insertion occur within the same database transaction. If any step fails, the entire transaction is rolled back.

A separate publisher can then deliver the outbox event to Kafka without introducing a dual-write consistency gap between the database update and message publication.

The outbox publisher may still deliver an event more than once, so downstream consumers should also process events idempotently.

Document the consequences

Every architectural decision solves one set of problems while introducing another.

Saga choreography can improve service autonomy, horizontal scalability, and fault isolation. Domain teams can deploy independently, and the platform no longer depends on a central transaction coordinator.

However, the system also becomes harder to understand.

A single business transaction may be distributed across multiple services and event streams. Debugging requires engineers to reconstruct the path of an order across several asynchronous operations.

The architecture should therefore propagate correlation identifiers through event headers and distributed traces, using standards and tooling such as OpenTelemetry.

Compensation logic also becomes the responsibility of the relevant domain.

A failed payment might require the order service to cancel the order. A later inventory failure might require the payment service to issue a refund.

These compensating actions are not automatic database rollbacks. They are explicit business operations that must be designed, implemented, tested, monitored, and sometimes retried.

Event ordering, duplicate delivery, schema evolution, dead-letter queues, replay strategies, and eventual consistency also become part of the operational model.

What improved

• Independent service deployment


• Better fault isolation


• Horizontal scalability


• Reduced synchronous coupling


• Clearer domain ownership

What became harder

• End-to-end debugging


• Event ordering and duplicate handling


• Distributed observability


• Compensation design


• Schema evolution


• Eventual-consistency testing


• Replay and dead-letter queue management


• Operating the messaging infrastructure

Include measurable outcomes

When the decision is reviewed later—or expanded into an engineering article—the outcome should be supported with measurable evidence.

Useful evidence might include:

• Reduced request latency


• Increased processing throughput


• Fewer cascading failures


• Shorter deployment lead time


• Lower recovery time after incidents


• Reduced cross-team coordination


• Changes in infrastructure or operational cost

Not every outcome will be positive.

The architecture may require additional infrastructure for Kafka, schema management, distributed tracing, dead-letter queues, and monitoring.

Incident investigation may also become slower because engineers must follow transactions across several services instead of inspecting a single application.

When the scenario is illustrative, avoid presenting invented measurements as real production results. Explain which metrics should be collected instead.

Preserve the ADR structure

Even when written as a narrative, the essential ADR structure should remain easy to identify.

Status: Is the decision proposed, accepted, deprecated, superseded, or rejected?

Context: What problem, constraints, and technical forces shaped the decision?

Alternatives: Which approaches were considered, and why were they rejected?

Decision: What was selected, and why?

Consequences: What benefits, risks, costs, and new responsibilities followed?

The article can remain conversational without losing the structure and discipline of an Architecture Decision Record.

Final thought

The best architecture articles do not simply describe what was built.

They explain how the decision was reached, which constraints shaped it, and which trade-offs were accepted.

Readers learn little from being told that a team used Kafka, Kubernetes, microservices, or the Saga pattern.

They learn from understanding why those technologies were selected, why other options were rejected, and what operational responsibilities followed.

A useful ADR records the decision, its context, and its consequences.

A strong engineering article expands that record into a clear account of the constraints, alternatives, and trade-offs that shaped it.

Facebook Whatsapp Twitter Linkein Pinterest Reddit Tumblr Mail

Systems Architecture
Cloud Native Architecture
Site Reliability Engineering (SRE)
typescript
nodejs
Distributed-Systems
Microservices
Software Architecture
Rest
Java
Technology

---

---

---

---

---