# srmk-2005/agentic-commerce-platform architecture

> Architecture diagram of the GitHub repository srmk-2005/agentic-commerce-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/srmk-2005/agentic-commerce-platform
- Repository: https://github.com/srmk-2005/agentic-commerce-platform

## Overview

This platform combines merchant-facing commerce operations and growth recommendations with machine-readable commerce APIs for external buyers. A typical buyer flow discovers a merchant and catalog, searches and verifies stock, creates an order, then proposes payment; merchant payment approval and Razorpay verification gate execution. Merchant growth actions also pass through safety and human approval governance. The README documents these capabilities; arrows below are limited to relationships visible in excerpts, the SOURCE INDEX references, or README statements, so several unsampled routes and agent stages are shown without speculative call chains.

Main entry points: [`backend/app/payments/payment_service.py`](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/payments/payment_service.py) (Payment orchestration), [`frontend/src/App.tsx`](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/App.tsx) (React application), [`backend/app/agent_commerce/service.py`](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/agent_commerce/service.py) (Agent commerce orchestration), [`backend/app/ai_buyer/agent.py`](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/ai_buyer/agent.py) (AI buyer pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Merchant and Buyer UI"]
  node_web_app["React application<br/>[App.tsx]"]
  node_buyer_ui["Buyer sandbox<br/>[AiBuyerPage.tsx]"]
  node_payment_ui["Payment approval"]
  node_demo_ui["Commerce demo<br/>[JudgeDemoPage.tsx]"]
  node_growth_ui["Growth workspace"]
  node_api_client["Frontend API client<br/>[api.ts]"]
  node_buyer_service["Buyer API service<br/>[buyerService.ts]"]
  node_payment_client["Payment API service<br/>[paymentService.ts]"]
end

subgraph group_agentic["AI Commerce"]
  node_buyer_agent["AI buyer pipeline<br/>[agent.py]"]
  node_commerce_protocol["Agent commerce protocol<br/>[protocol.py]"]
  node_agent_service["Agent commerce orchestration<br/>[service.py]"]
  node_discovery["Merchant discovery<br/>[discovery.py]"]
end

subgraph group_commerce["Commerce Operations"]
  node_commerce_api["AI catalog and orders<br/>[service.py]"]
  node_catalog_search["Catalog search<br/>[catalog.py]"]
  node_order_engine["Order creation<br/>[order_service.py]"]
  node_payment_engine["Payment orchestration<br/>[payment_service.py]"]
  node_razorpay["Razorpay adapter"]
end

subgraph group_governance["Growth and Governance"]
  node_growth_agent["Growth analysis agent<br/>[nodes.py]"]
  node_growth_actions["Growth actions<br/>[growth_service.py]"]
  node_safety["Safety policies<br/>[safety_service.py]"]
  node_audit["Audit ledger<br/>[audit_service.py]"]
end

subgraph group_platform["Backend and Persistence"]
  node_api_server["FastAPI application<br/>[main.py]"]
  node_database[("Relational database<br/>[models.py]")]
end

node_merchant(("Merchant operator"))
node_external_buyer(("External AI buyer"))
node_razorpay_api{{"Razorpay test service"}}

node_merchant -->|"uses"| node_web_app
node_external_buyer -->|"discovers and orders"| node_commerce_api
node_web_app -->|"routes to"| node_buyer_ui
node_web_app -->|"routes to"| node_payment_ui
node_web_app -->|"routes to"| node_demo_ui
node_web_app -->|"routes to"| node_growth_ui
node_buyer_ui -->|"calls"| node_buyer_service
node_demo_ui -->|"calls"| node_payment_client
node_payment_ui -->|"calls"| node_payment_client
node_buyer_service -->|"requests through"| node_api_client
node_payment_client -->|"requests through"| node_api_client
node_api_client -->|"HTTP requests"| node_api_server
node_api_server -->|"registers routes"| node_commerce_api
node_api_server -->|"registers routes"| node_agent_service
node_api_server -->|"registers routes"| node_payment_engine
node_buyer_agent -.->|"discovers capabilities"| node_discovery
node_buyer_agent -.->|"queries catalog"| node_catalog_search
node_buyer_agent -.->|"creates order"| node_order_engine
node_buyer_agent -.->|"proposes payment"| node_payment_engine
node_agent_service -->|"loads contract"| node_discovery
node_agent_service -->|"searches products"| node_catalog_search
node_agent_service -->|"creates orders"| node_order_engine
node_agent_service -->|"proposes payment"| node_payment_engine
node_commerce_api -->|"uses catalog"| node_catalog_search
node_commerce_api -->|"reads commerce data"| node_database
node_order_engine -->|"writes orders and stock"| node_database
node_growth_agent -.->|"proposes actions"| node_growth_actions
node_growth_actions -->|"checks actions"| node_safety
node_growth_actions -->|"records events"| node_audit
node_payment_engine -->|"creates and verifies orders"| node_razorpay
node_razorpay -.->|"test-mode requests"| node_razorpay_api
node_payment_engine -->|"records decisions"| node_audit
node_payment_engine -->|"reads and updates payments"| node_database
node_audit -->|"persists events"| node_database

click node_web_app "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/App.tsx"
click node_buyer_ui "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/pages/AiBuyerPage.tsx"
click node_payment_ui "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/pages/PaymentApprovalPage.tsx"
click node_demo_ui "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/pages/JudgeDemoPage.tsx"
click node_growth_ui "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/pages/AiAssistantPage.tsx"
click node_api_client "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/services/api.ts"
click node_buyer_service "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/services/buyerService.ts"
click node_payment_client "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/services/paymentService.ts"
click node_buyer_agent "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/ai_buyer/agent.py"
click node_commerce_protocol "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/agent_commerce/protocol.py"
click node_agent_service "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/agent_commerce/service.py"
click node_discovery "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/agent_commerce/discovery.py"
click node_commerce_api "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/commerce/service.py"
click node_catalog_search "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/commerce/catalog.py"
click node_order_engine "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/commerce/order_service.py"
click node_growth_agent "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/agent/nodes.py"
click node_growth_actions "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/services/growth_service.py"
click node_safety "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/services/safety_service.py"
click node_audit "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/services/audit_service.py"
click node_payment_engine "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/payments/payment_service.py"
click node_razorpay "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/payments/razorpay_service.py"
click node_api_server "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/main.py"
click node_database "https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/db/models.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_web_app,node_buyer_ui,node_payment_ui,node_demo_ui,node_growth_ui,node_api_client,node_buyer_service,node_payment_client toneBlue
class node_buyer_agent,node_commerce_protocol,node_agent_service,node_discovery toneAmber
class node_commerce_api,node_catalog_search,node_order_engine,node_payment_engine,node_razorpay toneMint
class node_growth_agent,node_growth_actions,node_safety,node_audit toneRose
class node_api_server,node_database,node_merchant,node_external_buyer,node_razorpay_api toneIndigo
```

## Components

### Merchant and Buyer UI

- [React application](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Buyer sandbox](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/pages/AiBuyerPage.tsx): `frontend/src/pages/AiBuyerPage.tsx`
- [Payment approval](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/pages/PaymentApprovalPage.tsx): `frontend/src/pages/PaymentApprovalPage.tsx`
- [Commerce demo](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/pages/JudgeDemoPage.tsx): `frontend/src/pages/JudgeDemoPage.tsx`
- [Growth workspace](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/pages/AiAssistantPage.tsx): `frontend/src/pages/AiAssistantPage.tsx`
- [Frontend API client](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Buyer API service](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/services/buyerService.ts): `frontend/src/services/buyerService.ts`
- [Payment API service](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/frontend/src/services/paymentService.ts): `frontend/src/services/paymentService.ts`

### AI Commerce

- [AI buyer pipeline](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/ai_buyer/agent.py): `backend/app/ai_buyer/agent.py`
- [Agent commerce protocol](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/agent_commerce/protocol.py): `backend/app/agent_commerce/protocol.py`
- [Agent commerce orchestration](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/agent_commerce/service.py): `backend/app/agent_commerce/service.py`
- [Merchant discovery](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/agent_commerce/discovery.py): `backend/app/agent_commerce/discovery.py`

### Commerce Operations

- [AI catalog and orders](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/commerce/service.py): `backend/app/commerce/service.py`
- [Catalog search](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/commerce/catalog.py): `backend/app/commerce/catalog.py`
- [Order creation](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/commerce/order_service.py): `backend/app/commerce/order_service.py`
- [Payment orchestration](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/payments/payment_service.py): `backend/app/payments/payment_service.py`
- [Razorpay adapter](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/payments/razorpay_service.py): `backend/app/payments/razorpay_service.py`

### Growth and Governance

- [Growth analysis agent](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/agent/nodes.py): `backend/app/agent/nodes.py`
- [Growth actions](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/services/growth_service.py): `backend/app/services/growth_service.py`
- [Safety policies](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/services/safety_service.py): `backend/app/services/safety_service.py`
- [Audit ledger](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`

### Backend and Persistence

- [FastAPI application](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/main.py): `backend/app/main.py`
- [Relational database](https://github.com/srmk-2005/agentic-commerce-platform/blob/main/backend/app/db/models.py): `backend/app/db/models.py`

### Other components

- **Merchant operator**
- **External AI buyer**
- **Razorpay test service**

## Connections

- Merchant operator → React application: uses
- External AI buyer → AI catalog and orders: discovers and orders
- React application → Buyer sandbox: routes to (evidence: `frontend/src/App.tsx`)
- React application → Payment approval: routes to (evidence: `frontend/src/App.tsx`)
- React application → Commerce demo: routes to (evidence: `frontend/src/App.tsx`)
- React application → Growth workspace: routes to (evidence: `frontend/src/App.tsx`)
- Buyer sandbox → Buyer API service: calls (evidence: `frontend/src/pages/AiBuyerPage.tsx`)
- Commerce demo → Payment API service: calls (evidence: `frontend/src/pages/JudgeDemoPage.tsx`)
- Payment approval → Payment API service: calls (evidence: `frontend/src/pages/PaymentApprovalPage.tsx`)
- Buyer API service → Frontend API client: requests through
- Payment API service → Frontend API client: requests through (evidence: `frontend/src/services/paymentService.ts`)
- Frontend API client → FastAPI application: HTTP requests (evidence: `frontend/src/services/api.ts`)
- FastAPI application → AI catalog and orders: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Agent commerce orchestration: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Payment orchestration: registers routes (evidence: `backend/app/main.py`)
- AI buyer pipeline → Merchant discovery: discovers capabilities
- AI buyer pipeline → Catalog search: queries catalog
- AI buyer pipeline → Order creation: creates order
- AI buyer pipeline → Payment orchestration: proposes payment
- Agent commerce orchestration → Merchant discovery: loads contract (evidence: `backend/app/agent_commerce/service.py`)
- Agent commerce orchestration → Catalog search: searches products (evidence: `backend/app/agent_commerce/service.py`)
- Agent commerce orchestration → Order creation: creates orders (evidence: `backend/app/agent_commerce/service.py`)
- Agent commerce orchestration → Payment orchestration: proposes payment (evidence: `backend/app/agent_commerce/service.py`)
- AI catalog and orders → Catalog search: uses catalog (evidence: `backend/app/commerce/service.py`)
- AI catalog and orders → Relational database: reads commerce data (evidence: `backend/app/commerce/service.py`)
- Order creation → Relational database: writes orders and stock (evidence: `backend/app/commerce/order_service.py`)
- Growth analysis agent → Growth actions: proposes actions
- Growth actions → Safety policies: checks actions (evidence: `backend/app/services/growth_service.py`)
- Growth actions → Audit ledger: records events (evidence: `backend/app/services/growth_service.py`)
- Payment orchestration → Razorpay adapter: creates and verifies orders (evidence: `backend/app/payments/payment_service.py`)
- Razorpay adapter → Razorpay test service: test-mode requests
- Payment orchestration → Audit ledger: records decisions (evidence: `backend/app/payments/payment_service.py`)
- Payment orchestration → Relational database: reads and updates payments (evidence: `backend/app/payments/payment_service.py`)
- Audit ledger → Relational database: persists events (evidence: `backend/app/services/audit_service.py`)