Technical enablement · 07

Integrations & swapping third-party systems

Clients rarely have the same technology stack as the reference implementation. This page documents how {{product.name}} connects to external systems, which of those connections are pluggable, and the recipe for replacing one provider with another.

⚠

Be explicit about status. For every integration, state whether the adapter is shipped, pluggable but not implemented, or would require refactoring. Do not describe planned work as available. Third-party licensing and data-sharing terms are for Legal and Procurement, not engineering.

The model: ports and adapters

Product code talks to a small, product-owned interface (the port). Each provider implements that interface in an adapter. Switching providers then means writing or configuring one adapter, not changing business logic. [Replace: name the real base class or interface and where it lives.]

Figure 1 — Provider adapter pattern. Product code depends only on the port; each external system sits behind an adapter selected by configuration.

Integration inventory

One row per external dependency, with an honest status.

Integration	Default provider	Purpose	Status	Swap effort
Identity	[Replace]	Authentication and SSO	Pluggable	Low (configuration)
AI model provider	[Replace]	Generation and embeddings	Pluggable	Low to medium
Content / asset store	[Replace]	Files and media	Adapter needed	Medium
Data source (CRM, CDP)	[Replace]	Customer or reference data	Adapter needed	Medium
Messaging / notifications	[Replace]	Email and chat delivery	Refactor needed	High

The general recipe

Confirm the port

Find the interface the product uses for this integration. If none exists, extract one before writing an adapter.
Map the capability gap

List what the old provider did that the new one cannot (or does differently): limits, data shapes, auth model, latency.
Implement and register the adapter

Implement the port, handle errors and rate limits consistently, and register it under a configuration name.
Test with contract tests

Run the same contract test suite against every adapter so behaviour stays interchangeable.
Roll out behind a flag

Enable per tenant, monitor, then make default if appropriate. Keep the previous adapter available for rollback.

Adapter skeleton (language-neutral pseudocode)

interface AssetStore:
    search(query, filters) -> list[Asset]
    fetch(asset_id)        -> Asset
    publish(asset)         -> asset_id

class ClientAssetStore implements AssetStore:
    # translate between the client's API and the product's Asset model
    # map errors to the product's error types; honour rate limits

Swap guides

One section per swappable system. Replace the examples with the integrations that matter for {{product.name}}.

Example: replacing the content / asset store

Aspect	Guidance
Port	`[Replace: AssetStore]` in `[replace/path]`
Current adapter	[Replace]
What to implement	search, fetch, publish, metadata mapping
Configuration	`[REPLACE_PROVIDER_KEY]`, credentials via the secret store
Known gaps	[Replace: features the new provider lacks]
Effort	[Replace: days/weeks, and what drives it]

Example: replacing the AI model provider

Model providers differ in context limits, tool-calling support, safety behaviour and data-handling terms. Route all calls through the AI service so a swap touches one adapter, and re-run your evaluation set before switching. Confirm data-processing terms with Legal and the Data Privacy Officer first.

API & agent access

ⓘ

Programmatic access. If {{product.name}} exposes a public API, document the OpenAPI location, authentication and rate limits here. If it also offers an MCP server or agent tools so AI assistants can call it, list the tools, the scopes each requires and the human-approval expectations. [Replace: details, or delete if not offered.] Apply the same tenant isolation and audit logging as the UI.

Effort summary

Integration	Typical effort	Main risk
Identity	[Replace]	Claim and group mapping
AI model provider	[Replace]	Behavioural drift; evaluation needed
Asset store	[Replace]	Metadata model differences
Data source	[Replace]	Data quality and volume

💡

Capture lessons from each client integration back into this page so the next team starts further ahead. See also the deployment models for network and access requirements.