Headless Salesforce Revenue Cloud (RCA) Capabilities, Without Dual Maintenance
“Separate capability from presentation - but keep exactly one engine that owns the truth.”
A pattern study: keep pricing and configuration authority in one engine, serve every channel from versioned contracts.
HEADLESSAPI-LEDCONTRACT-FIRSTRCA
Demo engine serves web, partner, and internal fixture clients from one contract set
What Made the Problem Difficult
Independent work, demo contracts only. Revenue logic has to reach many surfaces - self-service, partner, mobile, internal - and every surface team eventually proposes owning a copy. I modeled the alternative I trust: one engine, many readers, contracts in between.
Core Platform Constraint
Systemic FrictionBinding engine logic to internal page layouts leaves two bad options: force outsiders onto internal screens, or copy the logic outward and maintain both. Copies always diverge - usually discovered as misquotes.
- !One authoritative engine for price, configuration, and contract rules in the study model
- !External consumers integrate only through versioned contracts
- !Public-traffic patterns must respect platform rate limits
- !Catalog reads stay fast; transactional calculations stay exact
What System Was Designed
A gateway sits between experience surfaces and engine capabilities. It translates auth, enforces budgets, and aggregates multi-step inquiries into single-turn composite calls. Catalog metadata rides edge cache with contract-aware invalidation; live calculations pass through to the engine. Client libraries for React and web components share the same schemas.
Pivotal Architectural Choices
Key Architectural Decisions
Headless capability layer vs. rewriting the engine outside
Rewriting pricing externally is fast to start and slow to own.
- Rebuilding the engine in external microservices
- Iframing internal screens
One implementation to fix, many surfaces to serve. Frontend teams keep full visual freedom without owning arithmetic.
Edge caching for catalog, pass-through for transactions
Reads and calculations have different freshness needs.
- Pass everything through live
- Nightly batch syncs
Browsing stays instant and cheap while money math stays exact.
What Was Actually Built
Authored demo REST/GraphQL contracts that hide internal object shapes behind stable fields.
Built the gateway concerns explicitly: auth translation, per-route budgets, and response aggregation.
Designed composite endpoints so one configurator turn costs one call, not five.
Shipped thin client libraries sharing the same schemas across React and web-component consumers.
Deliberate Architectural Compromises
Trade-offs & Mitigations
⚖Gateway ownership vs. direct calls
Uniform contracts, budgets, and auth across channels.
A gateway to run and version.
Contract tests in CI that fail the build on breaking schema drift.
⚖Live calculation vs. limit budgets
Exact quotes on every transaction.
Public traffic can press platform allowances.
Cache everything cacheable; reserve live calls for money math with session-scoped tokens.
Verified Outcomes
Demo engine serves web, partner, and internal fixture clients from one contract set
No duplicated pricing logic across demo surfaces
Catalog browsing served from edge in the study setup; transactions calculate live
Breaking contract changes surface in CI before deployment in the harness
System Schematic & Data Flow
One demo engine, versioned contracts, edge-cached catalog with live transactional calculation.
Text alternative for screen readers: Architecture flow: Experience Surfaces (React / LWC) to Headless API Gateway via Contract-First Ingress; Headless API Gateway to Demo Salesforce Revenue Cloud (RCA) Engine via Composite Orchestration; Demo Salesforce Revenue Cloud (RCA) Engine to Pricing, Config & Rules via Single Authority; Pricing, Config & Rules to Omnichannel Fixtures via Unified Schema Response
Architectural Conclusion
“A capability outgrows its original UI the day a second channel needs it. Contracts are how it survives the trip.”
- •Keep one engine authoritative; let as many surfaces read it as contracts allow.
- •Cache what is stable, calculate what involves money - and write down which is which.