How to Build a Commerce Architecture Decision Record Practice

Summary

Commerce programs generate high-impact architecture decisions quickly: storefront approach, search strategy, integration ownership, catalog partitioning, identity model, release topology, observability scope, and more. The problem is not that teams never make decisions. The problem is that they make them in workshops, tickets, chat threads, and meeting notes, then lose the rationale when the program changes shape.

A useful architecture decision record practice gives commerce teams continuity. It helps new team members understand why a choice exists, helps delivery leads evaluate change requests against prior decisions, and reduces repeated debate over settled topics.

What should become an ADR?

Not every technical choice needs a formal record. Focus on decisions that have blast radius across teams, releases, or operating models. In SAP Commerce programs, that often includes:

• storefront strategy and ownership boundaries,
• catalog and content partitioning,
• integration contract design for core domains,
• search platform and indexing approach,
• identity and access model,
• deployment and release topology,
• observability standards for critical journeys,
• buy-versus-build decisions with upgrade implications.

A good test is simple: if the decision would be painful to rediscover six months later, record it.

Keep the template minimal but rigorous

Teams abandon ADRs when the template feels like architecture theater. The template should be short enough to complete during delivery but structured enough to preserve reasoning.

# ADR-012: Choose shared OCC contract strategy for multi-storefront delivery

## Status
Accepted

## Context
Program supports multiple storefront experiences on one SAP Commerce core.
Uncontrolled OCC divergence would increase upgrade and testing overhead.

## Decision
Adopt a shared OCC contract with experience-specific composition at the edge.
Storefront-specific commerce logic is not permitted in core APIs without review.

## Consequences
- Improves upgrade resilience
- Requires stronger API governance
- Pushes some presentation composition outside SAP Commerce

## Rejected alternatives
- Separate OCC extensions per storefront
- Storefront-specific controller customizations in core

That is enough to preserve the decision. You can add metadata such as date, owner, reviewers, or links to epics, but do not let the process become so heavy that teams avoid it.

Make ADRs part of the delivery flow

An ADR practice succeeds when it is attached to actual work, not stored as a parallel document exercise.

Trigger points

Create or update an ADR when a change affects shared architecture, introduces significant custom code, changes system boundaries, or creates new operational obligations.

Review points

Review ADRs during architecture forums, delivery checkpoints, or pull request gates for affected areas. The important thing is consistency, not ceremony.

Lifecycle

ADRs should support statuses such as proposed, accepted, superseded, and retired. This keeps the history clean without pretending decisions never evolve.

Ownership matters more than format

Every ADR should have a named owner or sponsoring role. Not because architecture belongs to one person, but because ambiguity kills follow-through. The owner is responsible for ensuring the record is created, reviewed, linked to implementation work, and updated if superseded.

In commerce programs, ownership is often shared across architecture and delivery. That is fine as long as the team knows who closes the loop.

Where teams get ADRs wrong

They record conclusions without context

"Use headless" is not useful unless the record explains why, under what constraints, and what trade-offs were accepted.

They document after the fact only when something is controversial

This turns ADRs into political evidence instead of working architecture tools.

They never revisit decisions

An accepted ADR should not be immutable. If assumptions change, the record should be superseded rather than silently ignored.

They write too many low-value ADRs

If every library choice or minor refactor gets a formal ADR, the practice loses signal.

An operating model that works in practice

The simplest durable model usually includes:

• one repository location for ADRs,
• a lightweight naming convention,
• a short template,
• review in the same forums where architecture decisions are already discussed,
• links from ADRs to work items and from work items back to ADRs,
• a periodic review of open or aging proposed decisions.

For example, you may keep ADRs under a dedicated folder and maintain a small index by status and domain.

adr_practice:
  location: "docs/adr/"
  naming: "ADR-###-short-decision-name.md"
  required_fields:
    - status
    - context
    - decision
    - consequences
    - rejected_alternatives
  review_forum: "weekly architecture and delivery sync"
  revisit_rule: "supersede when assumptions or constraints materially change"

This is enough for most programs. The point is consistency.

Illustrative example

Imagine an illustrative SAP Commerce program debating whether each storefront may extend OCC independently. Early in delivery, one team argues for speed and wants local ownership. Another argues for a shared contract to preserve upgrade resilience. The meeting ends with a verbal compromise, but no ADR is written. Three months later, new team members add brand-specific endpoints because they never saw the original trade-off discussion.

With an ADR practice, the decision would be explicit: shared OCC strategy, exceptions require review, consequences acknowledged, and rejected alternatives recorded. The team may still revisit the decision later, but it would do so consciously rather than by drift.

Questions to ask before adopting the practice

• Which decision types repeatedly create rework in our program?
• Where do architecture decisions currently disappear?
• Which review forum already exists and can own the lightweight process?
• What is the minimum template that our teams will actually keep current?
• How will we show when a decision has been superseded rather than abandoned?

These questions keep the practice operational instead of theoretical.

Start small, then enforce selectively

Do not begin with dozens of backfilled records. Start with new high-impact decisions and a few active architecture topics already causing debate. Once the team sees value, add guardrails: major shared-platform changes require an ADR; upgrade-sensitive customizations require an ADR; exceptions to architecture standards require an ADR.

That phased approach works better than a large documentation cleanup initiative that delivery teams will not maintain.

Next step

A commerce ADR practice is worthwhile when it reduces architectural amnesia and improves decision quality under delivery pressure. Keep the template small, tie it to real work, assign ownership, and treat superseded decisions as normal, not embarrassing.

If you want a starting point, download an ADR template pack and use it in your next architecture review: get the template pack.