An integration can pass its demonstration and still be unready for production. A record travels from one system to another. The fields look right. Authentication works. Everyone agrees the connection is complete.
Then someone changes a project code. A request times out after the receiving system commits it. An employee leaves, but their application permissions remain. A nightly import quietly stops halfway through. These are boundary problems: the places where two systems, two teams, or two definitions of the business meet.
The useful architecture conversation starts with those boundaries. Choosing an API client comes later.
Establish ownership at the field level
“The ERP is the source of truth” sounds decisive, but it often leaves the important questions unanswered. The ERP might own a project identifier while the SaaS application owns operational status. A data platform may contain both without being authorized to change either.
For each meaningful data element, decide who creates it, who can change it, and where a disputed value gets resolved. Document what happens when the source deletes a record, marks it inactive, merges it, or changes its identifier.
Consider an illustrative construction workflow. An ERP supplies the project code. An asset platform records where equipment is assigned. A telematics service reports its latest observed location. All three describe location or allocation in some way, but they don’t express the same fact. Replacing an assignment whenever a GPS observation arrives would turn a technical mapping into an accidental business rule.
Write the rule before writing the synchronization.
Separate identity from permission
An enterprise customer may ask for SSO as though it completes the access model. SSO answers part of the question: how a user establishes their identity. Your application must still decide which organization they belong to and what they can do there.
Provisioning adds another set of decisions. Who creates accounts? What should happen when a user is disabled upstream? Can a person retain access through another organization or another login method? Which administrative accounts need a separate recovery path?
Document the lifecycle from invitation through departure. Test it with realistic organization boundaries. Successful login is only one event in that lifecycle.
Design for uncertain delivery
A timeout doesn’t tell you whether the other system completed an operation. Retrying blindly can create a second invoice, assignment, or work order. Avoiding the retry can leave the systems inconsistent.
This is where idempotency matters: repeated attempts at the same intended operation should not repeat its business effect. The design needs a stable operation identity, durable tracking, and rules for concurrent attempts. A key generated anew on every retry doesn’t identify the same operation.
Provider guarantees also matter. For example, Stripe documents that webhook deliveries can be duplicated and that event order isn’t guaranteed. Those are characteristics to design around. Read the actual guarantees for each system; don’t assume another provider behaves the same way.
An integration should distinguish receipt, durable acceptance, processing, and business completion. A successful HTTP response at one boundary doesn’t necessarily establish success across all of them.
Give failures a destination
“We’ll log it” is an incomplete operating model. A log entry can describe a failure without ensuring anyone notices or can recover from it.
Decide which failures can be retried automatically, how long retries should continue, and when a person needs to intervene. Invalid business data usually needs a different response from a temporary network failure. Repeatedly sending the same invalid record can add noise and consume capacity without making progress.
Create a visible place for unresolved work. Preserve enough context to investigate safely, including the customer, external record identifier, operation, and error category. Avoid placing credentials or unnecessary personal data in that context.
Recovery needs boundaries too. Who can replay a record? What prevents a replay from duplicating work? How does someone know that the original problem has been corrected? If recovery requires editing production database rows from memory, the integration still has unfinished design work.
Reconcile business state
Even a well-designed event pipeline needs a way to detect disagreement. Events can be missed during configuration changes. A user may update data through a different path. A customer may backfill historical records after launch.
Reconciliation compares the state the business expects with the state the systems actually hold. It can use counts, stable identifiers, relevant totals, versions, or direct record comparisons, depending on the domain. A count alone won’t catch two different records canceling each other out.
Agree on what constitutes a mismatch and what happens next. Some differences can be repaired automatically. Others require a decision from the person who owns the data. The architecture should preserve that distinction.
Make ownership operational
A launch diagram should show more than connected boxes. It should tell the people supporting the integration where processing happens, where credentials live, where failed work waits, and which team owns each boundary.
Before committing to delivery, ask:
- What is the smallest useful scope, including failure handling?
- Which system owns each important field and identifier?
- What are the documented rate limits, delivery guarantees, and change policies?
- How will onboarding, credentials, and customer-specific mappings be managed?
- What can support diagnose without an engineer?
- How will the connection be disabled and its data handled when the relationship ends?
These answers affect both the estimate and the maintenance cost. Treating them as later enhancements produces a misleadingly small initial project.
Choose the simplest architecture that carries the responsibility
Sometimes a direct API connection is appropriate. Sometimes a queue, integration layer, scheduled file transfer, or customer-managed intermediary provides a better boundary. More components create their own operating obligations, so complexity needs a reason.
The right design is the one the business and engineering team can understand, operate, and recover. If a customer integration is becoming a collection of exceptions, Integration Architecture can help turn those exceptions into explicit decisions before they spread through the product.