# Composable Commerce Architecture: [Brand or programme name]

> Solution architecture for a composable (MACH) digital commerce platform: packaged business
> capabilities for the commerce engine, product information management (PIM), content management
> (CMS), search and merchandising, order management (OMS), payments, promotions and the customer
> data platform (CDP), a headless frontend with a backend for frontend (BFF), the integration and
> data ownership model, peak-season performance, PCI DSS scope reduction with hosted payment
> fields, vendor selection and the migration from a commerce monolith. It follows the MACH
> principles as described by the MACH Alliance (Microservices, API-first, Cloud-native SaaS,
> Headless; framed in 2026 as open, composable and connected technology) and PCI DSS v4.0.1 for
> payment scope. Replace every `[bracketed]` value and every row marked *Example*. Payment and
> privacy sections are a documentation format, not legal or compliance advice.

<!--
Guidance: How to use this template
- Write one architecture per commerce programme (one brand or a group of brands sharing a
  platform). Detailed component designs live in their own documents and are linked from section 6.
- Fill section 2 (business context and peak numbers) and section 4 (capabilities and data
  ownership) first. Composable architecture fails most often on unclear ownership of product,
  price, stock and customer data, not on technology.
- Composable is a means, not a goal. For a single-market brand with a simple catalogue, a suite
  may be the better answer; record that comparison in section 12.
- Related documents: Cart, checkout and inventory system design
  (`system-design/design-ecommerce-checkout-inventory`), Recommendation system design
  (`system-design/design-recommendation-system`), Business Capability Map
  (`architecture/business-capability-map`), Integration Design (`architecture/integration-design`),
  Microservice Specification (`architecture/microservice-spec`), Frontend Architecture
  (`architecture/frontend-architecture`), PCI DSS Scoping and Segmentation
  (`compliance/pci-dss-scoping-segmentation`).
-->

## Document control

<!-- Guidance: Identify the brands, markets and channels in scope and who decides. A change of commerce engine, OMS or frontend approach is a new major version. -->

| Field | Value |
|---|---|
| Document ID | [CCA-001] |
| Programme | [Programme name] |
| Brands and markets | [Brand names, countries, currencies, languages] |
| Channels | [Web / Mobile app / Marketplace / Store endpoints / Social commerce] |
| Business model | [B2C / B2B / D2C / Marketplace / Mixed] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@commerce-architect] |
| Approvers/reviewers | [@chief-digital-officer], [@ecommerce-director], [@cto], [@ciso], [@data-protection-officer], [@finance-lead] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Related documents | [Business case], [Capability map], [Vendor evaluation], [Migration plan] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Architecture board | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Ecommerce business owner | [@name] | [Decision] | YYYY-MM-DD |
| Security and PCI owner | [@name] | [Decision] | YYYY-MM-DD |
| Finance and procurement | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* Added marketplace channel and split OMS from commerce engine |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved after vendor selection; release 1 scoped to two markets |

## Contents

<!-- Guidance: Keep this list aligned with the headings. -->

1. [Introduction and scope](#1-introduction-and-scope)
2. [Business context and peak profile](#2-business-context-and-peak-profile)
3. [Architecture principles](#3-architecture-principles)
4. [Business capabilities and packaged business capabilities](#4-business-capabilities-and-packaged-business-capabilities)
5. [Target architecture](#5-target-architecture)
6. [Component design](#6-component-design)
7. [Frontend and backend for frontend](#7-frontend-and-backend-for-frontend)
8. [Integration and orchestration](#8-integration-and-orchestration)
9. [Customer data, identity and personalisation](#9-customer-data-identity-and-personalisation)
10. [Performance and peak readiness](#10-performance-and-peak-readiness)
11. [Security and PCI DSS scope reduction](#11-security-and-pci-dss-scope-reduction)
12. [Vendor selection](#12-vendor-selection)
13. [Migration from the monolith](#13-migration-from-the-monolith)
14. [Operating model, cost and governance](#14-operating-model-cost-and-governance)
15. [Decisions, risks and traceability](#15-decisions-risks-and-traceability)
16. [Glossary and references](#16-glossary-and-references)

## 1. Introduction and scope

<!-- Guidance: State the commercial reasons for going composable and how success is measured. Pitfall: listing MACH as the driver; the drivers are speed of change, experience quality, market expansion and cost. -->

### 1.1 Purpose

This document defines the target commerce architecture for [programme name]: the business
capabilities, the products chosen to deliver them, which product owns which data, how the
customer-facing experience is composed from them, how the platform behaves at peak, how card data
stays out of scope, and how the current platform is retired. It is the reference for product teams,
system integrators and vendors.

### 1.2 Drivers and outcomes

| ID | Driver | Measurable outcome | Owner |
|---|---|---|---|
| DRV-001 *(Example)* | Releases on the monolith happen monthly with a code freeze | Frontend releases daily; backend capability releases weekly | [@cto] |
| DRV-002 *(Example)* | Site slowed down on last Black Friday | Peak conversion rate equal to normal-day conversion | [@ecommerce-director] |
| DRV-003 *(Example)* | Launching a new market takes 9 months | New market live in 10 weeks | [@international-director] |
| DRV-004 *(Example)* | Content changes need developers | Merchandisers publish content and landing pages without a release | [@head-of-ecommerce-content] |
| DRV-005 *(Example)* | Self-hosted platform is in full PCI DSS scope | Card data never touches the platform; SAQ eligibility confirmed by the acquirer | [@ciso] |
| [DRV-nnn] | [Driver] | [Outcome and target] | [@owner] |

### 1.3 Scope

| In scope | Out of scope |
|---|---|
| [*Example:* Web storefront and mobile app for two brands in 6 markets] | [*Example:* Store point-of-sale replacement] |
| [*Example:* Catalogue, pricing, promotions, cart and checkout, orders, returns] | [*Example:* Warehouse management system (integrated, not replaced)] |
| [*Example:* Content, search, recommendations, customer accounts, loyalty integration] | [*Example:* ERP finance processes] |
| [*Example:* Marketplace feeds to [marketplaces]] | [*Example:* Marketplace seller platform for third-party sellers] |

## 2. Business context and peak profile

<!-- Guidance: Quantify normal and peak demand and the catalogue. These numbers drive vendor tier, rate limit and caching decisions. Pitfall: using annual averages, which hide the 10 to 20 times spikes of sales events and drops. -->

### 2.1 Commerce profile

| Measure | Normal day *(Example)* | Peak hour *(Example)* | Source |
|---|---|---|---|
| Orders | 28,800 per day (1,200 per hour) | 12,000 per hour (10 times normal) | Last two peak seasons |
| Conversion rate | 2.5% | 2.5% (target) | Analytics |
| Sessions | 1,152,000 per day | 480,000 per hour | Orders divided by conversion rate |
| Page views per session | 8 | 8 | Analytics |
| SKUs | 120,000 SKUs in 18,000 products | Same | PIM |
| Price changes | 40,000 per day | 300,000 in the hour before the sale | Pricing team |
| Markets and currencies | 6 markets, 4 currencies | Same | Business plan |

### 2.2 Peak calendar

| ID | Event | Date | Expected peak multiple | Special behaviour |
|---|---|---|---|---|
| PK-001 *(Example)* | Black Friday and Cyber Monday | [YYYY-MM-DD] | 10 times | Price drop at midnight, queue page ready |
| PK-002 *(Example)* | Limited product drop | [YYYY-MM-DD] | 25 times on a few SKUs | Hot SKUs, bot traffic |
| PK-003 *(Example)* | Seasonal sale | [YYYY-MM-DD] | 5 times | Content-heavy landing pages |

## 3. Architecture principles

<!-- Guidance: Turn MACH into testable principles for this programme, each with the decision it drives. Pitfall: principles nobody can check in a design review. -->

| ID | Principle | Rationale | Implication |
|---|---|---|---|
| PRI-001 | Microservices: each capability is independently deployable and replaceable | Change one capability without regression across others | One owning team per capability; no shared database between capabilities |
| PRI-002 | API-first: every capability is consumed through documented APIs and events | Composition and replacement depend on stable contracts | APIs designed before UI; contracts versioned; see `architecture/api-design-guidelines` |
| PRI-003 | Cloud-native SaaS: prefer multi-tenant SaaS that scales elastically and updates continuously | Avoid upgrade projects and capacity planning for peak | Contracts include peak limits; no forked vendor code |
| PRI-004 | Headless: presentation is separated from commerce logic | Many channels and fast frontend change | Frontend owns rendering; backends return data only |
| PRI-005 | One system of record per data entity | Composable systems fail on conflicting data | Data ownership matrix (section 8.2) approved before build |
| PRI-006 | Build only where you differentiate | Spend engineering on the experience, not on commodity features | Build-versus-buy per capability (section 4.2) |
| PRI-007 | Card data never enters the platform | Reduce PCI DSS scope and breach impact | Hosted payment fields or redirect only (section 11) |

The MACH Alliance now frames its principles as open, composable and connected technology. Treat
PRI-001 to PRI-004 as the technical form of those three goals: open contracts, modular capabilities
and real-time connection through APIs and events.

## 4. Business capabilities and packaged business capabilities

<!-- Guidance: A packaged business capability (PBC) is a business capability delivered as a deployable product or service with its own data, APIs and events. Map capabilities to PBCs and decide buy or build per PBC. Pitfall: choosing products first and discovering overlapping capabilities, such as promotions in three tools. -->

### 4.1 Capability map

| ID | Capability | Level 2 capabilities | Differentiating? | PBC |
|---|---|---|---|---|
| CAP-001 *(Example)* | Product information | Product data, enrichment, digital assets, syndication | No | PBC-02 PIM, PBC-03 DAM |
| CAP-002 *(Example)* | Catalogue and pricing | Catalogue, price lists, tax quote boundary | No | PBC-01 Commerce engine |
| CAP-003 *(Example)* | Promotions | Coupons, campaigns, bundles | Partly | PBC-01 Commerce engine (single promotion source) |
| CAP-004 *(Example)* | Content and experience | Pages, banners, editorial, localisation | Yes (brand experience) | PBC-04 CMS, custom frontend |
| CAP-005 *(Example)* | Search and discovery | Search, navigation, merchandising rules, recommendations | Yes | PBC-05 Search, PBC-09 Recommendations |
| CAP-006 *(Example)* | Cart and checkout | Cart, checkout, quote, address, shipping options | Partly | PBC-01 Commerce engine, custom checkout UI |
| CAP-007 *(Example)* | Payments | Authorisation, capture, refunds, alternative payment methods | No | PBC-06 Payment service provider |
| CAP-008 *(Example)* | Order management | Order capture, sourcing, fulfilment orchestration, returns | Partly | PBC-07 OMS |
| CAP-009 *(Example)* | Customer and loyalty | Accounts, consent, profile, loyalty | Partly | PBC-08 CDP, identity provider, loyalty platform |
| [CAP-nnn] | [Capability] | [Level 2] | [Yes / No / Partly] | [PBC] |

Keep the enterprise view in the Business Capability Map (`architecture/business-capability-map`);
this table is the commerce slice.

### 4.2 PBC register

| ID | PBC | Product or build | Delivery model | System of record for | Owning team |
|---|---|---|---|---|---|
| PBC-01 *(Example)* | Commerce engine | [Vendor] | SaaS | Catalogue, price lists, promotions, carts | Commerce core team |
| PBC-02 *(Example)* | PIM | [Vendor] | SaaS | Product attributes, enrichment status | Product data team |
| PBC-03 *(Example)* | DAM | [Vendor] | SaaS | Images, video, documents | Creative operations |
| PBC-04 *(Example)* | CMS | [Vendor] | SaaS (headless) | Pages, content entries | Content team |
| PBC-05 *(Example)* | Search and merchandising | [Vendor] | SaaS | Search index (derived), merchandising rules | Discovery team |
| PBC-06 *(Example)* | Payments | [Payment service provider] | SaaS | Payment transactions, tokens | Payments team |
| PBC-07 *(Example)* | OMS | [Vendor] | SaaS | Orders after placement, fulfilment, returns | Order team |
| PBC-08 *(Example)* | CDP | [Vendor] | SaaS | Unified profile, segments, consent state copy | Customer data team |
| PBC-09 *(Example)* | Recommendations | [Build] | Cloud services | Models, recommendation logs | Discovery team; see `system-design/design-recommendation-system` |
| PBC-10 *(Example)* | Frontend and BFF | [Build] | Cloud-native | None (composition only) | Experience team |

## 5. Target architecture

<!-- Guidance: One diagram that shows the layers: experience, composition, capabilities, integration and enterprise systems. Pitfall: drawing point-to-point lines between every SaaS product, which hides the integration design. -->

The target architecture has five layers. Channels call only the BFF; the BFF calls capability APIs;
capabilities exchange business events through the integration layer; enterprise systems connect
through the same layer.

```mermaid
flowchart TB
  subgraph EXP[Experience layer]
    WEB[Web storefront]
    APP[Mobile app]
    KIOSK[Store endpoints]
  end
  CDN[CDN and edge: caching, bot management, queue page]
  BFF[Backend for frontend and API gateway]
  subgraph PBC[Packaged business capabilities]
    CE[Commerce engine]
    CMS[CMS]
    SRCH[Search and merchandising]
    PAY[Payments with hosted fields]
    OMS[OMS]
    REC[Recommendations]
    IDP[Customer identity]
  end
  subgraph INT[Integration layer]
    EVT[Event broker]
    IPAAS[iPaaS and integration services]
  end
  subgraph ENT[Enterprise systems]
    PIM[PIM and DAM]
    ERP[ERP and finance]
    WMS[Warehouses and stores]
    CDP[CDP and marketing]
  end
  WEB --> CDN
  APP --> CDN
  KIOSK --> CDN
  CDN --> BFF
  BFF --> CE
  BFF --> CMS
  BFF --> SRCH
  BFF --> PAY
  BFF --> REC
  BFF --> IDP
  CE --> EVT
  OMS --> EVT
  EVT --> IPAAS
  IPAAS --> ERP
  IPAAS --> WMS
  IPAAS --> CDP
  PIM --> IPAAS
  IPAAS --> CE
  IPAAS --> SRCH
  EVT --> OMS
```

## 6. Component design

<!-- Guidance: For each PBC, record the decisions that matter at architecture level and link to the detailed design. Pitfall: specifying vendor features in detail here; keep this to responsibilities, boundaries and selection criteria. -->

### 6.1 Commerce engine

- Owns catalogue structure, price lists, promotions and carts; exposes cart, checkout and order
  placement APIs. It is the only place that computes a cart total. The quote boundary and stock
  reservation logic are designed in `system-design/design-ecommerce-checkout-inventory`.
- Decide early whether the engine or a separate pricing service owns prices for B2B contracts.
- Check vendor API rate limits, webhook delivery guarantees and multi-store or multi-market
  modelling against section 2.

### 6.2 PIM and DAM

- PIM is the system of record for product attributes and enrichment workflow; it publishes
  approved products to the commerce engine, search and marketplaces.
- Define a completeness rule per channel (for example images, size chart, translated description)
  that gates publication.
- DAM stores master assets; the CDN or an image service renders variants at the edge.

### 6.3 CMS

- Headless CMS owns pages and content entries; product data is referenced by identifier, never
  copied into content.
- Give merchandisers preview of a page with live product data and scheduled publication for peak
  events.

### 6.4 Search and merchandising

- The search index is derived from PIM, commerce engine (prices, availability flags) and
  inventory events; it is never a system of record.
- Merchandisers control boosting, pinning and synonyms through the search product; record the
  freshness requirement for prices and availability in the index (for example under 60 seconds).
- Recommendations follow `system-design/design-recommendation-system` and are composed by the BFF.

### 6.5 OMS

- The OMS owns the order after placement: sourcing across warehouses and stores, splits,
  fulfilment status, cancellations and returns. The commerce engine hands over at order placement.
- Available-to-promise data flows from the OMS or inventory service to the commerce engine and
  search with an agreed latency.

### 6.6 Payments

- A payment service provider (PSP) hosts the card entry fields or the payment page; the platform
  receives tokens and authorisation results only (section 11).
- Use the PSP's webhooks for asynchronous results and reconcile daily with settlement reports.

### 6.7 CDP

- The CDP builds the unified profile and segments from consented events; it is not the system of
  record for consent, which stays with the consent management platform and identity provider.
- Activation to marketing tools uses segments, not raw event streams.

## 7. Frontend and backend for frontend

<!-- Guidance: Decide rendering, composition and caching. The frontend is where differentiation happens and where most performance is won or lost. Pitfall: letting the browser call six SaaS APIs directly, exposing keys and multiplying latency. -->

| Topic | Options | Choice | Reason |
|---|---|---|---|
| Rendering | Client-side; server-side; static generation with incremental regeneration; hybrid | *Example:* Hybrid: static generation for content and category pages, server-side for product and cart | Cacheable pages at the edge, fresh prices and stock where needed |
| Composition | BFF per channel; shared GraphQL gateway; direct calls | *Example:* BFF per channel (web, app) | Each channel shapes its own payloads; contracts stay stable |
| Caching | CDN only; CDN plus BFF cache; none | *Example:* CDN plus BFF cache with event-based invalidation | Survives peak without overloading SaaS limits |
| Frontend framework | [Framework] | [Choice] | [Reason]; see `architecture/frontend-architecture` |
| Accessibility | WCAG level | *Example:* WCAG 2.2 AA | Legal duties in several markets; see `quality/accessibility-audit` |

BFF rules:

1. The BFF holds no business rules that belong to a PBC (prices, promotions, eligibility).
2. Every downstream call has a timeout, a fallback (cached response, hidden widget or degraded
   message) and a circuit breaker.
3. Secrets for SaaS APIs stay in the BFF; the browser receives only scoped, short-lived tokens.

## 8. Integration and orchestration

<!-- Guidance: Describe how PBCs share data and coordinate processes, and who owns each entity. Pitfall: two products both believing they own price or stock. -->

### 8.1 Integration patterns

| Pattern | Used for | Technology |
|---|---|---|
| Synchronous API through BFF | Browse, cart, checkout, account | REST or GraphQL; API gateway |
| Business events | Product published, price changed, order placed, order shipped, return received | Event broker; describe events with `architecture/event-api-specification` |
| Integration flows | ERP, WMS and marketplace synchronisation, mapping and enrichment | iPaaS or integration services; follow `architecture/integration-design` |
| Batch files | Large price loads, finance exports, legacy feeds | Managed file transfer; see `architecture/b2b-edi-file-transfer-design` |

### 8.2 Data ownership matrix

| Entity | System of record | Publishes to | Latency target | Conflict rule |
|---|---|---|---|---|
| Product attributes | PIM | Commerce engine, search, CMS, marketplaces | 15 minutes | PIM wins |
| Prices and price lists | [Commerce engine / pricing service] | Search, BFF cache, marketplaces | 60 seconds | Commerce engine wins |
| Promotions | Commerce engine | Search (badges), CMS (banners by reference) | 60 seconds | Commerce engine wins |
| Stock and available to promise | [OMS / inventory service] | Commerce engine, search | 30 seconds | Inventory wins; checkout re-validates |
| Content | CMS | BFF | On publish | CMS wins |
| Customer account and credentials | Identity provider | Commerce engine, CDP | Real time | Identity provider wins |
| Consent | Consent management platform | CDP, marketing tools | Real time | Consent platform wins |
| Order after placement | OMS | Commerce engine (order history), CDP, ERP | 1 minute | OMS wins |

### 8.3 Process orchestration

Order-to-cash spans the commerce engine, PSP, OMS, WMS and ERP. Keep one orchestrator per process:

- Checkout is orchestrated by the commerce engine (or checkout service) up to order placement.
- Fulfilment, cancellation and returns are orchestrated by the OMS.
- Refunds are requested by the OMS and executed by the PSP; finance postings flow from the OMS to
  ERP through the integration layer.

## 9. Customer data, identity and personalisation

<!-- Guidance: Describe identity, consent and the use of customer data in personalisation, with the legal basis. Pitfall: sending behavioural data to the CDP before consent is known. -->

| ID | Topic | Design |
|---|---|---|
| CDI-001 *(Example)* | Customer identity | CIAM with passwordless and social login; see `security/ciam-solution-design` |
| CDI-002 *(Example)* | Guest checkout | Allowed; order linked to account by verified email after the fact |
| CDI-003 *(Example)* | Consent | Consent platform records purposes per market; tags and CDP events fire only after consent |
| CDI-004 *(Example)* | Personalisation | Segments from CDP and recommendations; no special category data used |
| CDI-005 *(Example)* | Data subject requests | Identity provider triggers deletion or export across PBCs through an orchestrated workflow |
| CDI-006 *(Example)* | Data residency | Customer data for [market] stored in [region]; confirm each SaaS sub-processor; see `compliance/data-residency-sovereignty-assessment` |

Record the processing in the Record of Processing Activities (`compliance/gdpr-ropa`) and assess
high-risk profiling in a DPIA (`compliance/dpia`).

## 10. Performance and peak readiness

<!-- Guidance: Turn the peak profile into request rates per layer and compare them with each vendor's contracted limits. Pitfall: load testing the frontend while SaaS vendors' rate limits, which you cannot change on the day, stay untested. -->

### 10.1 Peak estimate

| Step | Calculation *(Example)* | Result |
|---|---|---|
| Peak orders per hour | 1,200 normal times 10 | 12,000 per hour (3.3 per second) |
| Peak sessions per hour | 12,000 divided by 2.5% conversion | 480,000 per hour |
| Peak page views per second | 480,000 times 8, divided by 3,600 | about 1,070 per second |
| BFF requests per second | 1,070 page views times 5 calls | about 5,330 per second |
| Requests reaching SaaS origins | 5,330 times (1 minus 80% cache hit) | about 1,070 per second |
| Cart writes per second | 10% of sessions build a cart, 4 writes each: 480,000 times 0.1 times 4, divided by 3,600 | about 53 per second |

Consequences: the commerce engine and search contracts must allow at least the origin rate with
headroom (for example 2 times), the cache hit rate is itself a requirement to test, and checkout
must stay healthy at 3.3 orders per second even if browse traffic exceeds the forecast. If the
contracted limit is lower, enable a checkout queue at the edge as designed in
`system-design/design-ecommerce-checkout-inventory`.

### 10.2 Peak readiness checklist

| ID | Item | Owner | Due |
|---|---|---|---|
| PRK-001 | Vendor peak notifications sent and limits confirmed in writing | Vendor manager | [Peak minus 8 weeks] |
| PRK-002 | Full journey load test at 1.5 times forecast, including third-party calls through sandboxes or agreed production tests | Performance lead; see `quality/performance-test-plan` | [Peak minus 6 weeks] |
| PRK-003 | Cache warm-up and invalidation tested for the midnight price change | Experience team | [Peak minus 4 weeks] |
| PRK-004 | Queue page and bot controls tested | Edge team | [Peak minus 4 weeks] |
| PRK-005 | Change freeze window agreed (frontend content changes allowed) | Release manager | [Peak minus 2 weeks] |
| PRK-006 | War room rota, dashboards and runbooks ready | Operations; see `ops/game-day-plan` | [Peak minus 1 week] |

### 10.3 Non-functional requirements

| ID | Quality | Requirement | Measure |
|---|---|---|---|
| NFR-001 *(Example)* | Performance | Largest Contentful Paint under 2.5 seconds at the 75th percentile on mobile | Real user monitoring |
| NFR-002 *(Example)* | Performance | BFF product detail response under 250 ms at the 95th percentile | APM |
| NFR-003 *(Example)* | Availability | Checkout 99.95% monthly, 99.99% during peak events | Synthetic and real user monitoring |
| NFR-004 *(Example)* | Freshness | Price and availability in search within 60 seconds of change | Event lag metric |
| NFR-005 *(Example)* | Degradation | Recommendations or reviews outage never blocks product page or checkout | Chaos test; see `ops/chaos-experiment` |

## 11. Security and PCI DSS scope reduction

<!-- Guidance: Decide how card data is captured so the platform stays out of the cardholder data environment as far as possible, and confirm the self-assessment questionnaire with your acquirer or QSA. Pitfall: assuming hosted fields remove all obligations; the pages that load them still need protection. -->

### 11.1 Payment capture options

| Option | How it works | Typical PCI DSS effect (confirm with acquirer or QSA) |
|---|---|---|
| Redirect to PSP payment page | Customer completes payment on the PSP's page | Smallest merchant scope among the options; SAQ A is commonly applicable |
| Hosted payment fields (iframes) | PSP serves each card field in an iframe inside the merchant page | Card data stays with the PSP; SAQ A is commonly applicable when all eligibility criteria are met |
| Direct post or JavaScript-built form | Merchant page builds the form that sends card data to the PSP | Merchant page can affect card data; SAQ A-EP or wider scope usually applies |
| Card data through merchant servers | Platform receives card numbers | Full scope; avoid |

*Example choice:* hosted payment fields with wallet buttons (for example Apple Pay and Google Pay
through the PSP) and redirect for alternative payment methods.

### 11.2 Controls

- PCI DSS v4.0.1 is the only active version (published June 2024; v4.0 retired at the end of
  2024). Map scope with PCI DSS Scoping and Segmentation (`compliance/pci-dss-scoping-segmentation`).
- In January 2025 the PCI SSC removed the payment page script requirements (6.4.3 and 11.6.1) and
  the related targeted risk analysis (12.3.1) from SAQ A, effective 31 March 2025, and added an eligibility criterion: the merchant confirms its site is not susceptible to
  script attacks that could affect its e-commerce systems. Keep evidence for that confirmation:
  content security policy, subresource integrity or script inventory, and tamper monitoring on
  checkout pages.
- Restrict who can change checkout page templates and tag manager containers; review third-party
  scripts on checkout pages at every release.
- Tokens from the PSP are stored in the commerce engine or PSP vault only; never log full PSP
  responses.
- Apply bot management, credential-stuffing defences and rate limits at the edge; see
  `security/threat-model` for the checkout threat model.

## 12. Vendor selection

<!-- Guidance: Score vendors per PBC on weighted criteria, with evidence from demos, proofs of concept and references. Pitfall: scoring features only, ignoring API limits, total cost and exit terms. -->

### 12.1 Criteria and weights

| Criterion | Weight | Evidence |
|---|---|---|
| Functional fit to capabilities in section 4 | 30% | Scripted demo; see `business/demo-script` |
| API and event quality (coverage, limits, webhooks, versioning) | 20% | Proof of concept; see `architecture/proof-of-concept` |
| Peak scalability and contracted limits | 20% | Load test in proof of concept, contract terms |
| Total cost of ownership over 5 years | 15% | TCO model; see `architecture/tco-analysis` |
| Vendor viability, ecosystem and exit terms | 15% | References, data export terms |

### 12.2 Worked example: commerce engine

| Vendor | Fit (30%) | API (20%) | Scale (20%) | TCO (15%) | Viability (15%) | Weighted score |
|---|---|---|---|---|---|---|
| Vendor A *(Example)* | 4 | 3 | 5 | 4 | 3 | 3.85 |
| Vendor B *(Example)* | 3 | 5 | 4 | 3 | 4 | 3.75 |
| Vendor C *(Example)* | 5 | 2 | 3 | 5 | 2 | 3.55 |

Scores use a 1 to 5 scale. Vendor A: 4 times 0.30 plus 3 times 0.20 plus 5 times 0.20 plus 4 times
0.15 plus 3 times 0.15 equals 3.85. A difference of 0.10 is within scoring noise; break the tie with
the proof-of-concept results and exit terms. Use the Vendor Evaluation Scorecard
(`business/vendor-evaluation-scorecard`) and the Build vs Buy Analysis
(`architecture/build-vs-buy-analysis`).

### 12.3 Suite versus composable check

| Question | Suite fits better when | Composable fits better when |
|---|---|---|
| How often does the experience change? | Quarterly or less | Weekly or more |
| How many markets, brands and channels? | One or two | Many, with local variation |
| How strong is in-house engineering? | Small team, integrator dependent | Product teams able to own a BFF and integrations |
| How unusual is the business model? | Standard B2C retail | Subscriptions, marketplaces, B2B contracts, bundles |

## 13. Migration from the monolith

<!-- Guidance: Move capability by capability behind a routing layer, starting where value is high and coupling is low. Pitfall: a big-bang replatform timed just before peak season. -->

| Phase | Scope | Approach | Exit criteria | Timing |
|---|---|---|---|---|
| MIG-001 *(Example)* | Edge, CDN and routing layer in front of the monolith | Strangler entry point | All traffic through new edge | [Quarter] |
| MIG-002 *(Example)* | CMS and content pages | New frontend serves content routes; monolith serves the rest | Content team publishes without releases | [Quarter] |
| MIG-003 *(Example)* | Search and listing pages | New search, index fed from monolith catalogue then PIM | Search conversion at least equal to baseline in A/B test | [Quarter] |
| MIG-004 *(Example)* | PIM | Product data moved; publishing to monolith and new engine | Completeness rules met per channel | [Quarter] |
| MIG-005 *(Example)* | Commerce engine, cart and checkout, one market | Market-by-market cutover; accounts and open carts migrated | Conversion and payment success within tolerance for 4 weeks | [Quarter, not within 8 weeks of peak] |
| MIG-006 *(Example)* | OMS | Orders from both engines into new OMS | Order reconciliation clean for 4 weeks | [Quarter] |
| MIG-007 *(Example)* | Decommission monolith | Remaining markets, then switch-off | Zero traffic for 30 days, data archived | [Quarter] |

Keep URLs, redirects and structured data stable to protect search rankings; plan data moves with
the Data Migration Strategy (`architecture/data-migration-strategy`) and cutovers with the Cutover
Plan (`project/cutover-plan`).

## 14. Operating model, cost and governance

<!-- Guidance: Composable shifts work from upgrades to integration, vendor management and product ownership. Show who owns what and what it costs. Pitfall: no one owning the end-to-end journey across products. -->

### 14.1 Ownership

| Role | Responsibility |
|---|---|
| Commerce platform owner | End-to-end roadmap, vendor portfolio, architecture decisions |
| PBC product owners | Configuration, backlog and vendor relationship per PBC |
| Experience team | Frontend, BFF, performance budgets |
| Integration team | Event broker, iPaaS, data ownership matrix |
| Site reliability | Monitoring, peak readiness, incident response |
| Vendor manager | Contracts, limits, service levels, renewals and exit plans |

### 14.2 Cost model

| Cost line | Driver | Example basis *(Example)* |
|---|---|---|
| SaaS subscriptions | GMV share, orders, API calls, SKUs or seats per vendor | Model each vendor's pricing metric at forecast and peak volumes |
| Cloud for BFF, frontend and integration | Requests, compute, egress | FinOps tagging per PBC; see `ops/finops-cost-review` |
| CDN and edge | Requests and bandwidth | Peak months priced separately |
| Integration platform | Flows, messages, connectors | iPaaS tier |
| Teams | Product teams and platform team | Full-time equivalents per PBC |

### 14.3 Governance

- Architecture decisions go to the Architecture Decision Log (`architecture/architecture-decision-log`).
- A new PBC or replacement of a PBC needs an updated data ownership matrix and exit plan.
- Vendor service levels are tracked monthly against the Service Level Agreement template
  (`ops/service-level-agreement`).

## 15. Decisions, risks and traceability

<!-- Guidance: Summarise the decisions, the top risks and the trace from drivers to design elements. Pitfall: risk lists without dates or owners. -->

### 15.1 Decisions

| ADR | Decision | Status |
|---|---|---|
| ADR-001 *(Example)* | Hosted payment fields from the PSP; no card data in the platform | [Accepted] |
| ADR-002 *(Example)* | BFF per channel; browser never calls SaaS APIs directly | [Accepted] |
| ADR-003 *(Example)* | Separate OMS from commerce engine | [Accepted] |
| ADR-004 *(Example)* | Market-by-market migration, no cutover within 8 weeks of peak | [Proposed] |

### 15.2 Risks

| ID | Risk | Likelihood | Impact | Mitigation | Owner |
|---|---|---|---|---|---|
| RSK-001 *(Example)* | SaaS rate limits reached at peak | Medium | High | Contracted limits, caching, edge queue, peak test | [@commerce-architect] |
| RSK-002 *(Example)* | Integration sprawl and unclear data ownership | High | High | Data ownership matrix, integration team, event catalogue | [@integration-lead] |
| RSK-003 *(Example)* | Total subscription cost exceeds business case at growth | Medium | Medium | Model pricing metrics at 3-year volumes; negotiate caps | [@finance-lead] |
| RSK-004 *(Example)* | Third-party script on checkout compromised | Low | High | Script inventory, CSP, tamper monitoring, SAQ evidence | [@ciso] |
| RSK-005 *(Example)* | SEO traffic drop after URL changes | Medium | High | Redirect map and monitoring per migration phase | [@seo-lead] |

### 15.3 Traceability matrix

| Driver | Principles | PBCs | Sections | NFRs | Tests |
|---|---|---|---|---|---|
| DRV-001 *(Example)* | PRI-001, PRI-004 | PBC-10 | 7, 13 | NFR-002 | Deployment frequency metric |
| DRV-002 *(Example)* | PRI-003 | PBC-01, PBC-05, PBC-10 | 10 | NFR-001, NFR-003 | PRK-002 load test |
| DRV-003 *(Example)* | PRI-002, PRI-005 | PBC-01, PBC-02, PBC-04 | 4, 8 | NFR-004 | New market rehearsal |
| DRV-004 *(Example)* | PRI-004 | PBC-04 | 6.3 | NFR-001 | Content publishing test |
| DRV-005 *(Example)* | PRI-007 | PBC-06 | 11 | NFR-003 | SAQ evidence review |

## 16. Glossary and references

<!-- Guidance: Use short definitions in your own words and record the date you checked each source. -->

### 16.1 Glossary

| Term | Meaning in this document |
|---|---|
| BFF | Backend for frontend: a channel-specific API layer that composes capability APIs |
| CDP | Customer data platform that builds unified profiles and segments |
| Headless | Commerce or content system that returns data through APIs, with presentation built separately |
| MACH | Microservices, API-first, Cloud-native SaaS, Headless |
| OMS | Order management system that owns orders after placement |
| PBC | Packaged business capability: a business capability delivered as a product with its own data, APIs and events |
| PIM | Product information management system |
| PSP | Payment service provider |
| SAQ | PCI DSS self-assessment questionnaire |

### 16.2 References

| Reference | Version or date checked | Use |
|---|---|---|
| MACH Alliance, MACH Explained and The Alliance pages, machalliance.org | Checked October 2026 | Section 3 |
| PCI Security Standards Council, PCI DSS v4.0.1, pcisecuritystandards.org | Published 11 June 2024 | Section 11 |
| PCI SSC blog, important updates for merchants validating to SAQ A | 30 January 2025 | Section 11 |
| [Vendor documentation for rate limits and service levels] | [Date checked] | Sections 6, 10 |
| [Internal standards] | [Version] | [Use] |

## Standard and licence note

Structure aligned with the MACH principles as described by the MACH Alliance and with the PCI DSS
v4.0.1 scoping approach for e-commerce payment capture. PCI DSS is a PCI Security Standards Council
standard; this template cites requirement numbers and self-assessment questionnaire names only and
reproduces no requirement text. MACH Alliance material is referenced by name; no text is copied.
Product categories are named generically; any vendor or product names you add are trademarks of
their owners, and this template is not affiliated with or endorsed by them. This template is
original text written for this collection. Check the current official versions before use. This is
a documentation format, not legal or compliance advice. Template licence: MIT.