# Integration Strategy: [Organisation name]

> Enterprise-level strategy for how applications, data, partners and
> people are connected: business drivers, the current integration
> landscape and its debt, integration principles, the styles the
> organisation uses (synchronous API, events, batch and file, B2B and
> EDI, data replication), a layered API model, the integration platform
> decision (iPaaS, enterprise service bus, event broker, API gateway,
> managed file transfer), canonical model policy, reuse and catalogue,
> security, operating model and centre of excellence, funding, roadmap
> and KPIs. Patterns are named with the vocabulary of Enterprise
> Integration Patterns (Hohpe and Woolf, 2003); asynchronous contracts
> follow AsyncAPI 3.1.0 and CloudEvents 1.0.2, synchronous contracts
> follow the OpenAPI Specification 3.2. Replace every `[bracketed]` value
> and every row marked *Example*.

<!--
Guidance: How to use this template
- Write one strategy per organisation or major business unit. It sets
  rules and choices that every project inherits; it does not design
  individual interfaces. Per-interface design belongs in Integration
  Design (`architecture/integration-design`) and Interface Control
  Document (`architecture/interface-control-document`).
- Fill section 1 (drivers) and section 2 (landscape and debt) first.
  Every principle, platform choice and roadmap item must trace back to a
  driver or a debt item; the traceability matrix in section 14.3 proves it.
- Section 4 (style selection) and section 8 (platform decision) are the
  heart of the document. Settle them with the architecture board and
  record each choice in the Architecture Decision Log
  (`architecture/architecture-decision-log`).
- Related documents: API Design Guidelines (`architecture/api-design-guidelines`),
  Event-Driven Architecture Design (`architecture/event-driven-architecture-design`),
  API Management Platform Design (`architecture/api-management-platform-design`),
  B2B, EDI and File Transfer Design (`architecture/b2b-edi-file-transfer-design`),
  Technology Selection (`architecture/technology-selection`),
  Architecture Roadmap (`architecture/architecture-roadmap-transition`).
- Worked examples use a mid-sized retailer with an ERP, an e-commerce
  platform, a warehouse system, 120 suppliers on EDI and a mobile app.
-->

## Document control

<!-- Guidance: Identify the strategy, its scope (whole enterprise or one business unit) and its planning horizon. A change of platform or of the layered model is a new major version. -->

| Field | Value |
|---|---|
| Document ID | [INT-STRAT-001] |
| Organisation or business unit | [Name] |
| Planning horizon | [YYYY to YYYY] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@head-of-integration] |
| Approvers/reviewers | [@chief-architect], [@ciso], [@cfo-delegate], [@head-of-applications] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Review cycle | [Yearly, or on a major platform change] |
| Related documents | [Enterprise architecture vision], [Application portfolio], [Data strategy] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Chief architect | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Chief information security officer | [@name] | [Decision] | YYYY-MM-DD |
| Head of applications | [@name] | [Decision] | YYYY-MM-DD |
| Finance | [@name] | [Decision] | YYYY-MM-DD |
| Architecture board | [@name] | [Decision] | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved; iPaaS plus event broker chosen, ESB retirement planned |
| 1.1 | YYYY-MM-DD | [@name] | *Example:* Added B2B style rules after EDI provider review |

## Contents

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

1. [Purpose, scope and drivers](#1-purpose-scope-and-drivers)
2. [Current integration landscape](#2-current-integration-landscape)
3. [Integration principles](#3-integration-principles)
4. [Integration styles and selection](#4-integration-styles-and-selection)
5. [Layered API model](#5-layered-api-model)
6. [Pattern vocabulary](#6-pattern-vocabulary)
7. [Platform capabilities and options](#7-platform-capabilities-and-options)
8. [Platform decision](#8-platform-decision)
9. [Canonical data and contract policy](#9-canonical-data-and-contract-policy)
10. [Reuse, catalogue and lifecycle](#10-reuse-catalogue-and-lifecycle)
11. [Security and identity](#11-security-and-identity)
12. [Operating model and centre of excellence](#12-operating-model-and-centre-of-excellence)
13. [Funding and chargeback](#13-funding-and-chargeback)
14. [Roadmap and traceability](#14-roadmap-and-traceability)
15. [KPIs and measures](#15-kpis-and-measures)
16. [Risks, assumptions and decisions](#16-risks-assumptions-and-decisions)
17. [Glossary and references](#17-glossary-and-references)

## 1. Purpose, scope and drivers

<!-- Guidance: Say why the organisation needs an integration strategy now. Questions: what business change is blocked or slowed by integration today? Which regulations or partner demands force change? Pitfall: drivers written as technology wishes ("move to microservices") instead of business outcomes. -->

### 1.1 Purpose

This strategy sets how [Organisation name] connects its applications,
data, partners and channels for the planning horizon. It tells project
teams which integration styles to use, which platforms to build on,
which contracts and standards to follow, who owns what, and how
integration work is funded. It replaces ad hoc, project-by-project
integration choices with a small set of governed options.

### 1.2 Scope

| In scope | Out of scope |
|---|---|
| *Example:* All application-to-application, application-to-partner and channel-to-backend integration | Analytics pipelines inside the data platform (see Data Platform Architecture, `architecture/data-platform-architecture`) |
| *Example:* Integration platforms, contracts, security, operating model and funding | Network connectivity and firewall design |
| *Example:* B2B and EDI with suppliers, carriers and marketplaces | Robotic process automation of user interfaces |
| [Item] | [Item] |

### 1.3 Business drivers

| ID | Driver | Evidence | Integration implication |
|---|---|---|---|
| DRV-001 *(Example)* | Launch new sales channels in weeks, not quarters | Last two channels took 7 and 9 months, 60 % of effort was integration | Reusable product, price and stock APIs; self-service onboarding |
| DRV-002 *(Example)* | Real-time stock visibility across stores and online | Overselling incidents during peak; nightly batch stock feed | Event-based stock updates with seconds of latency |
| DRV-003 *(Example)* | ERP replacement planned in two years | ERP vendor end of mainstream support | Decouple consumers from the ERP behind stable system APIs |
| DRV-004 *(Example)* | Onboard 200 more suppliers with less manual work | Onboarding takes 6 weeks per partner | Partner self-service, standard EDI maps, test automation |
| DRV-005 *(Example)* | Reduce integration run cost | Two overlapping platforms and a legacy ESB licence | Platform consolidation |
| [DRV-NNN] | [Driver] | [Evidence] | [Implication] |

## 2. Current integration landscape

<!-- Guidance: Describe what exists today, honestly. Count interfaces by style and platform, name the hotspots, and list integration debt with its cost. Use Current State Assessment (`architecture/current-state-assessment`) if one exists. Pitfall: a landscape picture with no numbers, which cannot support a business case. -->

```mermaid
flowchart LR
  subgraph Channels
    WEB[E-commerce site]
    APP[Mobile app]
    POS[Store POS]
  end
  subgraph Core
    ERP[ERP]
    WMS[Warehouse system]
    CRM[CRM]
    PIM[Product information]
  end
  subgraph Partners
    SUP[Suppliers EDI]
    CAR[Carriers]
    MKT[Marketplaces]
  end
  WEB -- point to point REST --> ERP
  APP -- custom backend --> ERP
  POS -- nightly files --> ERP
  ERP -- legacy ESB --> WMS
  ERP -- DB link --> CRM
  PIM -- CSV over SFTP --> WEB
  SUP -- AS2 via EDI provider --> ERP
  CAR -- SOAP --> WMS
  MKT -- vendor connector --> WEB
```

### 2.1 Interface inventory

| Style | Count | Platform today | Share of incidents | Comment |
|---|---|---|---|---|
| Synchronous API (REST, SOAP) *(Example)* | 140 | Custom code, legacy ESB | 35 % | No common gateway; credentials embedded in code |
| Events and messaging *(Example)* | 25 | Queue product on premises | 10 % | Point-to-point queues, no schema governance |
| Batch and file *(Example)* | 210 | Scheduler and SFTP scripts | 40 % | Failures found next morning |
| B2B and EDI *(Example)* | 120 partners | Outsourced EDI provider | 10 % | Maps owned by provider |
| Database links and shared tables *(Example)* | 18 | Direct | 5 % | Block ERP upgrade |
| [Style] | [Count] | [Platform] | [Share] | [Comment] |

### 2.2 Integration debt

| ID | Debt item | Consequence | Estimated yearly cost | Linked driver |
|---|---|---|---|---|
| DEBT-001 *(Example)* | 18 direct database links into the ERP | ERP cannot be upgraded or replaced without breaking consumers | [USD 400,000 in rework risk] | DRV-003 |
| DEBT-002 *(Example)* | No central monitoring for file transfers | Late detection, manual reruns | [USD 150,000 in support effort] | DRV-002 |
| DEBT-003 *(Example)* | Legacy ESB on unsupported version | Security exposure, scarce skills | [USD 250,000 licence and support] | DRV-005 |
| [DEBT-NNN] | [Item] | [Consequence] | [Cost] | [DRV-NNN] |

## 3. Integration principles

<!-- Guidance: Write principles that rule options out. Each needs a rationale and a consequence that a reviewer can check. Limit yourself to eight to twelve. Pitfall: "use best practice" principles that never decide anything. -->

| ID | Principle | Rationale | Consequence for projects |
|---|---|---|---|
| INP-001 *(Example)* | No consumer integrates directly with another application's database | Shared schemas freeze both sides | Database links are forbidden for new work; existing ones are on the retirement roadmap |
| INP-002 *(Example)* | Publish business events for every significant state change of a core entity | Consumers react without polling; producers stay unaware of consumers | Core systems emit events through the outbox or CDC (section 4) |
| INP-003 *(Example)* | Every interface has a machine-readable contract under version control | Contracts enable testing, catalogue and change control | OpenAPI for HTTP, AsyncAPI for events, schema files for batch and EDI maps |
| INP-004 *(Example)* | Reuse before build: check the catalogue first | Duplicate interfaces multiply run cost | Design review asks for the catalogue search result |
| INP-005 *(Example)* | Integration logic is thin; business rules live in the owning application | Logic in middleware becomes an unowned second system | Orchestration only when it spans several owners (process layer, section 5) |
| INP-006 *(Example)* | Asynchronous by default across domain boundaries, synchronous where a caller needs an immediate answer | Limits coupling of availability | Style decision tree in section 4.2 |
| INP-007 *(Example)* | Secure every interface by default with authenticated, encrypted transport | Internal networks are not trusted | Zero trust rules in section 11 |
| INP-008 *(Example)* | Observable end to end: every message carries a correlation identifier | Fault finding across hops | Trace context propagated through all platforms |
| [INP-NNN] | [Principle] | [Rationale] | [Consequence] |

## 4. Integration styles and selection

<!-- Guidance: Define each style the organisation supports, when to use it and when not to. Then give a decision tree that a project architect can follow in five minutes. Pitfall: allowing every style everywhere, which recreates the sprawl you are trying to remove. -->

### 4.1 Supported styles

| Style | Use when | Avoid when | Contract standard | Default platform |
|---|---|---|---|---|
| Synchronous request and response API | A caller needs an answer now (query, validation, command with immediate result) | The callee is slow, often unavailable, or the caller does not need the answer | OpenAPI 3.2 | API gateway plus iPaaS or service runtime |
| Event notification and event-carried state transfer | Many consumers need to know that something happened; producers must not depend on consumers | A reply is required in the same interaction | AsyncAPI 3.1.0 with CloudEvents 1.0.2 envelope | Event broker |
| Asynchronous command (queue) | One known receiver must do work reliably and at its own pace | Several independent consumers need the same fact | AsyncAPI 3.1.0 | Message queue on the event broker |
| Batch and file | Large volumes, period-end processing, systems that only accept files | Latency below [15 minutes] is needed | File layout specification with schema | Managed file transfer and scheduler |
| B2B and EDI | External trading partners using X12, EDIFACT or industry XML | Partner offers a modern API that meets the need | Standard message plus partner implementation guide | B2B gateway or EDI provider |
| Data replication and change data capture | Copying data sets for read models, search or analytics | Cross-domain business processes (use events instead) | Change event schema | CDC tooling to the event broker |
| [Style] | [Use when] | [Avoid when] | [Contract] | [Platform] |

### 4.2 Style decision tree

```mermaid
flowchart TB
  START[New integration need] --> EXT{External trading partner?}
  EXT -- yes --> PSTD{Partner uses EDI or files?}
  PSTD -- yes --> B2B[B2B and EDI style]
  PSTD -- no --> EXPAPI[Partner API via API management]
  EXT -- no --> REPLY{Does the caller need an answer in the same interaction?}
  REPLY -- yes --> SYNC[Synchronous API]
  REPLY -- no --> MANY{More than one consumer, now or likely?}
  MANY -- yes --> EVT[Event publish and subscribe]
  MANY -- no --> VOL{Bulk volume or file-only system?}
  VOL -- yes --> FILE[Batch and file via MFT]
  VOL -- no --> CMD[Asynchronous command on a queue]
```

Record any departure from the tree as an exception in the design review with the reason and an expiry date.

### 4.3 Getting events out of core systems

Core applications that cannot publish events natively use one of two
approved techniques. The transactional outbox pattern writes the
business change and the outgoing message in the same local transaction;
a relay then publishes the message, so an event is emitted only when the
change commits. Log-based change data capture reads the database
transaction log and turns committed changes into change events; it needs
no application change but exposes table structure, so a translation step
must turn row changes into business events before they leave the
owning domain. System Design: CDC Pipeline (`system-design/design-cdc-pipeline`)
covers the mechanics.

## 5. Layered API model

<!-- Guidance: Decide whether the organisation adopts a layered model for APIs and how strictly. The three-layer split into system, process and experience APIs is popularised as "API-led connectivity" by MuleSoft; the idea is vendor-neutral and works on any platform. Pitfall: forcing three layers on every interface, which adds latency and cost with no reuse benefit. -->

```mermaid
flowchart TB
  subgraph Experience layer
    XW[Web storefront API]
    XM[Mobile app API]
    XP[Partner portal API]
  end
  subgraph Process layer
    PO[Order placement]
    PS[Stock availability]
  end
  subgraph System layer
    SE[ERP system API]
    SW[WMS system API]
    SC[CRM system API]
  end
  XW --> PO
  XM --> PO
  XM --> PS
  XP --> PS
  PO --> SE
  PO --> SC
  PS --> SW
  PS --> SE
```

| Layer | Purpose | Owned by | Change rate | Rules |
|---|---|---|---|---|
| System | Expose one system of record in a stable, cleaned-up contract that hides its internals | Team that owns the application | Low | One system API per system and entity; no business orchestration; shields consumers from replacement of the system |
| Process | Combine system APIs and events into a business capability used by several channels | Domain or capability team | Medium | Owns orchestration and cross-system rules; no channel-specific formatting |
| Experience | Shape data for one channel or consumer group | Channel team | High | May aggregate, filter and paginate for its client; no direct call to system APIs unless an exception is approved under section 5.1 |

### 5.1 When to skip a layer

| Situation | Allowed shortcut | Condition |
|---|---|---|
| *Example:* Single consumer, simple read of one system | Experience calls system API directly | Logged as an exception; revisited when a second consumer appears |
| *Example:* Internal batch job | No experience layer | Job uses process or system API |
| *Example:* Event-driven flow | Layers apply to request and response only; events follow section 4 | Event producers are owners of the system of record |
| [Situation] | [Shortcut] | [Condition] |

## 6. Pattern vocabulary

<!-- Guidance: Agree a shared pattern vocabulary so that designs, reviews and the catalogue use the same words. Use the pattern names from Enterprise Integration Patterns; do not copy the book's text. Pitfall: each team inventing its own names for the same thing. -->

The organisation uses the pattern names catalogued at
enterpriseintegrationpatterns.com. The table lists the patterns that
designs must name explicitly and the house rule for each.

| Pattern (EIP name) | House rule |
|---|---|
| Publish-Subscribe Channel | Default channel type for business events; one topic per event family |
| Point-to-Point Channel | Used for asynchronous commands to one receiver |
| Guaranteed Delivery | Required for all business events and commands; brokers persist messages before acknowledging |
| Dead Letter Channel | Every consumer has one; alerts fire on first arrival |
| Idempotent Receiver | Every consumer of at-least-once channels deduplicates on event ID |
| Correlation Identifier | Every message and API call carries a correlation ID propagated end to end |
| Content-Based Router | Allowed in the process layer; routing rules are versioned with the flow |
| Message Translator and Normalizer | Mapping to and from canonical or partner formats lives at the edge of the platform |
| Canonical Data Model | Applied per domain only, see section 9 |
| Claim Check | Payloads above [256 KB] are stored in object storage and referenced by URI |
| Aggregator, Splitter, Resequencer | Allowed in process flows with explicit timeout and completion rules |
| Process Manager | Long-running orchestration only on the approved workflow runtime |
| Wire Tap and Message Store | Used for audit and replay; subject to retention rules in section 11 |
| Competing Consumers | Standard scaling technique for queues |

## 7. Platform capabilities and options

<!-- Guidance: List the capabilities the organisation needs before naming products. Then compare platform categories against them. Pitfall: choosing a product first and then discovering that file transfer or B2B is missing. -->

### 7.1 Required capabilities

| ID | Capability | Needed by styles | Priority |
|---|---|---|---|
| CAP-001 *(Example)* | API gateway with policy enforcement, quotas and analytics | Synchronous API | Must |
| CAP-002 *(Example)* | Developer portal and API catalogue | Synchronous API, events | Must |
| CAP-003 *(Example)* | Low-code integration flows with connectors to SaaS and ERP | Synchronous API, batch | Must |
| CAP-004 *(Example)* | Durable event broker with retention and replay | Events, commands, CDC | Must |
| CAP-005 *(Example)* | Schema registry with compatibility checks | Events | Must |
| CAP-006 *(Example)* | Managed file transfer with scheduling, checksums and audit | Batch and file | Must |
| CAP-007 *(Example)* | B2B gateway: AS2, AS4, SFTP, EDI translation, partner management | B2B and EDI | Should |
| CAP-008 *(Example)* | End-to-end monitoring, tracing and business activity views | All | Must |
| CAP-009 *(Example)* | Hybrid runtime that can run close to on-premises systems | All | Should |
| [CAP-NNN] | [Capability] | [Styles] | [Must / Should / Could] |

### 7.2 Platform categories

| Category | Strengths | Weaknesses | Typical fit |
|---|---|---|---|
| Integration platform as a service (iPaaS) | Connectors, low-code flows, managed runtime, fast delivery | Per-flow or per-message cost; vendor lock-in of flow definitions | SaaS-heavy estates, process and system APIs |
| Enterprise service bus (on-premises) | Mature transformation and routing, existing skills | Central bottleneck team, scaling and upgrade cost | Legacy estates, being retired in many organisations |
| Event broker or streaming platform | High throughput, decoupling, replay | Needs schema and topic governance; not a transformation engine | Events, CDC, streaming |
| API gateway and management | Security, quotas, portal, analytics at the edge | Not suited to orchestration or heavy mapping | All exposed APIs |
| Managed file transfer | Reliable, audited file movement, scheduling | Batch latency | Files and bulk data |
| B2B gateway or managed EDI service | Partner protocols, EDI standards, onboarding services | Specialist skills, per-partner cost | Trading partners |
| Code-based integration on a service platform | Full control, testable code, no licence | Needs engineering capacity and shared libraries | Complex domain logic, high scale |

## 8. Platform decision

<!-- Guidance: Score options against the capabilities in section 7 with weights agreed before scoring. Use Technology Selection (`architecture/technology-selection`) or Build vs Buy Analysis (`architecture/build-vs-buy-analysis`) for the detailed evaluation and Total Cost of Ownership Analysis (`architecture/tco-analysis`) for cost. Pitfall: scoring after the preferred vendor is known. -->

| Criterion | Weight | Option A: iPaaS + managed broker | Option B: refresh ESB + broker | Option C: code-based on service platform |
|---|---|---|---|---|
| Capability coverage (CAP-001 to CAP-009) *(Example)* | 30 % | 4 | 3 | 3 |
| Delivery speed for new integrations *(Example)* | 20 % | 5 | 3 | 2 |
| Five-year total cost *(Example)* | 20 % | 3 | 2 | 4 |
| Skills availability *(Example)* | 10 % | 4 | 2 | 3 |
| Hybrid and data residency fit *(Example)* | 10 % | 3 | 4 | 5 |
| Exit cost and portability *(Example)* | 10 % | 2 | 2 | 5 |
| **Weighted score** *(Example)* | 100 % | **3.70** | **2.70** | **3.40** |

Scores use 1 (poor) to 5 (excellent). The weighted score for option A is
0.3 x 4 + 0.2 x 5 + 0.2 x 3 + 0.1 x 4 + 0.1 x 3 + 0.1 x 2 = 3.70, option B scores 2.70 and option C 3.40.
Recompute every row when you replace the example scores.

| Decision | Choice | ADR |
|---|---|---|
| *Example:* Integration runtime | Option A, iPaaS for flows and system APIs | ADR-INT-001 |
| *Example:* Event broker | Managed streaming service in the primary cloud region | ADR-INT-002 |
| *Example:* B2B | Keep outsourced EDI provider for two years, then review | ADR-INT-003 |
| *Example:* Legacy ESB | Retire by YYYY-MM; no new interfaces from YYYY-MM-DD | ADR-INT-004 |
| [Decision] | [Choice] | [ADR-ID] |

## 9. Canonical data and contract policy

<!-- Guidance: Decide where a canonical model helps and where it hurts. An enterprise-wide canonical model is expensive to agree and to change; most organisations now define canonical models per business domain and let consumers map at the edge. Pitfall: a canonical model that nobody owns and every project extends. -->

| Policy area | Rule |
|---|---|
| Scope of canonical models | *Example:* One canonical model per business domain (product, customer, order, stock); no single enterprise-wide model |
| Ownership | *Example:* The domain team that owns the system of record owns the canonical model; changes go through its contract review |
| Mapping location | *Example:* Translate at the edge: system APIs map system formats to the domain model; partners are mapped in the B2B gateway |
| Identifiers | *Example:* Global identifiers issued by the system of record or the master data hub (Master Data Management Design, `architecture/master-data-management-design`) |
| Reference data | *Example:* Country, currency and unit codes follow ISO code lists; local codes are mapped, not exposed |
| Versioning | *Example:* Semantic versioning on every contract; breaking changes need a new major version and a deprecation period (API Deprecation Policy, `architecture/api-deprecation-policy`) |
| Data contracts for analytics | *Example:* Datasets published to the data platform use a data contract (`ai-data/data-contract`) |
| Personal data | *Example:* Contracts mark personal data fields; minimise fields per consumer |

## 10. Reuse, catalogue and lifecycle

<!-- Guidance: Reuse only happens when interfaces are easy to find and trust. Decide what the catalogue holds, who curates it and how an interface moves through its lifecycle. Pitfall: a catalogue filled once at launch and never kept current. -->

### 10.1 Catalogue content

Every interface, API, event type and file feed is registered with: ID,
name, owner, style, contract link, version, lifecycle state, data
classification, consumers, service level and support channel. The
developer portal (API Management Platform Design,
`architecture/api-management-platform-design`) and the event catalogue
(Event-Driven Architecture Design, `architecture/event-driven-architecture-design`)
are the user-facing views of the same register.

### 10.2 Lifecycle states

An interface moves through five states; only Published interfaces may gain new consumers.

```mermaid
stateDiagram-v2
  [*] --> Proposed
  Proposed --> Designed: contract reviewed
  Designed --> Published: tests pass, registered
  Published --> Deprecated: successor published
  Deprecated --> Retired: no consumers or sunset date
  Retired --> [*]
```

### 10.3 Reuse rules

| Rule | Check |
|---|---|
| *Example:* Search the catalogue before proposing a new interface | Design review records the search and why existing interfaces do not fit |
| *Example:* Extending an existing contract is preferred over creating a parallel one | Backward-compatible additions only |
| *Example:* Interfaces with no consumer for 6 months are candidates for retirement | Quarterly catalogue review |
| [Rule] | [Check] |

## 11. Security and identity

<!-- Guidance: Set the security baseline that every interface must meet, with the owner of each control. Link to Security Architecture (`security/security-architecture`) and Zero Trust Architecture (`security/zero-trust-architecture`). Pitfall: shared service accounts with long-lived passwords across many interfaces. -->

| Area | Baseline rule |
|---|---|
| Transport | TLS 1.2 or later on every hop, TLS 1.3 preferred; mutual TLS for service-to-service traffic between trust zones |
| API authentication | OAuth 2.0 client credentials or token exchange for machine callers, following the OAuth 2.0 Security Best Current Practice (RFC 9700, January 2025); API keys only for low-risk public data and never alone for write access |
| User delegation | Authorisation code flow with PKCE through the corporate identity provider |
| Financial-grade APIs | Where open banking or high-value payments apply, follow the FAPI 2.0 Security Profile (OpenID Foundation, Final, February 2025); see Open Banking API Design (`industry/open-banking-api-design`) |
| Event broker | Per-client identities, topic-level access control lists, no shared credentials |
| Files and B2B | Key-based SFTP or certificate-based AS2 and AS4 with signed receipts; keys rotated per section 9 of the B2B, EDI and File Transfer Design |
| Secrets | Held in the secrets manager; no credentials in flow definitions or code |
| Data protection | Field-level encryption or tokenisation for card and special-category data; personal data minimised per consumer |
| Logging | Payload logging off by default for classified data; audit events retained [13 months] |
| Threat modelling | Required for every externally exposed interface (`security/threat-model`) |

## 12. Operating model and centre of excellence

<!-- Guidance: Decide who builds, who runs and who governs. Most organisations move from a central integration team that builds everything to a centre of excellence that provides the platform, standards and enablement while domain teams build their own integrations. Pitfall: a federated model without guardrails, which repeats the sprawl. -->

### 12.1 Model choice

| Model | Description | Use when |
|---|---|---|
| Centralised | One integration team designs, builds and runs all interfaces | Small estate or low maturity |
| Federated with centre of excellence | Platform team runs the platforms; domain teams build; the centre of excellence sets standards and reviews | Medium to large estates with capable domain teams |
| Fully decentralised | Teams choose and run their own tools | Rarely appropriate for shared integration |

*Example:* The organisation adopts the federated model with a centre of
excellence of [6] people (lead architect, two platform engineers, an API
product manager, a B2B specialist and an enablement lead).

### 12.2 RACI

| Activity | Centre of excellence | Platform team | Domain team | Security | Architecture board |
|---|---|---|---|---|---|
| Integration standards and patterns | A, R | C | C | C | I |
| Platform operation and upgrades | C | A, R | I | C | I |
| Interface design | C | I | A, R | C | I |
| Interface build and test | I | C | A, R | I | I |
| Contract review for shared APIs and events | A, R | I | R | C | I |
| Exceptions to this strategy | R | C | C | C | A |
| Partner onboarding (B2B) | A, R | R | C | C | I |

### 12.3 Enablement

| Item | Description |
|---|---|
| *Example:* Starter templates | Flow, API and event templates with logging, security and error handling built in |
| *Example:* Training path | Platform basics, API design, event design, security, two-day bootcamp per quarter |
| [Item] | [Description] |

## 13. Funding and chargeback

<!-- Guidance: Decide how platform and interface costs are paid. Chargeback by usage encourages discipline but can discourage reuse if the first consumer pays everything. Pitfall: charging the producer of a reusable API for every new consumer. -->

| Cost element | Funding approach | Allocation key |
|---|---|---|
| Platform licences and infrastructure *(Example)* | Central IT budget for the base; showback to domains | Message volume or API calls per domain |
| Centre of excellence staff *(Example)* | Central budget | Not charged |
| Interface build *(Example)* | Project budget of the first consumer | Not shared |
| Reusable system API build *(Example)* | Central reuse fund up to [USD 50,000] per API | Repaid through later consumer fees, if any |
| B2B partner onboarding *(Example)* | Business unit that requests the partner | Per partner |
| [Element] | [Approach] | [Key] |

## 14. Roadmap and traceability

<!-- Guidance: Sequence the change in transition states that each deliver value. Use Architecture Roadmap (`architecture/architecture-roadmap-transition`) for the detailed plan. Pitfall: a big-bang platform migration with no interim business benefit. -->

### 14.1 Transition states

| Phase | Window | Outcomes | Exit criteria |
|---|---|---|---|
| Foundation *(Example)* | Q1 to Q2 YYYY | Gateway, iPaaS, broker and schema registry live; standards published | First three interfaces in production on new platforms |
| Decouple the ERP *(Example)* | Q3 YYYY to Q2 YYYY | System APIs and events for product, stock, order, customer | Database links reduced from 18 to 4 |
| Retire legacy ESB *(Example)* | Q3 to Q4 YYYY | All ESB interfaces migrated | ESB decommissioned, licence ended |
| B2B modernisation *(Example)* | YYYY | Partner self-service onboarding, AS4 option | Onboarding time below 2 weeks |
| [Phase] | [Window] | [Outcomes] | [Exit criteria] |

### 14.2 Migration rules for existing interfaces

| Rule | Detail |
|---|---|
| *Example:* Migrate on change | Any interface touched by a project moves to the target platform in that project |
| *Example:* Migrate by risk | Interfaces with the highest incident share migrate first |
| *Example:* Freeze | No new interface on the legacy ESB from YYYY-MM-DD |
| [Rule] | [Detail] |

### 14.3 Traceability matrix

| Driver or debt | Principles | Capabilities | Roadmap phase | KPI |
|---|---|---|---|---|
| DRV-001 *(Example)* | INP-003, INP-004 | CAP-001, CAP-002, CAP-003 | Foundation | KPI-001 |
| DRV-002 *(Example)* | INP-002, INP-006 | CAP-004, CAP-005 | Decouple the ERP | KPI-003 |
| DRV-003 / DEBT-001 *(Example)* | INP-001 | CAP-003 | Decouple the ERP | KPI-004 |
| DRV-004 *(Example)* | INP-003 | CAP-007 | B2B modernisation | KPI-005 |
| DRV-005 / DEBT-003 *(Example)* | INP-004 | CAP-003 | Retire legacy ESB | KPI-006 |
| [ID] | [INP-NNN] | [CAP-NNN] | [Phase] | [KPI-NNN] |

## 15. KPIs and measures

<!-- Guidance: Pick a few measures tied to the drivers, with a baseline and a target. Measure them from platform data, not surveys. Pitfall: counting the number of APIs built, which rewards duplication. -->

| ID | KPI | Baseline | Target | Source |
|---|---|---|---|---|
| KPI-001 *(Example)* | Lead time from request to production for a new integration | 10 weeks | 3 weeks | Delivery tracker |
| KPI-002 *(Example)* | Reuse ratio: consumers per published API or event type | 1.1 | 2.5 | Catalogue |
| KPI-003 *(Example)* | Stock update latency from WMS to channels, 95th percentile | 12 hours | 30 seconds | Broker metrics |
| KPI-004 *(Example)* | Direct database links into the ERP | 18 | 0 | Interface inventory |
| KPI-005 *(Example)* | Partner onboarding time | 6 weeks | 2 weeks | B2B gateway |
| KPI-006 *(Example)* | Integration platform run cost per year | [USD 1.2 million] | [USD 0.8 million] | Finance |
| KPI-007 *(Example)* | Integration incidents per month with business impact | 14 | 4 | Incident tool |
| [KPI-NNN] | [KPI] | [Baseline] | [Target] | [Source] |

## 16. Risks, assumptions and decisions

<!-- Guidance: Record the risks to the strategy itself, the assumptions it rests on, and the decisions taken. Keep open questions visible with an owner and a date. -->

| ID | Type | Description | Response | Owner |
|---|---|---|---|---|
| RSK-001 *(Example)* | Risk | Domain teams lack integration skills for the federated model | Enablement plan, centre of excellence pairing for first two projects | @coe-lead |
| RSK-002 *(Example)* | Risk | iPaaS cost grows faster than usage forecast | Monthly cost review, quotas per domain | @finops-lead |
| RSK-003 *(Example)* | Risk | Event broker becomes a dumping ground for unowned topics | Topic ownership and catalogue rules, see EDA design | @eda-lead |
| ASM-001 *(Example)* | Assumption | ERP vendor supports outbox or CDC for core tables | Proof of concept in Foundation phase | @erp-architect |
| DEC-001 *(Example)* | Decision | Domain canonical models, not an enterprise model | ADR-INT-005 | @chief-architect |
| [ID] | [Risk / Assumption / Decision] | [Description] | [Response] | [@owner] |

## 17. Glossary and references

<!-- Guidance: Define terms that readers in business and IT may understand differently, and list the sources with the date you checked them. -->

### 17.1 Glossary

| Term | Meaning |
|---|---|
| iPaaS | Integration platform delivered as a managed cloud service |
| ESB | Enterprise service bus, a central middleware for routing and transformation |
| System, process, experience API | Layers of the layered API model in section 5 |
| Canonical data model | Shared message format that several applications map to |
| Outbox | Table written in the same transaction as the business change, read by a relay that publishes messages |
| CDC | Change data capture from a database log |
| MFT | Managed file transfer |
| Centre of excellence | Small team that owns integration standards, platforms and enablement |

### 17.2 References

| Reference | Version or date checked | Use |
|---|---|---|
| Enterprise Integration Patterns, Gregor Hohpe and Bobby Woolf, Addison-Wesley, and enterpriseintegrationpatterns.com | Book 2003; site checked YYYY-MM-DD | Pattern names in section 6 |
| AsyncAPI Specification, asyncapi.com | 3.1.0 (January 2026) | Event and message contracts |
| CloudEvents, CNCF, github.com/cloudevents/spec | 1.0.2 | Event envelope |
| OpenAPI Specification, spec.openapis.org | 3.2 (3.2.0 September 2025, 3.2.1 September 2026) | HTTP API contracts |
| RFC 9700, Best Current Practice for OAuth 2.0 Security (BCP 240), IETF | January 2025 | Section 11 |
| FAPI 2.0 Security Profile, OpenID Foundation | Final, February 2025 | Financial-grade APIs |
| Transactional outbox pattern, microservices.io (Chris Richardson) | Checked YYYY-MM-DD | Section 4.3 |
| API-led connectivity, MuleSoft | Vendor concept, checked YYYY-MM-DD | Layer names in section 5 |
| [Internal standard] | [Version] | [Use] |

## Standard and licence note

Based on public specifications: AsyncAPI 3.1.0 (Linux Foundation, Apache
2.0), CloudEvents 1.0.2 (CNCF, Apache 2.0), the OpenAPI Specification
3.2, RFC 9700 and the FAPI 2.0 Security Profile. Pattern names come from
Enterprise Integration Patterns by Gregor Hohpe and Bobby Woolf; the
site publishes pattern names, icons and summaries under CC BY 4.0, and
this template uses the names only, with attribution, and writes all
explanations in original words. The system, process and experience
layering is described in neutral terms; "API-led connectivity" is a
term used by MuleSoft, a trademark of its owner, and this template is
not affiliated with or endorsed by any vendor. This template is
original text written for this collection. Check the current official
version of every specification before use. Template licence: MIT.