“Build an integration platform” leaves most architectural decisions open. Who owns an order? How long may fulfillment take? What happens when a partner API is unavailable? A diagram drawn before answering these questions can look convincing while solving the wrong problem.
Consider a hypothetical personalization platform that accepts marketplace orders, generates production assets, and submits them to fulfillment partners. The examples here are design exercises, rather than descriptions of a particular client system.
A repeatable path to a design
Follow the diagram from the business operation to the evidence supporting the architecture. Each step produces something another person can inspect: a requirement, a target, a boundary, a decision, or a test result.
Discover
Identify users, the valuable operation, and constraints. Ask what happens when the operation fails before choosing services.
Start with outcomes and constraints
The valuable operation is “accept a valid order and eventually hand the approved asset to the correct fulfillment account.” Identify which parts must succeed together and which can happen later. An accepted order needs a durable record; slow rendering does not have to hold the customer’s HTTP connection open.
- Actors: merchants, operators, marketplace APIs, and fulfillment services need different access.
- Ownership: decide which component is authoritative for orders, approval state, and partner receipts.
- Constraints: capture integration quotas, existing systems, operating budget, team size, and retention obligations.
- Failure cost: a delayed status update and duplicate paid fulfillment need different recovery policies.
Separate a requirement from an implementation proposal. “A merchant can track accepted orders” is a requirement. “Use five microservices” is an option that needs justification.
Make quality attributes measurable
For illustration, a team might agree on these initial targets. The numbers are assumptions to validate with stakeholders and measurements, rather than universal recommendations.
1Order acceptance: p95 under 500 ms at the agreed peak load2Normal fulfillment: 95% submitted within 2 minutes3Partner outage: preserve accepted work for later recovery4Tenant isolation: merchants cannot read each other's orders5Recovery: agree restoration time and acceptable data loss separately6Cost: track infrastructure and partner cost per completed order
A latency percentile needs a measurement window and a precise operation boundary. The fulfillment target must define how partner downtime is counted. Otherwise two dashboards can report different results while both appear to satisfy the same requirement.
Draw boundaries that explain responsibility
The C4 model offers several views of a system. A context view helps explain users and external systems; a container view shows applications and data stores. Here “container” is an architectural abstraction and does not necessarily mean Docker.
Start the example with a merchant UI, an API owning order state, a durable queue, workers, and a database. Label connections with purpose and direction. Show that the API acknowledges durable acceptance while workers submit to partners asynchronously.
Choose the smallest credible deployment model
A modular application with a separately scaled worker may be enough initially. Independently deployed services become useful when parts have different scaling, ownership, or release needs. Splitting every module adds network failures and operational work.
- Keep together: coupled rules needing one transaction and owned by the same team.
- Separate when justified: expensive processing, constrained adapters, or components with different runtimes.
- Define contracts: document schemas, errors, compatibility, and who can change them.
Record why the decision fits
AWS’s architectural decision record guidance emphasizes preserving the context and reasoning behind important choices. A short record helps future engineers understand the alternatives and consequences.
1# ADR 001: Process fulfillment asynchronously2Status: Accepted for the initial release3Context: Partner APIs can exceed the order-acceptance latency target.4Decision: Persist orders and pending events together; use workers.5Alternatives: Synchronous partner calls; a service for every module.6Consequences: Acceptance is separate from completion. Operators need7queue visibility, retries, and reconciliation for uncertain submissions.8Revisit when: Workload, ownership, partner behavior, or cost changes.
Validate the riskiest assumption
Before building every screen, probe the partner integration. Measure latency and quota behavior. Check whether it supports a durable idempotency key or submission lookup. Without either, retrying an ambiguous timeout may duplicate fulfillment.
Run a small end-to-end test: accept an order, stop a worker, restart it, and verify recoverability. Test authorization using two merchants. Review the evidence against the agreed targets; a happy-path demo cannot prove the whole architecture.
The useful deliverable connects business operation → measurable target → technical decision → validation. That connection gives the team a reason to trust the design and a clear trigger for revisiting it.