UCP Protocol Inspector

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer actor Shopper as End User / Customer participant CP as End User's Device (Laptop, PC, Phone) end box rgb(42,24,5) Kodez / Retailer participant GW as UCP gateway (Kodez) end box rgb(5,46,22) Google - UCP Protocol / Merchant Center participant NEG as Negotiation / capability discovery participant SEC as Security (keys/signatures) end CP->>GW: GET /.well-known/ucp GW->>SEC: Fetch signing keys / JWKs SEC-->>GW: Active keys GW-->>CP: Retailer profile (services, capabilities, versions, payment handlers) CP->>NEG: Submit platform profile (UCP-Agent, supported capabilities) NEG->>NEG: Intersect capabilities, pin exact version, prune extensions NEG-->>CP: Negotiated capability set CP-->>Shopper: Platform ready to shop with retailer

sequenceDiagram autonumber box rgb(13,27,42) Client / Consumer / Customer actor Shopper as End User / Customer participant CP as End User's Device (Laptop, PC, Phone) end box rgb(42,24,5) Kodez / Retailer participant GW as UCP gateway (Kodez) participant CO as Checkout state machine participant CN as Northstar connector participant RB as Northstar Backend end box rgb(5,46,22) Google - UCP Protocol / Merchant Center participant VAL as Schema validation end Shopper->>CP: Select product, quantity, delivery details CP->>GW: POST /checkouts (idempotency key) GW->>VAL: Validate request against schema VAL-->>GW: Valid GW->>CO: Create checkout session CO->>CN: Translate to canonical commerce request CN->>RB: Query availability, price, tax, fulfillment RB-->>CN: Authoritative totals and options CN-->>CO: Canonical checkout state CO-->>GW: Checkout with totals, policies, required actions GW-->>CP: Checkout response CP-->>Shopper: Review totals and fulfillment options Shopper->>CP: Update address / fulfillment choice CP->>GW: PUT /checkouts/{id} (full replacement) GW->>CO: Recompute state via connector CO->>CN: Re-price / re-validate CN->>RB: Recheck availability and totals RB-->>CN: Updated totals CN-->>CO: Updated canonical state CO-->>GW: Updated checkout GW-->>CP: Updated totals and actions CP->>GW: POST /checkouts/{id}/complete (payment credential, idempotency key) GW->>CO: Complete checkout CO->>CN: Authorize payment, create order CN->>RB: Submit order RB-->>CN: Order created CN-->>CO: Order snapshot CO-->>GW: Completed checkout + order reference GW-->>CP: Order confirmation CP-->>Shopper: Order confirmed

sequenceDiagram autonumber box rgb(42,24,5) Kodez / Retailer participant RB as Northstar Backend participant CN as Northstar connector participant OW as Orders & webhook service participant GW as UCP gateway (Kodez) end box rgb(5,46,22) Google - UCP Protocol / Merchant Center participant SEC as Security (signing) end box rgb(13,27,42) Client / Consumer / Customer participant CP as End User's Device (Laptop, PC, Phone) actor Shopper as End User / Customer end RB->>CN: Shipment / delivery / cancellation event CN->>OW: Canonical order event OW->>SEC: Sign webhook payload SEC-->>OW: Signed payload OW->>CP: Deliver signed order webhook alt Webhook failure OW->>OW: Retry with backoff OW->>OW: Dead-letter after max attempts end CP->>GW: GET /orders/{id} (verify current state) GW->>OW: Fetch order snapshot OW-->>GW: Current order state GW-->>CP: Order status timeline CP-->>Shopper: Show updated order status

flowchart TB subgraph CLIENT["Client / Consumer / Customer"] Demo["End user's device: consumer platform / AI shopping agent
(Gemini, ChatGPT, Perplexity, Amazon, Google Universal Cart, or other UCP clients)"] end subgraph GOOGLE["Google (UCP protocol, Merchant Center)"] Profile[Profile & capability discovery] Validation[Schema validation] Security[HTTP Message Signatures] end subgraph KODEZ["Kodez / Retailer"] Gateway[UCP REST gateway] Checkout[Checkout & order state machine] State[(UCP SQLite state store)] Orders[Order & webhook service] Northstar[Northstar Canonical Connector and Backend] Events[Event and trace store] end WebhookRelay[Signed webhook delivery] ClientWebhook[Client webhook receiver] Demo <--> Gateway Gateway --> Profile Profile --> Validation Validation --> Security Gateway --> Checkout Checkout --> Orders Checkout <--> State Checkout --> Northstar Orders <--> Northstar Northstar <--> Events Security --> Orders Orders --> WebhookRelay --> ClientWebhook style CLIENT fill:#0d1b2a,stroke:#38bdf8,stroke-width:2px,color:#f8fafc style GOOGLE fill:#052e16,stroke:#4ade80,stroke-width:2px,color:#f8fafc style KODEZ fill:#2a1805,stroke:#fb923c,stroke-width:2px,color:#f8fafc classDef clientNode fill:#1e293b,stroke:#38bdf8,stroke-width:1.5px,color:#f8fafc; classDef googleNode fill:#064e3b,stroke:#4ade80,stroke-width:1.5px,color:#f8fafc; classDef kodezNode fill:#431407,stroke:#fb923c,stroke-width:1.5px,color:#f8fafc; classDef webhookNode fill:#312e81,stroke:#a5b4fc,stroke-width:1.5px,color:#f8fafc; class Demo clientNode; class Profile,Validation,Security googleNode; class Gateway,Checkout,Orders,Northstar,Events kodezNode; class State kodezNode; class WebhookRelay webhookNode; class ClientWebhook clientNode;