# universal-commerce-protocol/samples architecture

> Architecture diagram of the GitHub repository universal-commerce-protocol/samples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/universal-commerce-protocol/samples
- Repository: https://github.com/universal-commerce-protocol/samples

## Overview

This repository contains three UCP merchant-server samples plus an A2A retail agent and chat client. The user journey is merchant discovery, shopping and checkout, payment, then order handling; the A2A variant adds conversational product selection and payment credentials. The graph preserves the documented Python and Node.js server capabilities and the agent’s shopping flow. Some subsystems are represented from README or index references rather than sampled implementation details, so uncertain internal wiring is omitted.

Main entry points: [`rest/python/server/server.py`](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/server.py) (FastAPI Service), [`rest/python/server/services/checkout_service.py`](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/services/checkout_service.py) (Checkout Lifecycle), [`rest/nodejs/src/index.ts`](https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/index.ts) (Hono Service), [`a2a/chat-client/App.tsx`](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/App.tsx) (Chat Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_a2a["A2A Retail Agent"]
  node_agent["Shopping Agent<br/>[agent.py]"]
  node_agent_runtime["Agent Runtime<br/>[agent_executor.py]"]
  node_store[("Product Store<br/>[store.py]")]
  node_product_types["Product Types<br/>[product_types.py]"]
  node_agent_payment["Payment Processor"]
  node_ucp_extension["UCP Extension<br/>[ucp_extension.py]"]
end

subgraph group_python["Python Merchant Server"]
  node_python_server["FastAPI Service<br/>[server.py]"]
  node_python_routes["Generated UCP Routes<br/>[ucp_routes.py]"]
  node_python_impl["Route Implementation"]
  node_python_discovery["Discovery Route<br/>[discovery.py]"]
  node_python_mcp["MCP Route<br/>[mcp.py]"]
  node_python_order["Order Route<br/>[order.py]"]
  node_python_checkout["Checkout Lifecycle"]
  node_python_cart["Cart Service<br/>[cart_service.py]"]
  node_python_fulfillment["Fulfillment Options"]
  node_python_db[("Commerce Database<br/>[db.py]")]
  node_python_models["Commerce Models<br/>[models.py]"]
  node_python_signing["Request Signing<br/>[ucp_signing.py]"]
  node_python_webhook["Webhook Signing<br/>[webhook_signer.py]"]
  node_happy_client["Happy-Path Client"]
end

subgraph group_node["Node Merchant Server"]
  node_node_server["Hono Service<br/>[index.ts]"]
  node_node_discovery["Discovery API<br/>[discovery.ts]"]
  node_node_checkout["Checkout API<br/>[checkout.ts]"]
  node_node_order["Order API<br/>[order.ts]"]
  node_node_testing["Simulation API<br/>[testing.ts]"]
  node_node_db[("Commerce Database<br/>[db.ts]")]
  node_node_transactions[("Transaction Store<br/>[transactions.ts]")]
end

subgraph group_client["A2A Chat Client"]
  node_chat_app["Chat Application<br/>[App.tsx]"]
  node_chat_input["Chat Input<br/>[ChatInput.tsx]"]
  node_chat_messages["Message Renderer<br/>[ChatMessage.tsx]"]
  node_checkout_ui["Checkout UI<br/>[Checkout.tsx]"]
  node_payment_ui["Payment Confirmation"]
end

node_shopper(("Shopper"))
node_platform(("Commerce Platform"))

node_shopper -->|"uses"| node_chat_app
node_chat_app -->|"renders"| node_chat_input
node_chat_app -->|"renders"| node_chat_messages
node_chat_app -->|"sends chat"| node_agent
node_chat_app -->|"renders checkout"| node_chat_messages
node_chat_messages -->|"renders"| node_checkout_ui
node_chat_messages -->|"renders"| node_payment_ui
node_agent_runtime -->|"runs"| node_agent
node_agent -->|"queries"| node_store
node_store -->|"uses types"| node_product_types
node_agent -->|"uses payments"| node_agent_payment
node_platform -->|"calls UCP"| node_python_server
node_python_server -->|"includes routes"| node_python_routes
node_python_server -->|"applies implementation"| node_python_impl
node_python_server -->|"includes route"| node_python_discovery
node_python_server -->|"includes route"| node_python_mcp
node_python_server -->|"includes route"| node_python_order
node_python_impl -->|"delegates checkout"| node_python_checkout
node_python_impl -->|"delegates cart"| node_python_cart
node_python_checkout -->|"calculates options"| node_python_fulfillment
node_python_checkout -->|"reads and writes"| node_python_db
node_python_cart -->|"reads and writes"| node_python_db
node_python_checkout -->|"uses models"| node_python_models
node_python_checkout -->|"signs deliveries"| node_python_webhook
node_python_webhook -->|"uses signing"| node_python_signing
node_happy_client -->|"discovers and checks out"| node_platform
node_platform -->|"calls UCP"| node_node_server
node_node_server -->|"routes discovery"| node_node_discovery
node_node_server -->|"routes checkout"| node_node_checkout
node_node_server -->|"routes orders"| node_node_order
node_node_server -->|"routes simulation"| node_node_testing
node_node_checkout -->|"initializes storage"| node_node_db
node_node_checkout -->|"stores transactions"| node_node_transactions

click node_agent "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/agent.py"
click node_agent_runtime "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/agent_executor.py"
click node_store "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/store.py"
click node_product_types "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/models/product_types.py"
click node_agent_payment "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/payment_processor.py"
click node_ucp_extension "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/a2a_extensions/ucp_extension.py"
click node_chat_app "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/App.tsx"
click node_chat_input "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/components/ChatInput.tsx"
click node_chat_messages "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/components/ChatMessage.tsx"
click node_checkout_ui "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/components/Checkout.tsx"
click node_payment_ui "https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/components/PaymentConfirmation.tsx"
click node_python_server "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/server.py"
click node_python_routes "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/generated_routes/ucp_routes.py"
click node_python_impl "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/routes/ucp_implementation.py"
click node_python_discovery "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/routes/discovery.py"
click node_python_mcp "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/routes/mcp.py"
click node_python_order "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/routes/order.py"
click node_python_checkout "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/services/checkout_service.py"
click node_python_cart "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/services/cart_service.py"
click node_python_fulfillment "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/services/fulfillment_service.py"
click node_python_db "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/db.py"
click node_python_models "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/models.py"
click node_python_signing "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/ucp_signing.py"
click node_python_webhook "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/webhook_signer.py"
click node_happy_client "https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/client/flower_shop/simple_happy_path_client.py"
click node_node_server "https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/index.ts"
click node_node_discovery "https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/api/discovery.ts"
click node_node_checkout "https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/api/checkout.ts"
click node_node_order "https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/api/order.ts"
click node_node_testing "https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/api/testing.ts"
click node_node_db "https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/data/db.ts"
click node_node_transactions "https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/data/transactions.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_agent_runtime,node_store,node_product_types,node_agent_payment,node_ucp_extension toneBlue
class node_python_server,node_python_routes,node_python_impl,node_python_discovery,node_python_mcp,node_python_order,node_python_checkout,node_python_cart,node_python_fulfillment,node_python_db,node_python_models,node_python_signing,node_python_webhook,node_happy_client toneAmber
class node_node_server,node_node_discovery,node_node_checkout,node_node_order,node_node_testing,node_node_db,node_node_transactions toneMint
class node_chat_app,node_chat_input,node_chat_messages,node_checkout_ui,node_payment_ui toneRose
class node_shopper,node_platform toneIndigo
```

## Components

### A2A Retail Agent

- [Shopping Agent](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/agent.py): `a2a/business_agent/src/business_agent/agent.py`
- [Agent Runtime](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/agent_executor.py): `a2a/business_agent/src/business_agent/agent_executor.py`
- [Product Store](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/store.py): `a2a/business_agent/src/business_agent/store.py`
- [Product Types](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/models/product_types.py): `a2a/business_agent/src/business_agent/models/product_types.py`
- [Payment Processor](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/payment_processor.py): `a2a/business_agent/src/business_agent/payment_processor.py`
- [UCP Extension](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/business_agent/src/business_agent/a2a_extensions/ucp_extension.py): `a2a/business_agent/src/business_agent/a2a_extensions/ucp_extension.py`

### Python Merchant Server

- [FastAPI Service](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/server.py): `rest/python/server/server.py`
- [Generated UCP Routes](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/generated_routes/ucp_routes.py): `rest/python/server/generated_routes/ucp_routes.py`
- [Route Implementation](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/routes/ucp_implementation.py): `rest/python/server/routes/ucp_implementation.py`
- [Discovery Route](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/routes/discovery.py): `rest/python/server/routes/discovery.py`
- [MCP Route](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/routes/mcp.py): `rest/python/server/routes/mcp.py`
- [Order Route](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/routes/order.py): `rest/python/server/routes/order.py`
- [Checkout Lifecycle](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/services/checkout_service.py): `rest/python/server/services/checkout_service.py`
- [Cart Service](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/services/cart_service.py): `rest/python/server/services/cart_service.py`
- [Fulfillment Options](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/services/fulfillment_service.py): `rest/python/server/services/fulfillment_service.py`
- [Commerce Database](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/db.py): `rest/python/server/db.py`
- [Commerce Models](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/models.py): `rest/python/server/models.py`
- [Request Signing](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/ucp_signing.py): `rest/python/server/ucp_signing.py`
- [Webhook Signing](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/server/webhook_signer.py): `rest/python/server/webhook_signer.py`
- [Happy-Path Client](https://github.com/universal-commerce-protocol/samples/blob/main/rest/python/client/flower_shop/simple_happy_path_client.py): `rest/python/client/flower_shop/simple_happy_path_client.py`

### Node Merchant Server

- [Hono Service](https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/index.ts): `rest/nodejs/src/index.ts`
- [Discovery API](https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/api/discovery.ts): `rest/nodejs/src/api/discovery.ts`
- [Checkout API](https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/api/checkout.ts): `rest/nodejs/src/api/checkout.ts`
- [Order API](https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/api/order.ts): `rest/nodejs/src/api/order.ts`
- [Simulation API](https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/api/testing.ts): `rest/nodejs/src/api/testing.ts`
- [Commerce Database](https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/data/db.ts): `rest/nodejs/src/data/db.ts`
- [Transaction Store](https://github.com/universal-commerce-protocol/samples/blob/main/rest/nodejs/src/data/transactions.ts): `rest/nodejs/src/data/transactions.ts`

### A2A Chat Client

- [Chat Application](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/App.tsx): `a2a/chat-client/App.tsx`
- [Chat Input](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/components/ChatInput.tsx): `a2a/chat-client/components/ChatInput.tsx`
- [Message Renderer](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/components/ChatMessage.tsx): `a2a/chat-client/components/ChatMessage.tsx`
- [Checkout UI](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/components/Checkout.tsx): `a2a/chat-client/components/Checkout.tsx`
- [Payment Confirmation](https://github.com/universal-commerce-protocol/samples/blob/main/a2a/chat-client/components/PaymentConfirmation.tsx): `a2a/chat-client/components/PaymentConfirmation.tsx`

### Other components

- **Shopper**
- **Commerce Platform**

## Connections

- Shopper → Chat Application: uses
- Chat Application → Chat Input: renders (evidence: `a2a/chat-client/App.tsx`)
- Chat Application → Message Renderer: renders (evidence: `a2a/chat-client/App.tsx`)
- Chat Application → Shopping Agent: sends chat (evidence: `a2a/chat-client/App.tsx`)
- Chat Application → Message Renderer: renders checkout (evidence: `a2a/chat-client/components/ChatMessage.tsx`)
- Message Renderer → Checkout UI: renders (evidence: `a2a/chat-client/components/ChatMessage.tsx`)
- Message Renderer → Payment Confirmation: renders (evidence: `a2a/chat-client/components/ChatMessage.tsx`)
- Agent Runtime → Shopping Agent: runs (evidence: `a2a/business_agent/src/business_agent/main.py`)
- Shopping Agent → Product Store: queries (evidence: `a2a/business_agent/src/business_agent/agent.py`)
- Product Store → Product Types: uses types (evidence: `a2a/business_agent/src/business_agent/store.py`)
- Shopping Agent → Payment Processor: uses payments (evidence: `a2a/business_agent/src/business_agent/agent.py`)
- Commerce Platform → FastAPI Service: calls UCP
- FastAPI Service → Generated UCP Routes: includes routes (evidence: `rest/python/server/server.py`)
- FastAPI Service → Route Implementation: applies implementation (evidence: `rest/python/server/server.py`)
- FastAPI Service → Discovery Route: includes route (evidence: `rest/python/server/server.py`)
- FastAPI Service → MCP Route: includes route (evidence: `rest/python/server/server.py`)
- FastAPI Service → Order Route: includes route (evidence: `rest/python/server/server.py`)
- Route Implementation → Checkout Lifecycle: delegates checkout (evidence: `rest/python/server/routes/ucp_implementation.py`)
- Route Implementation → Cart Service: delegates cart (evidence: `rest/python/server/routes/ucp_implementation.py`)
- Checkout Lifecycle → Fulfillment Options: calculates options (evidence: `rest/python/server/services/checkout_service.py`)
- Checkout Lifecycle → Commerce Database: reads and writes (evidence: `rest/python/server/services/checkout_service.py`)
- Cart Service → Commerce Database: reads and writes (evidence: `rest/python/server/services/cart_service.py`)
- Checkout Lifecycle → Commerce Models: uses models (evidence: `rest/python/server/services/checkout_service.py`)
- Checkout Lifecycle → Webhook Signing: signs deliveries (evidence: `rest/python/server/services/checkout_service.py`)
- Webhook Signing → Request Signing: uses signing (evidence: `rest/python/server/webhook_signer.py`)
- Happy-Path Client → Commerce Platform: discovers and checks out
- Commerce Platform → Hono Service: calls UCP
- Hono Service → Discovery API: routes discovery (evidence: `rest/nodejs/src/index.ts`)
- Hono Service → Checkout API: routes checkout (evidence: `rest/nodejs/src/index.ts`)
- Hono Service → Order API: routes orders (evidence: `rest/nodejs/src/index.ts`)
- Hono Service → Simulation API: routes simulation (evidence: `rest/nodejs/src/index.ts`)
- Checkout API → Commerce Database: initializes storage (evidence: `rest/nodejs/src/index.ts`)
- Checkout API → Transaction Store: stores transactions (evidence: `rest/nodejs/src/api/checkout.ts`)
