Understand the boundaries
before you integrate.

Commerce core

Keep business rules—catalog eligibility, checkout decisions, order transitions and operational policies—inside an explicit application layer. Web and mobile experiences should consume those rules instead of duplicating them.

Provider adapters

A payment gateway or shipping provider should not leak provider-specific concepts across the whole commerce codebase. An adapter translates the provider into a smaller internal contract.

// illustrative contract — not a public endpoint
PaymentAdapter.authorize(order, paymentContext)
PaymentAdapter.handleCallback(providerPayload)
PaymentAdapter.refund(transaction, amount)

Webhook safety

Callbacks should be authenticated where supported, parsed defensively, recorded with an idempotency key, acknowledged quickly and moved into controlled processing. Repeated provider delivery must not repeat a destructive action.

Production-safe deployment

Separate static marketing routes from application routes. Validate Nginx before reload, switch files atomically where practical, smoke-test application baselines, and keep a rollback path that does not require restoring the entire platform.

Incremental modernization

Inventory → wrap → replace → verify → retire. Each retired legacy module should leave fewer hidden dependencies, not simply relocate them to a new framework.

Fail visibly, degrade safely

Non-critical failures should create a useful error reference and preserve the main journey where doing so is safe. Payment, inventory or security failures should never be silently converted into success.