# Integration Design: [Programme or solution name]

> Complete design for the integrations between a set of applications:
> landscape, catalogue of interfaces, a detailed specification per
> integration (pattern, trigger, volume, mapping, transformation, error
> handling, retries, idempotency, monitoring), canonical data model,
> security, service levels, testing and cutover. Patterns are named using
> the vocabulary of *Enterprise Integration Patterns* (Hohpe and Woolf).
> Replace every `[bracketed]` value and every row marked *Example*.
> Worked examples integrate an e-commerce platform with an ERP, a
> warehouse system and a CRM.

<!--
Guidance: How to use this template
- Build the catalogue (section 3) first and agree it with every system
  owner. Integrations missing from the catalogue are found during cutover,
  which is the most expensive time to find them.
- Name the pattern for each integration (Message Channel, Content-Based
  Router, Message Translator, Aggregator and so on). A shared vocabulary
  shortens design reviews and makes the error handling obvious.
- Write the field mapping with the business owner of the target data, not
  only with developers. Most integration defects are mapping defects.
- Keep one subsection per integration in section 5 with the same layout.
-->

## Document control

<!-- Guidance: Identify the programme, the integration platform and the owners of the systems being connected. -->

| Field | Value |
|---|---|
| Document ID | [INT-DES-COMMERCE-001] |
| Programme / solution | [Commerce replatforming] |
| Integration platform | [iPaaS / ESB / message broker / custom services] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Integration architect | [@integration-architect] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Related | [Solution architecture], [Data dictionary], [Test plan], [Cutover plan] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Integration architect | [@name] | [Approved / Changes requested] | YYYY-MM-DD |
| ERP system owner | [@name] | [Decision] | YYYY-MM-DD |
| Warehouse system owner | [@name] | [Decision] | YYYY-MM-DD |
| Security | [@name] | [Decision] | YYYY-MM-DD |
| Business data owner | [@name] | [Decision] | YYYY-MM-DD |

## Revision history

<!-- Guidance: Record integrations added or changed and mapping changes. -->

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft of catalogue |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* INT-03 changed from nightly file to near real-time events |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved for build |

## Contents

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

1. [Introduction](#1-introduction)
2. [Integration landscape](#2-integration-landscape)
3. [Integration catalogue](#3-integration-catalogue)
4. [Integration principles and patterns](#4-integration-principles-and-patterns)
5. [Integration specifications](#5-integration-specifications)
6. [Canonical data model](#6-canonical-data-model)
7. [Error handling and operations](#7-error-handling-and-operations)
8. [Security](#8-security)
9. [Service levels](#9-service-levels)
10. [Testing](#10-testing)
11. [Cutover and transition](#11-cutover-and-transition)
12. [Appendices](#12-appendices)

## 1. Introduction

<!-- Guidance: Why the integrations exist, what is in scope and the constraints that shape the design. -->

### 1.1 Purpose

[What this document decides. Example: "This document specifies how the new
commerce platform exchanges orders, products, stock and customers with
the ERP, warehouse management system and CRM, and how those exchanges
are monitored and cut over from the legacy platform."]

### 1.2 Scope

| In scope | Out of scope |
|---|---|
| *Example:* Order, product, price, stock, customer and shipment flows | Finance consolidation between ERP instances |
| *Example:* Migration of open orders at cutover | Historical order migration (separate data migration plan) |
| [Item] | [Item] |

### 1.3 Constraints and assumptions

- [Example: ERP exposes only SOAP services and nightly file exports; no
  event capability before its upgrade in Q4.]
- [Example: Warehouse system processes orders in waves every 15 minutes.]
- [Example: All integrations run on the existing integration platform; no
  new middleware licences.]

## 2. Integration landscape

<!-- Guidance: One picture of every system and every integration between them, numbered as in the catalogue. Show the integration platform explicitly. -->

The landscape below shows the systems and the numbered integrations
(INT-nn) that connect them through the integration platform.

```mermaid
flowchart LR
  shop["Commerce platform"]
  erp["ERP"]
  wms["Warehouse management"]
  crm["CRM"]
  carrier["Carrier API"]
  ip{{"Integration platform"}}
  erp -->|"INT-01 products"| ip --> shop
  erp -->|"INT-02 prices"| ip
  wms -->|"INT-03 stock"| ip
  shop -->|"INT-04 orders"| ip --> erp
  ip -->|"INT-04 orders"| wms
  wms -->|"INT-05 shipments"| ip
  ip -->|"INT-06 labels"| carrier
  shop -->|"INT-07 customers"| ip --> crm
```

| System | Role | Owner | Technology | Integration capabilities |
|---|---|---|---|---|
| Commerce platform | Storefront, cart, orders | [@owner] | SaaS | REST API, webhooks |
| ERP | Products, prices, finance | [@owner] | [Product, version] | SOAP services, SFTP files |
| Warehouse management | Picking, packing, shipping | [@owner] | [Product] | REST API, message queue |
| CRM | Customer profiles, marketing consent | [@owner] | SaaS | REST API, bulk API |
| Carrier | Labels, tracking | External | REST API | REST API, webhooks |

## 3. Integration catalogue

<!-- Guidance: One row per integration. This table is the inventory used for planning, testing, monitoring and cutover. -->

| ID | Name | Source | Target | Pattern(s) | Style | Trigger | Frequency | Volume (peak) | Priority |
|---|---|---|---|---|---|---|---|---|---|
| INT-01 | Product master | ERP | Commerce | File Transfer, Message Translator | Batch | Schedule | Nightly 02:00 | 60 000 products | High |
| INT-02 | Price update | ERP | Commerce | Polling Consumer, Message Translator | Near real-time | Change poll | Every 5 min | 5 000 changes/hour | High |
| INT-03 | Stock level | WMS | Commerce | Event Message, Aggregator | Event | Stock movement | Continuous | 30 events/s | Critical |
| INT-04 | Order export | Commerce | ERP, WMS | Event Message, Recipient List, Message Translator | Event | Order paid | Continuous | 15 orders/s | Critical |
| INT-05 | Shipment confirmation | WMS | Commerce, ERP | Event Message, Publish-Subscribe Channel | Event | Parcel dispatched | Continuous | 12/s | High |
| INT-06 | Carrier label | Integration platform | Carrier | Request-Reply | Synchronous | Pack complete | On demand | 12/s | Critical |
| INT-07 | Customer sync | Commerce | CRM | Event Message, Content Enricher | Event | Account change | Continuous | 3/s | Medium |
| [INT-nn] | [Name] | [Source] | [Target] | [Patterns] | [Style] | [Trigger] | [Frequency] | [Volume] | [Priority] |

## 4. Integration principles and patterns

<!-- Guidance: Rules every integration follows, and the patterns from the shared vocabulary with how they are implemented on this platform. -->

### 4.1 Principles

| ID | Principle | Consequence |
|---|---|---|
| IP-01 | Systems are loosely coupled through the integration platform | No point-to-point database links |
| IP-02 | Each data entity has one system of record | Section 6.2 lists the owner of each entity |
| IP-03 | Prefer events for changes, request-reply only when the caller needs the answer now | Stock and orders are events; labels are request-reply |
| IP-04 | Every message is traceable end to end | Correlation ID on every message and log entry |
| IP-05 | Every consumer is idempotent | Duplicates never create duplicate business records |
| IP-06 | Translation to and from the canonical model happens at the edges | Source and target adapters own their mappings |

### 4.2 Pattern catalogue

| Pattern | Used for | Implementation on this platform |
|---|---|---|
| Message Channel | Transport between producer and consumer | Broker topic or queue per flow |
| Publish-Subscribe Channel | One event, several consumers | Topic with one subscription per consumer |
| Event Message | Notify that something happened | CloudEvents-style envelope, canonical payload |
| Request-Reply | Synchronous call needing an answer | HTTPS call with timeout and correlation ID |
| Message Translator | Convert formats and structures | Mapping in adapter, defined in 5.x mapping tables |
| Content Enricher | Add data the source does not send | Lookup to system of record, cached |
| Content-Based Router | Route by message content | Rules on country or order type |
| Recipient List | Send to a computed list of targets | Order export to ERP and WMS |
| Aggregator | Combine related messages | Stock events aggregated per SKU per 10 s window |
| Idempotent Receiver | Ignore duplicates | Deduplication store keyed by message ID |
| Dead Letter Channel | Hold messages that cannot be delivered | Per-flow dead-letter queue |
| Polling Consumer | Read from a source without events | Scheduled query on change timestamp |
| File Transfer | Bulk exchange | SFTP with checksum and control file |

## 5. Integration specifications

<!-- Guidance: One subsection per catalogue entry, same layout every time. Fill all rows; write "not applicable" with a reason when a row does not apply. -->

### 5.1 INT-04 Order export

This integration sends every paid order to the ERP for invoicing and to
the warehouse for fulfilment.

#### 5.1.1 Overview

| Attribute | Value |
|---|---|
| Purpose | Make paid orders available for fulfilment and invoicing |
| Source / target | Commerce platform to ERP and WMS |
| Patterns | Event Message, Recipient List, Message Translator, Idempotent Receiver, Dead Letter Channel |
| Trigger | Commerce webhook `order.paid` |
| Frequency and volume | Continuous; 3 orders/s average, 15/s peak; 250 000 per month |
| Message size | 2 to 20 KB |
| Latency target | Order in WMS within 60 s at p95 |
| Ordering | Per order only (key `orderId`) |

#### 5.1.2 Flow

The sequence shows the happy path and the duplicate case.

```mermaid
sequenceDiagram
  participant C as Commerce
  participant IP as Integration platform
  participant E as ERP
  participant W as WMS
  C->>IP: Webhook order.paid (orderId, eventId)
  IP->>IP: Verify signature, store eventId
  IP->>C: GET /orders/{orderId} (enrich)
  IP->>IP: Translate to canonical Order
  par To ERP
    IP->>E: SOAP CreateSalesOrder
    E-->>IP: ERP order number
  and To WMS
    IP->>W: POST /outbound-orders
    W-->>IP: 201 Created
  end
  C->>IP: Duplicate webhook (same eventId)
  IP-->>C: 200 OK, ignored
```

#### 5.1.3 Field mapping

| # | Source field (Commerce) | Canonical field | Target field (ERP) | Target field (WMS) | Rule |
|---|---|---|---|---|---|
| 1 | `id` | `order.externalId` | `CustomerPO` | `reference` | Copy |
| 2 | `created_at` | `order.orderedAt` | `DocDate` | `orderDate` | Convert RFC 3339 UTC to ERP local date `YYYYMMDD` |
| 3 | `customer.id` | `order.customerRef` | `SoldTo` | not sent | Lookup ERP customer number via cross-reference table XR-01 |
| 4 | `line_items[].sku` | `lines[].sku` | `Material` | `sku` | Upper case; strip spaces |
| 5 | `line_items[].quantity` | `lines[].quantity` | `TargetQty` | `qty` | Integer |
| 6 | `line_items[].price` | `lines[].unitPrice` | `NetPrice` | not sent | Decimal string to ERP decimal with 2 places |
| 7 | `shipping_address.country_code` | `shipTo.country` | `Country` | `country` | ISO 3166-1 alpha-2 unchanged |
| 8 | `shipping_lines[0].code` | `shipping.method` | `ShipCond` | `serviceLevel` | Value map VM-01 |
| 9 | none | `order.salesOrg` | `SalesOrg` | not sent | Constant `1000` for EU web orders |
| [n] | [Source] | [Canonical] | [Target] | [Target] | [Rule] |

Value map VM-01 (shipping method):

| Commerce code | Canonical | ERP `ShipCond` | WMS `serviceLevel` |
|---|---|---|---|
| `standard` | `STANDARD` | `01` | `STD` |
| `express` | `EXPRESS` | `02` | `EXP` |
| `click_collect` | `PICKUP` | `05` | `PCK` |

#### 5.1.4 Transformation and validation rules

- Reject (to dead letter) any order whose total does not equal the sum of
  lines plus shipping minus discounts, within 0.01.
- Split orders with more than [999] lines because the ERP limit is 999.
- Orders with country outside [EU list] are routed by a Content-Based
  Router to the export queue for manual customs handling.

#### 5.1.5 Error handling, retries and idempotency

| Error | Detection | Handling |
|---|---|---|
| ERP unavailable or timeout (30 s) | SOAP fault or timeout | Retry 5 times with backoff 1, 2, 4, 8, 16 min, then dead letter and alert |
| ERP business error (unknown material) | SOAP fault code | No retry; dead letter; ticket to product data team |
| WMS 409 Conflict | HTTP status | Treat as success (order already exists) |
| WMS 5xx | HTTP status | Retry as for ERP |
| Duplicate webhook | `eventId` already stored | Acknowledge, no processing |

Idempotency: the integration stores `eventId` for 7 days; ERP calls carry
`CustomerPO` and the ERP rejects duplicates on it; WMS uses `reference` as
a unique key.

#### 5.1.6 Monitoring

| Metric | Threshold | Action |
|---|---|---|
| Orders received versus exported per hour | Difference above 0.5% | Alert integration support |
| End-to-end latency p95 | Above 60 s for 15 min | Alert |
| Dead letter count | Any message | Ticket; above 20 in 1 hour pages on call |

### 5.2 INT-03 Stock level

| Attribute | Value |
|---|---|
| Purpose | Keep available stock in the storefront accurate to prevent overselling |
| Patterns | Event Message, Aggregator, Message Translator |
| Trigger | WMS stock movement event |
| Frequency and volume | 30 events/s peak; aggregated to at most one update per SKU every 10 s |
| Mapping | `item_code` to `sku`; `qty_available - qty_allocated` to `available` |
| Error handling | Retry 3 times; on failure the next aggregate supersedes; nightly full reconciliation file corrects drift |
| Idempotency | Updates are absolute quantities with a sequence number; older sequence numbers are ignored |
| Monitoring | Reconciliation differences above 1% of SKUs raise an alert |

### 5.3 [INT-nn] [Integration name]

[Repeat the layout of 5.1 (overview, flow, mapping, rules, errors,
monitoring) for each remaining catalogue entry.]

## 6. Canonical data model

<!-- Guidance: The shared representation used inside the integration platform. Keep it small: only entities that cross more than two systems. -->

### 6.1 Canonical entities

The canonical model below is the form messages take inside the
integration platform; adapters translate to and from it.

```mermaid
classDiagram
  class Order {
    externalId: string
    orderedAt: datetime
    customerRef: string
    currency: string
    total: decimal
  }
  class OrderLine {
    sku: string
    quantity: int
    unitPrice: decimal
  }
  class Address {
    name: string
    line1: string
    city: string
    postalCode: string
    country: string
  }
  class Customer {
    customerRef: string
    email: string
    marketingConsent: bool
  }
  Order "1" --> "1..*" OrderLine
  Order "1" --> "1" Address : shipTo
  Order "*" --> "1" Customer
```

### 6.2 Systems of record

| Entity | System of record | Consumers | Key | Cross-reference |
|---|---|---|---|---|
| Product | ERP | Commerce, WMS | `sku` | n/a |
| Price | ERP | Commerce | `sku` + price list | n/a |
| Stock | WMS | Commerce | `sku` + site | n/a |
| Order | Commerce (until paid), then ERP | ERP, WMS | `externalId` | XR-02 Commerce ID to ERP order number |
| Customer | Commerce | CRM, ERP | `customerRef` | XR-01 Commerce ID to ERP customer number |

## 7. Error handling and operations

<!-- Guidance: Common rules for all integrations, so each specification only lists exceptions. -->

| Topic | Standard |
|---|---|
| Retry policy | Exponential backoff, maximum 5 attempts, then Dead Letter Channel |
| Dead letter handling | Reviewed daily by integration support; resubmission through the platform console with audit trail |
| Correlation | `correlationId` generated at entry, propagated to every hop and log |
| Logging | Message metadata always; payloads only in non-production or masked |
| Reprocessing | Every flow supports replay from a given time for [7 days] |
| Support model | L1 integration support [hours], L2 platform team, L3 system owners |
| Runbooks | One per integration, linked from the monitoring dashboard |

## 8. Security

<!-- Guidance: Authentication, transport, data protection and access to the integration platform itself. -->

| Integration | Authentication | Transport | Data classification | Notes |
|---|---|---|---|---|
| INT-04 inbound webhook | HMAC signature with shared secret, rotated 90 days | HTTPS | Personal | Timestamp checked within 5 min |
| INT-04 to ERP | Client certificate | TLS over private link | Personal | Service account with create-order rights only |
| INT-01 file | SSH key per partner | SFTP | Internal | Files encrypted at rest; deleted after 30 days |
| INT-06 carrier | OAuth 2.0 client credentials | HTTPS | Personal (address) | Outbound allow-list |
| [INT-nn] | [Method] | [Transport] | [Class] | [Notes] |

General controls: credentials in the secrets manager; least-privilege
service accounts per integration; platform console access by SSO with
MFA; audit log of resubmissions and mapping changes.

## 9. Service levels

<!-- Guidance: What each integration commits to and how it is measured. Align with the business processes that depend on it. -->

| ID | Availability | Latency target | Data freshness | Support hours | Measured by |
|---|---|---|---|---|---|
| INT-03 | 99.9% | p95 under 30 s | Stock no older than 60 s | 24x7 | Platform metrics |
| INT-04 | 99.9% | p95 under 60 s | n/a | 24x7 | End-to-end tracking |
| INT-01 | 99% of nightly runs complete by 05:00 | n/a | Daily | Business hours | Job monitor |
| [INT-nn] | [Target] | [Target] | [Target] | [Hours] | [Method] |

Overall flow availability for a chain of $n$ independent steps with
availability $a_i$:

$$
A_{flow} = \prod_{i=1}^{n} a_i
$$

For INT-04 with Commerce (99.95%), platform (99.95%) and ERP (99.9%), the
result is about 99.80%, so retries and queuing are needed to meet the
99.9% target.

## 10. Testing

<!-- Guidance: Test levels, environments, data and the evidence that each integration is ready. -->

| Level | Scope | Environment | Exit criterion |
|---|---|---|---|
| Unit | Mappings and transformation rules | Developer / CI | 100% of mapping rows covered by tests |
| Contract | Message schemas and API contracts against each system | CI with mocks | All contracts pass |
| System integration | End-to-end flows across real test systems | SIT | All catalogue flows pass happy path and listed error cases |
| Performance | Peak volume plus 50% | Performance environment | Latency targets met; no message loss |
| Resilience | Target outage, duplicate and out-of-order messages | SIT | Recovery without data loss or duplicates |
| User acceptance | Business scenarios across systems | UAT | Sign-off by process owners |

| Test case | Integration | Scenario | Expected result |
|---|---|---|---|
| TC-INT04-01 | INT-04 | *Example:* Paid order with 3 lines, standard shipping | ERP and WMS orders created within 60 s; values match mapping |
| TC-INT04-05 | INT-04 | *Example:* Same webhook delivered twice | One order in each target |
| TC-INT04-07 | INT-04 | *Example:* ERP down for 20 minutes | Orders delivered after recovery in order |
| [TC-nn] | [INT] | [Scenario] | [Result] |

## 11. Cutover and transition

<!-- Guidance: How integrations move from the legacy setup to the new one without losing or duplicating data. Include go and no-go criteria and rollback. -->

| Step | Activity | Owner | Timing | Verification |
|---|---|---|---|---|
| 1 | Freeze mapping and configuration changes | Integration lead | T-7 days | Change freeze notice |
| 2 | Load product, price and customer masters (INT-01, INT-07 bulk) | Data team | T-3 days | Counts and checksums match |
| 3 | Run legacy and new stock flows in parallel, compare | Integration team | T-3 to T-1 | Difference under 0.1% |
| 4 | Stop legacy order export; drain queues | Integration team | T-0 22:00 | Queue depth zero |
| 5 | Migrate open orders | Data team | T-0 22:30 | Count reconciled |
| 6 | Enable new INT-04 and INT-05 | Integration team | T-0 23:30 | Test order end to end |
| 7 | Go / no-go decision | Cutover manager | T-0 23:45 | Criteria below |
| 8 | Hypercare with extended monitoring | All | T+1 to T+14 days | Daily reconciliation report |

Go / no-go criteria: all critical integrations pass smoke tests; no open
severity 1 or 2 defects; reconciliation within tolerance. Rollback:
re-enable the legacy export and replay orders captured since step 6 from
the integration platform store.

## 12. Appendices

<!-- Guidance: Glossary, cross-reference tables and references. -->

### 12.1 Glossary

| Term | Meaning |
|---|---|
| Canonical data model | Shared message format used inside the integration platform |
| System of record | The system whose value of a data item is authoritative |
| Cross-reference table | Mapping of identifiers between systems |
| Hypercare | Period of increased support after go-live |
| [Term] | [Meaning] |

### 12.2 References

| Reference | Use |
|---|---|
| Hohpe, G. and Woolf, B., *Enterprise Integration Patterns*, Addison-Wesley, 2003 | Pattern names in sections 3 to 5 |
| [System API documentation] | Interface details |
| [Data dictionary] | Field definitions |

## Standard and licence note

Based on common industry practice for integration design. Pattern names
follow the vocabulary of Gregor Hohpe and Bobby Woolf, *Enterprise
Integration Patterns: Designing, Building, and Deploying Messaging
Solutions* (Addison-Wesley, 2003); only the pattern names are used, and
no text or diagrams from the book are reproduced. Original text written
for this collection. Template licence: MIT.