Integration Design

## What a synchronous call does **Synchronous integration** means the calling system opens a connection, sends a request, and blocks — holding a thread, a connection, and often a user-facing spinner — until the receiving system computes and returns a response over that same channel. The classic implementations are HTTP/REST calls, gRPC unary calls, or a direct network read. The caller's code proceeds linearly: 1. call 2. wait 3. get response 4. continue This is the model most engineers learn first because it maps directly onto function calls: you invoke something and get a return value back in the same execution flow. ## What an asynchronous call does instead **Asynchronous integration** breaks that direct temporal coupling. - Instead of waiting on the same channel, the caller fires a message into a durable intermediary (a queue, a topic, an outbox table) and moves on immediately, or accepts a callback/webhook the other side invokes later. - The receiving system consumes the message whenever it has capacity, processes it, and — if a reply is needed — sends it back through its own asynchronous channel rather than the original connection. The key shift: request and response become two independent messages instead of one blocking round trip. ## Why both exist Both patterns exist because they solve different problems. - **Synchronous calls** exist because some interactions are inherently read-now: a user clicking 'view profile' needs the data before the page can render — there's no meaningful way to decouple that. - **Asynchronous integration** exists because many interactions are write-now, process-eventually: placing an order doesn't require warehouse, billing, and shipping to all confirm instantly — it requires the order durably recorded, with downstream work happening independently and reliably even if one of those systems is temporarily down. ## The trade-offs The trade-offs cut both ways. | Style | What it buys | What it costs | |---|---|---| | **Synchronous integration** | Simple to trace and debug — a stack trace or distributed-trace span shows the exact causal chain, and errors surface immediately where you can retry or show the user a message. | Its cost is temporal coupling: the caller's availability is bounded by the callee's, latency compounds across chained calls, and a slow dependency can exhaust the caller's thread pool, taking it down too. Mitigations exist (timeouts, circuit breakers, bulkheads, retries with backoff) but they're bolted on, not free — each is another failure mode to test. | | **Asynchronous integration** | Buys resilience to outages (the message sits durably until the consumer is back) and load leveling (a burst becomes a queue drained at the consumer's own pace). | Its cost is that 'I sent it' is no longer 'it succeeded' — you need a separate mechanism to close that loop if the caller cares about the outcome. You also inherit distributed-systems problems: messages can arrive out of order or be delivered more than once (most brokers guarantee at-least-once, not exactly-once), so idempotent consumers become mandatory, not optional hardening. | ## Failure modes Failure modes differ sharply in production. - **A synchronous integration failing** looks like elevated latency, timeouts, and cascading errors — visible fast, but capable of taking multiple systems down together in a retry storm if every caller retries aggressively at once. - **An asynchronous integration failing** looks quieter: messages silently piling up in a queue, a consumer falling behind without anyone noticing until the backlog is hours old, or a poison message a consumer can never process, blocking everything behind it until someone builds a dead-letter queue and monitors depth/age. ## A concrete example A concrete example: an e-commerce checkout typically calls inventory-check and payment-authorization **synchronously** — the customer is staring at the screen and the flow cannot proceed without those answers, so a short timeout with a clear failure message is the right design. But order fulfillment, the confirmation email, analytics, and warehouse notification are dispatched **asynchronously** via an `OrderPlaced` event — none needs to happen before the customer sees 'Order confirmed,' and doing them synchronously would mean checkout hangs on the warehouse system's uptime. Choosing correctly per interaction, rather than picking one style for the whole system, is the actual skill being tested.