Surface contract (C8)
This page is the system-wide validation reference for surfaces: one canonical name, one URL strategy (or resolver), and one primary owner per row. Product, OSS, and web must match.MCP deployment roles (gateway-console vs Registry MCP vs hosted gateway MCP): MCP surfaces. Developer demo URLs resolve via
resolveDeveloperDemoUrls in @repo/analytics/taxonomy (same paths everywhere when env overrides are unset).Canonical surfaces
| Surface | Canonical name | URL / resolution | Primary owner |
|---|---|---|---|
| Operator UI for self-hosted gateway | Gateway Console | App: apps/gateway-console (deployed host per env) | Platform — Gateway |
| Hosted commerce MCP shell | Hosted Gateway MCP | apps/hosted-gateway-mcp | Platform — Gateway |
| LLM commerce protocol & package | Commerce Gateway | OSS/docs: commercegateway.io; integration: Commerce Gateway | DX + Gateway OSS |
| Discovery protocol & OSS server | Registry MCP | Package @betterdata/registry-mcp; deployed registry-mcp-server; system ref: MCP surfaces | DX + Registry OSS |
| In-product listing & workspace | Commerce Registry | SCM routes under /commerce/registry; public discovery: registry.betterdata.co | Platform — Registry |
| Governed automation | Loop Engine | Loops, loopengine.io | Platform — Loops |
| Reference implementations | Gateway Demo · Commerce Demo · Agent Starter (docs/code) | resolveDeveloperDemoUrls + BUILD_AGENT_DOC_PATH in @repo/analytics/taxonomy | DX — Reference |
| Product shell | Better Data | app / marketing betterdata.co | Product |
Naming rules (must not conflate)
- Registry MCP is the discovery protocol / MCP tools (
@shopresolution, etc.). It is not the Commerce Registry product card. - Commerce Registry is the workspace and product surface for listing, verification, and discovery configuration — native to the platform, not a separate external signup product.
- Gateway Console is the operator dashboard (config, keys, status). It is not the Commerce Gateway protocol runtime.
- Commerce Gateway is the protocol and packages that expose commerce tools to LLMs — not the console UI.
Commerce Agent (composition, not a surface row)
Commerce Agent is not an additional row in this table and not a product SKU. It is the canonical composition pattern: discover (Registry MCP) → execute (Commerce Gateway) → govern (Loop Engine) → recorded outcome; Gateway Demo / Commerce Demo are optional experience layers (reference only). See Commerce Agent pattern (C9) — the only definition; do not introduce “agent” as a standalone product.Demos
- Gateway Demo and Commerce Demo are reference layer experiences — not product modules, not control planes, not multiple competing URLs. URLs resolve through
resolveDeveloperDemoUrls(optional env overrides; otherwise docs fallbacks fromDEVELOPER_DEMO_DOCS_PATHSin@repo/analytics/taxonomy).
Setup flows
- Gateway and registry setup happen in-product after workspace connection. Protocol and Remote MCP endpoints are configuration, not a separate external product signup. See messaging on MCP surfaces.
System diagram (single canonical story)
- Canonical layered messaging (Infrastructure → Protocol → Reference → Control → Platform): Core Concepts — Layered ecosystem and the same model in
@repo/analytics/taxonomy(LAYERED_ECOSYSTEM_MODEL). - Four product layers and operational signal chain (tags → loops → gateway → SCM/DCM): Platform architecture — complementary illustration, not a competing “flat product stack.”
- LLM ↔ gateway ↔ backends (narrow): mermaid under Architecture Overview in Core Concepts — gateway plumbing, not the full platform diagram.