# ethanz-zh/commerce-pilot architecture

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

- Interactive diagram: https://gitdiagram.com/ethanz-zh/commerce-pilot
- Repository: https://github.com/ethanz-zh/commerce-pilot

## Overview

CommercePilot is an e-commerce operations platform whose main workflow analyzes sales, inventory and pricing, retrieves policy evidence, checks compliance, then stages a campaign draft for human approval. The React console starts workflows and displays progress and results; the API also exposes a deterministic baseline and approval operations. The graph includes documented RAG, evaluation and platform-sync capabilities. Some subsystem links come from the README and tree rather than sampled implementation, so uncertain call-level wiring is omitted.

Main entry points: [`app/infrastructure/database.py`](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/infrastructure/database.py) (Commerce database), [`app/workflows/multi_agent.py`](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py) (Multi-agent workflow), [`app/api/routes.py`](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/api/routes.py) (API routes), [`app/rag/retrieval.py`](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/rag/retrieval.py) (Hybrid policy retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console_api["Console and API"]
  node_console["Operations console<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_api_routes["API routes<br/>[routes.py]"]
end

subgraph group_workflow["Workflow orchestration"]
  node_multi_workflow["Multi-agent workflow<br/>[multi_agent.py]"]
  node_baseline["Deterministic baseline<br/>[baseline.py]"]
  node_supervisor["Supervisor<br/>[multi_agent.py]"]
  node_sales_worker["Sales analysis<br/>[multi_agent.py]"]
  node_inventory_worker["Inventory pricing<br/>[multi_agent.py]"]
  node_policy_worker["Policy worker<br/>[multi_agent.py]"]
  node_strategy["Strategy planner<br/>[multi_agent.py]"]
  node_compliance_reviewer["Compliance reviewer<br/>[multi_agent.py]"]
  node_execution["Draft execution<br/>[multi_agent.py]"]
end

subgraph group_commerce["Commerce data and tools"]
  node_sales_tools["Sales tools<br/>[sales.py]"]
  node_inventory_tools["Inventory and pricing tools<br/>[inventory.py]"]
  node_campaign_tools["Campaign tools<br/>[campaigns.py]"]
  node_database[("Commerce database<br/>[database.py]")]
  node_domain_models["Business models<br/>[models.py]"]
end

subgraph group_intelligence["Models and policy RAG"]
  node_rag["Hybrid policy retrieval<br/>[retrieval.py]"]
  node_rag_index["Policy indexing<br/>[indexing.py]"]
  node_rag_provider["Embedding and reranking<br/>[providers.py]"]
  node_llm_provider["Agent model provider<br/>[providers.py]"]
  node_eval_agent["Agent evaluation<br/>[agent.py]"]
  node_eval_retrieval["Retrieval evaluation<br/>[retrieval.py]"]
end

subgraph group_integrations["Approval and platforms"]
  node_approval["Human approval<br/>[approval.py]"]
  node_checkpointer[("Workflow checkpointer<br/>[checkpoint.py]")]
  node_platform_sync["Platform data sync<br/>[sync.py]"]
  node_platform_factory["Gateway factory<br/>[factory.py]"]
  node_platform_gateway["Shop gateways<br/>[contracts.py]"]
  node_taobao["Taobao adapter<br/>[taobao.py]"]
  node_mock_gateway["Mock gateway<br/>[mock.py]"]
end

node_operator(("Operator"))
node_dashscope{{"DashScope services"}}

node_operator -->|"uses"| node_console
node_console -->|"requests workflows"| node_api_client
node_api_client -->|"calls API"| node_api_routes
node_api_routes -->|"runs"| node_multi_workflow
node_api_routes -->|"runs baseline"| node_baseline
node_multi_workflow -->|"starts graph"| node_supervisor
node_supervisor -->|"dispatches"| node_sales_worker
node_supervisor -->|"dispatches"| node_inventory_worker
node_supervisor -->|"dispatches"| node_policy_worker
node_sales_worker -->|"queries sales"| node_sales_tools
node_inventory_worker -->|"calculates pricing"| node_inventory_tools
node_policy_worker -->|"retrieves evidence"| node_rag
node_multi_workflow -->|"plans from evidence"| node_strategy
node_multi_workflow -->|"reviews plan"| node_compliance_reviewer
node_multi_workflow -->|"creates draft"| node_execution
node_execution -->|"stages campaign"| node_campaign_tools
node_sales_tools -->|"reads data"| node_database
node_inventory_tools -->|"reads data"| node_database
node_campaign_tools -->|"writes draft"| node_database
node_database -->|"stores"| node_domain_models
node_rag -->|"reads policies and chunks"| node_database
node_rag -->|"embeds and reranks"| node_rag_provider
node_rag_index -->|"creates embeddings"| node_rag_provider
node_rag_index -->|"stores indexed chunks"| node_database
node_multi_workflow -->|"requests decisions"| node_llm_provider
node_llm_provider -.->|"calls model"| node_dashscope
node_rag_provider -.->|"calls embedding and reranker"| node_dashscope
node_api_routes -->|"starts and decides"| node_approval
node_approval -->|"persists graph state"| node_checkpointer
node_approval -->|"stores tasks and decisions"| node_database
node_console -->|"views approval center"| node_approval
node_eval_agent -->|"evaluates runs"| node_multi_workflow
node_eval_retrieval -->|"scores retrieval"| node_rag
node_platform_sync -->|"selects gateway"| node_platform_factory
node_platform_factory -->|"provides gateway"| node_platform_gateway
node_platform_gateway -->|"implemented by"| node_mock_gateway
node_platform_gateway -.->|"implemented by"| node_taobao
node_platform_sync -->|"synchronizes business data"| node_database

click node_console "https://github.com/ethanz-zh/commerce-pilot/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/ethanz-zh/commerce-pilot/blob/main/frontend/src/api.ts"
click node_api_routes "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/api/routes.py"
click node_multi_workflow "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py"
click node_baseline "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/baseline.py"
click node_supervisor "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py"
click node_sales_worker "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py"
click node_inventory_worker "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py"
click node_policy_worker "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py"
click node_strategy "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py"
click node_compliance_reviewer "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py"
click node_execution "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py"
click node_sales_tools "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/tools/sales.py"
click node_inventory_tools "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/tools/inventory.py"
click node_campaign_tools "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/tools/campaigns.py"
click node_database "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/infrastructure/database.py"
click node_domain_models "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/domain/models.py"
click node_rag "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/rag/retrieval.py"
click node_rag_index "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/rag/indexing.py"
click node_rag_provider "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/rag/providers.py"
click node_llm_provider "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/llm/providers.py"
click node_eval_agent "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/evaluation/agent.py"
click node_eval_retrieval "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/evaluation/retrieval.py"
click node_approval "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/approval.py"
click node_checkpointer "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/infrastructure/checkpoint.py"
click node_platform_sync "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/sync.py"
click node_platform_factory "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/factory.py"
click node_platform_gateway "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/contracts.py"
click node_taobao "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/taobao.py"
click node_mock_gateway "https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/mock.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_console,node_api_client,node_api_routes toneBlue
class node_multi_workflow,node_baseline,node_supervisor,node_sales_worker,node_inventory_worker,node_policy_worker,node_strategy,node_compliance_reviewer,node_execution toneAmber
class node_sales_tools,node_inventory_tools,node_campaign_tools,node_database,node_domain_models toneMint
class node_rag,node_rag_index,node_rag_provider,node_llm_provider,node_eval_agent,node_eval_retrieval toneRose
class node_approval,node_checkpointer,node_platform_sync,node_platform_factory,node_platform_gateway,node_taobao,node_mock_gateway,node_operator,node_dashscope toneIndigo
```

## Components

### Console and API

- [Operations console](https://github.com/ethanz-zh/commerce-pilot/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/ethanz-zh/commerce-pilot/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [API routes](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/api/routes.py): `app/api/routes.py`

### Workflow orchestration

- [Multi-agent workflow](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py): `app/workflows/multi_agent.py`
- [Deterministic baseline](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/baseline.py): `app/workflows/baseline.py`
- [Supervisor](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py): `app/workflows/multi_agent.py`
- [Sales analysis](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py): `app/workflows/multi_agent.py`
- [Inventory pricing](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py): `app/workflows/multi_agent.py`
- [Policy worker](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py): `app/workflows/multi_agent.py`
- [Strategy planner](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py): `app/workflows/multi_agent.py`
- [Compliance reviewer](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py): `app/workflows/multi_agent.py`
- [Draft execution](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/multi_agent.py): `app/workflows/multi_agent.py`

### Commerce data and tools

- [Sales tools](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/tools/sales.py): `app/tools/sales.py`
- [Inventory and pricing tools](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/tools/inventory.py): `app/tools/inventory.py`
- [Campaign tools](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/tools/campaigns.py): `app/tools/campaigns.py`
- [Commerce database](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/infrastructure/database.py): `app/infrastructure/database.py`
- [Business models](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/domain/models.py): `app/domain/models.py`

### Models and policy RAG

- [Hybrid policy retrieval](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/rag/retrieval.py): `app/rag/retrieval.py`
- [Policy indexing](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/rag/indexing.py): `app/rag/indexing.py`
- [Embedding and reranking](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/rag/providers.py): `app/rag/providers.py`
- [Agent model provider](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/llm/providers.py): `app/llm/providers.py`
- [Agent evaluation](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/evaluation/agent.py): `app/evaluation/agent.py`
- [Retrieval evaluation](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/evaluation/retrieval.py): `app/evaluation/retrieval.py`

### Approval and platforms

- [Human approval](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/workflows/approval.py): `app/workflows/approval.py`
- [Workflow checkpointer](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/infrastructure/checkpoint.py): `app/infrastructure/checkpoint.py`
- [Platform data sync](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/sync.py): `app/platform/sync.py`
- [Gateway factory](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/factory.py): `app/platform/factory.py`
- [Shop gateways](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/contracts.py): `app/platform/contracts.py`
- [Taobao adapter](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/taobao.py): `app/platform/taobao.py`
- [Mock gateway](https://github.com/ethanz-zh/commerce-pilot/blob/main/app/platform/mock.py): `app/platform/mock.py`

### Other components

- **Operator**
- **DashScope services**

## Connections

- Operator → Operations console: uses
- Operations console → API client: requests workflows
- API client → API routes: calls API
- API routes → Multi-agent workflow: runs
- API routes → Deterministic baseline: runs baseline
- Multi-agent workflow → Supervisor: starts graph
- Supervisor → Sales analysis: dispatches
- Supervisor → Inventory pricing: dispatches
- Supervisor → Policy worker: dispatches
- Sales analysis → Sales tools: queries sales
- Inventory pricing → Inventory and pricing tools: calculates pricing
- Policy worker → Hybrid policy retrieval: retrieves evidence
- Multi-agent workflow → Strategy planner: plans from evidence
- Multi-agent workflow → Compliance reviewer: reviews plan
- Multi-agent workflow → Draft execution: creates draft
- Draft execution → Campaign tools: stages campaign
- Sales tools → Commerce database: reads data
- Inventory and pricing tools → Commerce database: reads data
- Campaign tools → Commerce database: writes draft
- Commerce database → Business models: stores
- Hybrid policy retrieval → Commerce database: reads policies and chunks
- Hybrid policy retrieval → Embedding and reranking: embeds and reranks
- Policy indexing → Embedding and reranking: creates embeddings
- Policy indexing → Commerce database: stores indexed chunks
- Multi-agent workflow → Agent model provider: requests decisions
- Agent model provider → DashScope services: calls model
- Embedding and reranking → DashScope services: calls embedding and reranker
- API routes → Human approval: starts and decides
- Human approval → Workflow checkpointer: persists graph state
- Human approval → Commerce database: stores tasks and decisions
- Operations console → Human approval: views approval center
- Agent evaluation → Multi-agent workflow: evaluates runs
- Retrieval evaluation → Hybrid policy retrieval: scores retrieval
- Platform data sync → Gateway factory: selects gateway
- Gateway factory → Shop gateways: provides gateway
- Shop gateways → Mock gateway: implemented by
- Shop gateways → Taobao adapter: implemented by
- Platform data sync → Commerce database: synchronizes business data