Composable Commerce Architecture

Composable Commerce Architecture

Activate when architecting a headless / composable commerce implementation on Salesforce Commerce Cloud (B2C or B2B): bespoke storefronts, micro-frontends, BFF middleware, multi-brand/multi-region front-ends over shared Commerce APIs. Composable commerce trades the shipped storefront for flexibility and frontend ownership — it is a deliberate architectural choice, not a default.

Before Starting

• Confirm the composable choice is warranted. Composable commerce adds complexity: you now own a frontend codebase, a BFF, CDN config, caching, and observability. If the business can live with the shipped storefront, do that first.
• Inventory the Commerce APIs in scope. Salesforce Commerce API (SCAPI) covers catalog, cart, checkout, promotions, customer. Gaps (custom flows) become BFF-only features.
• Understand the caching contract. Composable sites live or die by cache strategy. Decide what is page-cached (catalog, PLP), what is edge-computed (personalization), what is origin-only (cart, checkout).

Core Concepts

Headless vs composable

Headless = decoupled frontend over one backend. Composable = best-of-breed assembly: Commerce Cloud for transactions, Contentful/Amplience for CMS, Algolia/Coveo for search, ShipStation for fulfillment. The integration layer (BFF) is what makes it composable.

Backend-for-Frontend (BFF)

A thin service layer between the storefront and Commerce Cloud APIs. Aggregates calls, translates responses for the frontend, hosts business logic the frontend should not have (pricing rules, promo eligibility). Typically Node.js or serverless functions.

MACH stack positioning

MACH = Microservices, API-first, Cloud-native, Headless. Salesforce Commerce Cloud with SCAPI fits MACH; pair with Next.js / Remix for the frontend. Cloud-native = the frontend lives in Vercel / Netlify / Cloudflare Pages, not in Commerce Cloud hosting.

Edge rendering and CDN

Catalog pages are rendered at the edge (ISR / SSG), cached in CDN. Authenticated cart and checkout are origin-rendered. Personalization is edge-computed from a user cookie or header.

Common Patterns

Pattern: Next.js storefront with SCAPI + BFF

Next.js app on Vercel, reads from a Node BFF deployed on Vercel functions or a separate container. BFF authenticates to SCAPI via Client Credentials, applies markups, serves aggregated responses. CDN caches PLP/PDP at edge with ISR revalidation.

Pattern: Multi-brand single Commerce Cloud

Brands share catalog/inventory but have distinct storefronts. BFF routes per brand. Brand config in Commerce Cloud site preferences; frontend derives brand from hostname.

Pattern: Decompose monolith storefront incrementally

Phase 1: keep existing storefront; add headless for one PDP experiment. Phase 2: entire PLP+PDP composable; checkout stays on shipped. Phase 3: full composable including checkout. Gives learning at each phase.

Decision Guidance

Recommended Workflow

1. Validate the composable decision vs shipped storefront with a capability gap analysis.
2. Draft the component architecture: storefront, BFF, CDN, PIM, CMS, search, payments.
3. Map every customer-facing flow to SCAPI endpoints; identify gaps that need custom Apex + custom APIs.
4. Select the frontend framework and deployment target; prototype a PDP to validate latency budget.
5. Build the BFF with a contract between frontend and Commerce Cloud; version the contract from day one.
6. Define caching strategy per route; instrument observability.
7. Rollout incrementally: A/B test the composable experience against the shipped storefront.

Review Checklist

• Capability gap analysis shows composable is warranted
• BFF contract versioned and documented
• Caching strategy defined per route (edge / origin)
• Personalization approach clear (cookie / header / edge function)
• PCI scope minimized (checkout on hosted payment or tokenized)
• Observability: RUM, BFF logs, Commerce Cloud API metrics joined
• Rollback plan to shipped storefront documented

Salesforce-Specific Gotchas

1. SCAPI rate limits are per-client, not per-user. A busy BFF can exhaust rate limits and throttle every user; design token rotation and per-endpoint budgets.
2. Session affinity for cart lives with Commerce Cloud. Composable frontends must pass the cart token consistently; losing it = empty cart.
3. B2B promotions and pricing often require Apex extension points. Plan the custom API surface alongside the frontend.

Output Artifacts

Related Skills

• architect/multi-cloud-architecture — adjacent cloud composition
• integration/integration-pattern-selection — BFF integration choice
• security/oauth-and-jwt-patterns — BFF auth to SCAPI