1.1 Frame the Integration Before Drawing Boxes

Define actors, data ownership, and the business workflow before choosing technology.

◷ Estimated reading time: 6 min

Begin with a concrete story

Imagine that a shopper places an order on TikTok Shop. The merchant already uses its own software to pack and ship orders. Your job is to connect the two sides so the merchant sees the new order and TikTok Shop later receives the tracking number.

At first, the flow sounds simple:

Shopper places order
      ↓
TikTok Shop sends order to our integration
      ↓
Our integration sends order to the merchant's order system
      ↓
Merchant ships the package
      ↓
Our integration sends tracking information back to TikTok Shop

This is an integration: software that helps two independently operated systems exchange information and stay in agreement.

Name systems by what they do

You do not need a wall of enterprise acronyms to begin. Start with plain-language roles:

System	What it does in this example
TikTok Shop	Accepts the customer's order and shows its marketplace status
Merchant order system	Tells the merchant what to pack, cancel, or ship
Warehouse system	Tracks physical stock and warehouse work
Our integration service	Translates data, delivers updates, retries failures, and records enough state to recover

Later, you may hear names such as OMS, meaning Order Management System, or WMS, meaning Warehouse Management System. Those labels are useful shorthand, but the design question is still: what job does this system perform?

Decide who is allowed to say what is true

Suppose TikTok Shop says the order is cancelled, but our integration database still says it is paid. Which value should win?

The answer depends on ownership. In this example, TikTok Shop created the customer order and owns its marketplace lifecycle, so its cancellation status should usually win. Our integration may keep a copy for processing, but that copy is not automatically the authority.

This authoritative system is called the source of truth. A source of truth is simply the place we trust when two copies disagree.

Question	Example answer
Who created and owns the marketplace order?	TikTok Shop
Who manages packing and shipping work?	The merchant's order system
Who knows the physical stock on a shelf?	The merchant's warehouse system
What does our integration own?	Delivery attempts, ID mappings, processed-event records, checkpoints, and audit history

Common beginner mistake

Storing a copy of a business object does not make your service its owner. Your database might say PAID because it has not received the latest cancellation yet. Design must specify which system wins and how the stale copy will be corrected.

Draw boundaries before choosing technology

Before discussing REST APIs, webhooks, queues, or databases, write down:

Which people and systems participate?
What event starts the workflow?
What information moves in each direction?
Which system is the source of truth for each important fact?
What must happen if one side is slow or temporarily unavailable?

Interview language

"Before choosing technology, I would identify the systems, walk through the business flow, and define the source of truth for each important piece of data. That tells us what must move, in which direction, and how disagreements should be repaired."

Key Takeaways

Start from the business workflow, not the transport.
Describe systems by their responsibilities before introducing product names or acronyms.
Assign a source of truth for each important fact, such as order status or available stock.
Keep delivery and recovery state separate from the business data owned by connected systems.

Test

TikTok Shop says an order is CANCELLED, while your integration database still says PAID. What should you ask first?

System Design for Integrations 1.2 Integration Timing Models

loading…