Governed Salesforce Integration Reference Architecture
Overview
Create an evidence-backed target architecture that names every source of truth, mutation path, principal, data class, failure boundary, and recovery mechanism.
Prerequisites
- Business capabilities, system context, sources of truth, data owners, consumers, service objectives, and constraints
- Org topology, Salesforce products, External Client Apps or existing Connected Apps, APIs, events, limits, and entitlements
- Security, privacy, residency, retention, reconciliation, disaster recovery, support, and change-control requirements
Tool Discipline
Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.
Current Contract
Salesforce provides multiple synchronous, asynchronous, bulk, composite, and event integration surfaces with org-specific availability and limits. No single direct API, middleware, replicated database, or event pattern is correct for every domain.
Authentication
Model human, integration, deployment, diagnostic, and break-glass principals separately. Bind each to an approved app, OAuth flow, minimum permissions, secret custody, rotation, revocation, and audit path.
Instructions
- Map systems, trust zones, sources of truth, record and event ownership, consumers, data classes, and business invariants.
- Inventory orgs, products, editions, packages, schemas, API versions, events, limits, identities, and operational dependencies.
- Select interaction patterns per use case: synchronous request, asynchronous bulk, composite, event, scheduled reconciliation, or replicated read model.
- Define contracts for schema, versioning, idempotency, ordering, pagination, checkpoints, retries, dead letters, and backfills.
- Design CRUD and field access, sharing, encryption, retention, audit, residency, redaction, support, and separation of duties.
- Model outages, limit exhaustion, partial writes, event gaps, schema drift, wrong-org access, and disaster recovery.
- Validate with threat, failure, capacity, cost, operability, migration, and rollback reviews and record rejected alternatives.
Approval Boundaries
Do not establish new trust, data movement, system authority, production mutation, or vendor dependency without architecture, security, data, and business approval.
Output
Return context and container views, authority matrix, trust and data-flow boundaries, contracts, failure scenarios, capacity and cost assumptions, decisions, risks, and migration plan.
Error Handling
| Condition | Response |
|---|---|
| Two systems claim authority for the same field | Resolve ownership and conflict policy before implementation. |
| Recovery depends only on replay availability | Add durable reconciliation and backfill from the source of truth. |
| Entitlement or limit assumption is unverified | Mark the design provisional and obtain current org evidence. |
Example
A redacted completion receipt might look like this:
domain=orders; authority=erp; salesforce=crm-projection; writes=governed; events=cdc; reconcile=daily; recovery=tested
Resources
Next Steps
Run the workflow first in the lowest-risk authorized org and preserve its redacted receipt. Schedule a review against the next Salesforce seasonal release and the customer change calendar.