Unified Commerce Gateway

What it is

The Synchronity Gateway is a Fastify 5 service that sits between AI agents and storefront APIs. Every commerce call an agent makes — search a product, add to cart, execute checkout — hits the gateway first. The gateway:

1. Authenticates the agent via its Agent Identity Token (AIT).
2. Routes the call to the right connector (Shopify / WooCommerce / REST-generic) based on the site_id and the agent's allowed scopes.
3. Normalizes the connector's response into the AMPS protocol shape so the agent sees a single, consistent payload across stores.
4. Audits every request to a durable audit log for compliance and debugging.

Why it matters

Agents shouldn't know about Shopify's GraphQL idiosyncrasies or WooCommerce's REST quirks. The gateway gives them one mental model — search/cart/checkout — and the connector layer translates underneath. Two benefits:

• Connector keys never leave the gateway. Agents authenticate with a JWT; the gateway stores the merchant's per-site connector key only as an HMAC hash. An agent that goes rogue can be revoked centrally — the merchant's storefront credentials are untouched.
• Adding a new platform is a connector, not an agent rewrite. Drop a new connector behind the gateway and every existing agent prompt continues to work against the new platform.

Request pipeline

client (Claude/Cursor)
    │  HTTPS + Bearer AIT
    ▼
gateway                     ◄── Postgres + Redis
  1. request log
  2. CORS + security headers
  3. authentication
  4. scope / RBAC check
  5. rate limiting (sliding window)
  6. audit logging
  7. route handler
    │  HTTP + connector key
    ▼
connector (Shopify | Woo | REST-generic)
    │
    ▼
merchant storefront API

Order matters. Auth runs before scope checks; scope checks run before rate limits; rate limits run before the audit write. A request that fails any earlier stage never hits the connector.

What you get for free

• AMPS normalization. Every product, cart, order response conforms to the AMPS protocol. Agents don't write per-platform parsers.
• Centralized rate limiting. Per-agent Redis sliding window. One bad actor can't exhaust your Shopify rate budget.
• Auditable history. Every action recorded with agent_id, site_id, action_type, request/response, IP, outcome.

What you write

Almost nothing. Register an agent, register a site, drop the MCP server into your client, done. The gateway, connectors, and SDKs handle the rest.