# simplifyai4u/commerce-agents-claude architecture

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

- Interactive diagram: https://gitdiagram.com/simplifyai4u/commerce-agents-claude
- Repository: https://github.com/simplifyai4u/commerce-agents-claude
- Video tour (about a minute): https://gitdiagram.com/simplifyai4u/commerce-agents-claude/video

## Overview

The repository provides two commerce agents: customer-facing shopping and staff-facing merchant operations. A user turn enters through one of three runtimes—Messages API, Agent SDK, or Managed Agents—and uses shared prompts, skills, tools, and safety controls against a deployment-provided commerce backend. Shopping supports discovery through cart and checkout-summary staging; merchant work spans business analysis through staged changes and human approval. Memory and presentation are shared runtime concerns. The README documents the main capability flows; sampled orchestrators and adapters support the runtime wiring shown here, but several implementations were not sampled.

Main entry points: [`merchant-agent/runtime-messages-api/merchant_agent_runtime/orchestrator.py`](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/runtime-messages-api/merchant_agent_runtime/orchestrator.py) (Merchant turn loop), [`shopping-agent/runtime-messages-api/shopping_agent_runtime/orchestrator.py`](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/runtime-messages-api/shopping_agent_runtime/orchestrator.py) (Shopping turn loop), [`merchant-agent/core/merchant_agent/executor.py`](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/executor.py) (Merchant executor), [`shopping-agent/core/shopping_agent/executor.py`](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/executor.py) (Shopping executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_common["Shared runtime"]
  node_common_memory[("Durable memory<br/>[memory.py]")]
  node_common_grounding["Grounding<br/>[grounding.py]"]
  node_common_presentation["Presentation events<br/>[presentation.py]"]
end

subgraph group_shopping["Shopping agent"]
  node_shopping_skills["Shopping skills"]
  node_shopping_prompt["Shopping prompt<br/>[prompt.py]"]
  node_shopping_tools["Shopping tool contracts<br/>[registry.py]"]
  node_shopping_executor["Shopping executor<br/>[executor.py]"]
  node_storefront_backend["Storefront backend<br/>[backend.py]"]
  node_shopping_gates["Shopping guardrails<br/>[gates.py]"]
end

subgraph group_merchant["Merchant agent"]
  node_merchant_skills["Merchant skills"]
  node_merchant_prompt["Merchant prompt<br/>[prompt.py]"]
  node_merchant_tools["Merchant tool contracts<br/>[registry.py]"]
  node_merchant_executor["Merchant executor<br/>[executor.py]"]
  node_merchant_backend["Merchant backend<br/>[backend.py]"]
  node_merchant_changes["Staged changes<br/>[changes.py]"]
  node_merchant_gates["Merchant guardrails<br/>[gates.py]"]
  node_merchant_analysis["Analysis delegate<br/>[analysis.py]"]
end

subgraph group_runtimes["Runtime adapters"]
  node_shopping_messages["Shopping turn loop<br/>[orchestrator.py]"]
  node_shopping_sdk["Shopping SDK adapter<br/>[agent.py]"]
  node_merchant_messages["Merchant turn loop<br/>[orchestrator.py]"]
  node_merchant_sdk["Merchant SDK adapter<br/>[agent.py]"]
end

subgraph group_managed["Managed interfaces"]
  node_storefront_mcp["Storefront MCP server"]
  node_merchant_mcp["Merchant MCP server"]
  node_merchant_digest["Scheduled digest"]
end

node_customer(("Customer"))
node_operator(("Store operator"))
node_claude_api["Claude Messages API"]
node_agent_sdk["Claude Agent SDK"]
node_approval(("Host approval surface"))

node_customer -->|"sends turn"| node_shopping_messages
node_shopping_messages -->|"requests completion"| node_claude_api
node_shopping_messages -->|"builds context"| node_shopping_prompt
node_shopping_messages -->|"dispatches tools"| node_shopping_executor
node_shopping_messages -->|"prefetches reads"| node_storefront_backend
node_shopping_messages -->|"reads and extracts"| node_common_memory
node_shopping_messages -->|"renders events"| node_common_presentation
node_shopping_prompt -->|"indexes skills"| node_shopping_skills
node_shopping_executor -->|"uses contracts"| node_shopping_tools
node_shopping_executor -->|"calls commerce"| node_storefront_backend
node_shopping_executor -->|"enforces gates"| node_shopping_gates
node_shopping_executor -->|"serves memory tools"| node_common_memory
node_shopping_sdk -->|"runs turns"| node_agent_sdk
node_shopping_sdk -.->|"connects tools"| node_storefront_mcp
node_storefront_mcp -->|"dispatches calls"| node_shopping_executor
node_operator -->|"sends turn"| node_merchant_messages
node_merchant_messages -->|"requests completion"| node_claude_api
node_merchant_messages -->|"builds context"| node_merchant_prompt
node_merchant_messages -->|"dispatches tools"| node_merchant_executor
node_merchant_messages -->|"prefetches context"| node_merchant_backend
node_merchant_messages -->|"reads and extracts"| node_common_memory
node_merchant_messages -->|"renders events"| node_common_presentation
node_merchant_prompt -->|"indexes skills"| node_merchant_skills
node_merchant_executor -->|"uses contracts"| node_merchant_tools
node_merchant_executor -->|"calls commerce"| node_merchant_backend
node_merchant_executor -->|"enforces gates"| node_merchant_gates
node_merchant_executor -->|"stages changes"| node_merchant_changes
node_merchant_executor -->|"serves memory tools"| node_common_memory
node_merchant_messages -->|"delegates analysis"| node_merchant_analysis
node_merchant_sdk -->|"runs turns"| node_agent_sdk
node_merchant_sdk -->|"connects tools"| node_merchant_mcp
node_merchant_mcp -->|"dispatches calls"| node_merchant_executor
node_merchant_changes -->|"requests approval"| node_approval
node_approval -->|"approves staged"| node_merchant_changes
node_merchant_digest -->|"reads merchant data"| node_merchant_backend

click node_shopping_skills "https://github.com/simplifyai4u/commerce-agents-claude/tree/main/shopping-agent/skills"
click node_shopping_prompt "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/prompt.py"
click node_shopping_tools "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/tools/registry.py"
click node_shopping_executor "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/executor.py"
click node_storefront_backend "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/backend.py"
click node_shopping_gates "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/gates.py"
click node_shopping_messages "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/runtime-messages-api/shopping_agent_runtime/orchestrator.py"
click node_shopping_sdk "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/runtime-agent-sdk/shopping_agent_sdk/agent.py"
click node_storefront_mcp "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/managed-agents/storefront-mcp-server/storefront_mcp_server.py"
click node_merchant_skills "https://github.com/simplifyai4u/commerce-agents-claude/tree/main/merchant-agent/skills"
click node_merchant_prompt "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/prompt.py"
click node_merchant_tools "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/tools/registry.py"
click node_merchant_executor "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/executor.py"
click node_merchant_backend "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/backend.py"
click node_merchant_changes "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/changes.py"
click node_merchant_gates "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/gates.py"
click node_merchant_analysis "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/runtime-messages-api/merchant_agent_runtime/analysis.py"
click node_merchant_messages "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/runtime-messages-api/merchant_agent_runtime/orchestrator.py"
click node_merchant_sdk "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/runtime-agent-sdk/merchant_agent_sdk/agent.py"
click node_merchant_mcp "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/managed-agents/merchant-mcp-server/merchant_mcp_server.py"
click node_common_memory "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/commerce-common/commerce_common/memory.py"
click node_common_grounding "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/commerce-common/commerce_common/grounding.py"
click node_common_presentation "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/commerce-common/commerce_common/presentation.py"
click node_merchant_digest "https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/managed-agents/scheduled-digest/run_morning_digest.py"

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_common_memory,node_common_grounding,node_common_presentation toneBlue
class node_shopping_skills,node_shopping_prompt,node_shopping_tools,node_shopping_executor,node_storefront_backend,node_shopping_gates toneAmber
class node_merchant_skills,node_merchant_prompt,node_merchant_tools,node_merchant_executor,node_merchant_backend,node_merchant_changes,node_merchant_gates,node_merchant_analysis,node_claude_api toneMint
class node_shopping_messages,node_shopping_sdk,node_merchant_messages,node_merchant_sdk toneRose
class node_storefront_mcp,node_merchant_mcp,node_merchant_digest,node_customer,node_operator,node_agent_sdk,node_approval toneIndigo
```

## Components

### Shared runtime

- [Durable memory](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/commerce-common/commerce_common/memory.py): `commerce-common/commerce_common/memory.py`
- [Grounding](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/commerce-common/commerce_common/grounding.py): `commerce-common/commerce_common/grounding.py`
- [Presentation events](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/commerce-common/commerce_common/presentation.py): `commerce-common/commerce_common/presentation.py`

### Shopping agent

- [Shopping skills](https://github.com/simplifyai4u/commerce-agents-claude/tree/main/shopping-agent/skills): `shopping-agent/skills`
- [Shopping prompt](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/prompt.py): `shopping-agent/core/shopping_agent/prompt.py`
- [Shopping tool contracts](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/tools/registry.py): `shopping-agent/core/shopping_agent/tools/registry.py`
- [Shopping executor](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/executor.py): `shopping-agent/core/shopping_agent/executor.py`
- [Storefront backend](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/backend.py): `shopping-agent/core/shopping_agent/backend.py`
- [Shopping guardrails](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/core/shopping_agent/gates.py): `shopping-agent/core/shopping_agent/gates.py`

### Merchant agent

- [Merchant skills](https://github.com/simplifyai4u/commerce-agents-claude/tree/main/merchant-agent/skills): `merchant-agent/skills`
- [Merchant prompt](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/prompt.py): `merchant-agent/core/merchant_agent/prompt.py`
- [Merchant tool contracts](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/tools/registry.py): `merchant-agent/core/merchant_agent/tools/registry.py`
- [Merchant executor](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/executor.py): `merchant-agent/core/merchant_agent/executor.py`
- [Merchant backend](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/backend.py): `merchant-agent/core/merchant_agent/backend.py`
- [Staged changes](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/changes.py): `merchant-agent/core/merchant_agent/changes.py`
- [Merchant guardrails](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/core/merchant_agent/gates.py): `merchant-agent/core/merchant_agent/gates.py`
- [Analysis delegate](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/runtime-messages-api/merchant_agent_runtime/analysis.py): `merchant-agent/runtime-messages-api/merchant_agent_runtime/analysis.py`

### Runtime adapters

- [Shopping turn loop](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/runtime-messages-api/shopping_agent_runtime/orchestrator.py): `shopping-agent/runtime-messages-api/shopping_agent_runtime/orchestrator.py`
- [Shopping SDK adapter](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/runtime-agent-sdk/shopping_agent_sdk/agent.py): `shopping-agent/runtime-agent-sdk/shopping_agent_sdk/agent.py`
- [Merchant turn loop](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/runtime-messages-api/merchant_agent_runtime/orchestrator.py): `merchant-agent/runtime-messages-api/merchant_agent_runtime/orchestrator.py`
- [Merchant SDK adapter](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/runtime-agent-sdk/merchant_agent_sdk/agent.py): `merchant-agent/runtime-agent-sdk/merchant_agent_sdk/agent.py`

### Managed interfaces

- [Storefront MCP server](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/shopping-agent/managed-agents/storefront-mcp-server/storefront_mcp_server.py): `shopping-agent/managed-agents/storefront-mcp-server/storefront_mcp_server.py`
- [Merchant MCP server](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/managed-agents/merchant-mcp-server/merchant_mcp_server.py): `merchant-agent/managed-agents/merchant-mcp-server/merchant_mcp_server.py`
- [Scheduled digest](https://github.com/simplifyai4u/commerce-agents-claude/blob/main/merchant-agent/managed-agents/scheduled-digest/run_morning_digest.py): `merchant-agent/managed-agents/scheduled-digest/run_morning_digest.py`

### Other components

- **Customer**
- **Store operator**
- **Claude Messages API**
- **Claude Agent SDK**
- **Host approval surface**

## Connections

- Customer → Shopping turn loop: sends turn
- Shopping turn loop → Claude Messages API: requests completion
- Shopping turn loop → Shopping prompt: builds context
- Shopping turn loop → Shopping executor: dispatches tools
- Shopping turn loop → Storefront backend: prefetches reads
- Shopping turn loop → Durable memory: reads and extracts
- Shopping turn loop → Presentation events: renders events
- Shopping prompt → Shopping skills: indexes skills
- Shopping executor → Shopping tool contracts: uses contracts
- Shopping executor → Storefront backend: calls commerce
- Shopping executor → Shopping guardrails: enforces gates
- Shopping executor → Durable memory: serves memory tools
- Shopping SDK adapter → Claude Agent SDK: runs turns
- Shopping SDK adapter → Storefront MCP server: connects tools
- Storefront MCP server → Shopping executor: dispatches calls
- Store operator → Merchant turn loop: sends turn
- Merchant turn loop → Claude Messages API: requests completion
- Merchant turn loop → Merchant prompt: builds context
- Merchant turn loop → Merchant executor: dispatches tools
- Merchant turn loop → Merchant backend: prefetches context
- Merchant turn loop → Durable memory: reads and extracts
- Merchant turn loop → Presentation events: renders events
- Merchant prompt → Merchant skills: indexes skills
- Merchant executor → Merchant tool contracts: uses contracts
- Merchant executor → Merchant backend: calls commerce
- Merchant executor → Merchant guardrails: enforces gates
- Merchant executor → Staged changes: stages changes
- Merchant executor → Durable memory: serves memory tools
- Merchant turn loop → Analysis delegate: delegates analysis
- Merchant SDK adapter → Claude Agent SDK: runs turns
- Merchant SDK adapter → Merchant MCP server: connects tools
- Merchant MCP server → Merchant executor: dispatches calls
- Staged changes → Host approval surface: requests approval
- Host approval surface → Staged changes: approves staged
- Scheduled digest → Merchant backend: reads merchant data