UCP Architecture Library

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer actor Shopper participant CP as Consumer platform end box rgb(42,24,5) Kodez / Retailer participant GW as UCP gateway participant CO as Checkout service participant SC as Scenario controller participant CN as Commerce connector participant RB as Retailer backend end Shopper->>CP: Change quantity or fulfillment CP->>GW: PUT /checkout/{id} GW->>CO: Validate and update checkout CO->>SC: Read active fault flags SC-->>CO: Price drift or stock exhaustion CO->>CN: Re-price and re-validate CN->>RB: Check current availability and totals RB-->>CN: Changed total or unavailable item CN-->>CO: Classified recoverable error CO-->>GW: Checkout requires shopper action GW-->>CP: Protocol error with next action CP-->>Shopper: Show updated total or remove item

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer actor Shopper participant CP as Consumer platform end box rgb(42,24,5) Kodez / Retailer participant GW as UCP gateway participant CO as Checkout service participant PAY as Payment simulator participant STORE as Checkout store end Shopper->>CP: Submit tokenized payment CP->>GW: POST /checkout/{id}/complete GW->>CO: Complete checkout CO->>PAY: Authorize opaque credential PAY-->>CO: Declined CO->>STORE: Persist recoverable checkout state CO-->>GW: Payment failure GW-->>CP: Protocol error CP-->>Shopper: Request another payment method Shopper->>CP: Submit replacement credential CP->>GW: Retry completion with new idempotency key GW->>CO: Complete checkout again CO->>PAY: Authorize replacement credential PAY-->>CO: Approved

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer participant CP as Consumer platform end box rgb(42,24,5) Kodez / Retailer participant GW as UCP gateway participant CO as Checkout service participant IDEM as Idempotency store participant CN as Commerce connector participant RB as Retailer backend end CP->>GW: POST /checkout/{id}/complete + key K1 GW->>IDEM: Look up K1 IDEM-->>GW: No prior result GW->>CO: Complete checkout CO->>CN: Create order CN->>RB: Submit order RB-->>CN: Order created CN-->>CO: Order snapshot CO->>IDEM: Store result for K1 GW--xCP: Response lost or timeout CP->>GW: Retry completion with key K1 GW->>IDEM: Look up K1 IDEM-->>GW: Replay original order result GW-->>CP: Same order, no duplicate effect

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer participant CP as Consumer platform end box rgb(42,24,5) Kodez / Retailer participant RB as Retailer backend participant CN as Commerce connector participant OW as Order service participant WH as Webhook transport end box rgb(5,46,22) Google - UCP Protocol / Merchant Center participant SEC as Signature service end RB->>CN: Shipment or delivery event CN->>OW: Normalize canonical order event OW->>SEC: Sign webhook payload SEC-->>OW: Signature and timestamp OW->>WH: Dispatch signed event WH->>CP: POST signed webhook alt Webhook failure CP--xWH: 5xx or timeout WH->>WH: Retry with backoff WH->>CP: POST signed webhook again CP--xWH: Still unavailable WH->>OW: Record dead-letter event else Delivery succeeds CP-->>WH: 2xx acknowledgement WH->>OW: Record delivered event end

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer participant CP as Consumer platform end box rgb(42,24,5) Kodez / Retailer participant GW as UCP gateway participant CO as Checkout service end box rgb(5,46,22) Google - UCP Protocol / Merchant Center participant SIG as Signature service participant VAL as Schema validator participant REP as Replay and idempotency store end CP->>GW: Signed state-changing request GW->>SIG: Verify signature and digest SIG-->>GW: Valid or rejected alt Invalid signature or digest GW-->>CP: 401 or 400 protocol error else Signature valid GW->>REP: Check timestamp, replay, and idempotency key REP-->>GW: Fresh request or replay result alt Replay detected GW-->>CP: Replay response or conflict else Fresh request GW->>VAL: Validate schema and invariants VAL-->>GW: Valid payload GW->>CO: Execute state change CO-->>GW: Result GW-->>CP: Signed protocol response end end

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer participant CP as Consumer platform end box rgb(42,24,5) Kodez / Retailer actor Operator participant OPS as Operations console participant GW as UCP gateway participant SC as Scenario controller participant CO as Commerce services participant TRACE as Trace store end Operator->>OPS: Enable price, stock, payment, or timeout flag OPS->>GW: POST /scenario GW->>SC: Update scenario flags SC-->>GW: Active flags GW->>TRACE: Record configuration change GW-->>OPS: Updated scenario state CP->>GW: Execute checkout flow GW->>CO: Read scenario state during operation CO-->>GW: Controlled success or failure GW->>TRACE: Record request and outcome GW-->>CP: Protocol response Operator->>OPS: Reset demo state OPS->>GW: POST /reset GW->>SC: Clear flags and reset state SC-->>GW: Baseline restored

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer participant GMC as Google Shopping simulator end box rgb(42,24,5) Kodez / Retailer participant GW as UCP gateway participant CAT as Catalog service participant DB as SQLite database end box rgb(5,46,22) Google - UCP Protocol / Merchant Center participant FEED as Feed generator end GMC->>GW: GET /feeds/google-shopping.xml GW->>FEED: Generate RSS 2.0 feed FEED->>CAT: List products and variants CAT->>DB: Read catalog DB-->>CAT: Product data CAT-->>FEED: Products with GTIN and price FEED-->>GW: XML with ucp:checkout_endpoint GW-->>GMC: Merchant feed GMC->>GW: GET /.well-known/ucp GW-->>GMC: Profile and supported capabilities GMC->>GW: POST /checkout GW-->>GMC: Retailer-authoritative checkout

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer participant Client as MCP client end box rgb(5,46,22) Google - UCP Protocol / Merchant Center participant MCP as UCP skills MCP server participant MAN as skills.manifest.json participant FS as Canonical skill files end Client->>MCP: Initialize stdio session MCP-->>Client: Tools, resources, and prompts Client->>MCP: ucp_list_skills MCP->>MAN: Read catalog manifest MAN-->>MCP: Skill metadata and references MCP-->>Client: Skill list Client->>MCP: ucp_get_skill(skillId) MCP->>MAN: Resolve skill entry MCP->>FS: Read canonical Markdown FS-->>MCP: Skill instructions MCP-->>Client: Manifest entry and instructions Client->>MCP: ucp_get_resource(reference) MCP->>FS: Read referenced template or rubric FS-->>MCP: Resource content MCP-->>Client: Resource response

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer participant CP as Consumer platform end box rgb(42,24,5) Kodez / Retailer participant GW as UCP gateway participant CO as Checkout service participant PORT as Commerce connector port participant A as Retailer connector A participant B as Retailer connector B participant RA as Retailer system A participant RB as Retailer system B end CP->>GW: POST /checkout GW->>CO: Create checkout CO->>PORT: createCheckout(canonical request) alt Retailer A selected PORT->>A: Translate canonical request A->>RA: Retailer-specific API call RA-->>A: Retailer response A-->>PORT: Canonical checkout else Retailer B selected PORT->>B: Translate canonical request B->>RB: Retailer-specific API call RB-->>B: Retailer response B-->>PORT: Canonical checkout end PORT-->>CO: Same canonical contract CO-->>GW: UCP checkout response GW-->>CP: Protocol-valid response

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer actor Shopper participant CP as Consumer platform end box rgb(42,24,5) Kodez / Retailer participant GA as Retailer A gateway participant GB as Retailer B gateway participant A as Retailer A order service participant B as Retailer B order service end Shopper->>CP: Add products from two retailers par Independent checkout A CP->>GA: Create and complete checkout A GA->>A: Authoritative totals and order A A-->>GA: Order A confirmed GA-->>CP: Order A result and Independent checkout B CP->>GB: Create and complete checkout B GB->>B: Authoritative totals and order B B-->>GB: Payment failure or order B confirmed GB-->>CP: Order B result end CP-->>Shopper: Aggregate independent order history Note over CP: Retailer systems of record remain independent

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer actor Shopper participant SA as Shopper agent end box rgb(42,24,5) Kodez / Retailer participant RA as Retailer agent or connector participant GW as UCP gateway participant CO as Checkout service participant PAY as Tokenized payment handler participant RB as Retailer backend end Shopper->>SA: Set product, budget, and retailer policy SA->>RA: Discover profile and capabilities RA-->>SA: Negotiated capability set SA->>GW: Create checkout GW->>CO: Return authoritative totals and fulfillment CO->>RB: Check availability and pricing RB-->>CO: Current checkout state CO-->>GW: Checkout state GW-->>SA: Totals and required actions SA->>SA: Compare totals with shopper limits alt Within pre-authorized limits SA->>PAY: Acquire opaque payment credential PAY-->>SA: Token SA->>GW: Complete checkout with idempotency key GW->>CO: Authorize and create order CO->>RB: Submit order RB-->>CO: Order created CO-->>GW: Order confirmation GW-->>SA: Completed order SA-->>Shopper: Report result asynchronously else Outside limits SA-->>Shopper: Request explicit confirmation end