# harshdubey23/sellable architecture

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

- Interactive diagram: https://gitdiagram.com/harshdubey23/sellable
- Repository: https://github.com/harshdubey23/sellable

## Overview

SELLABLE lets a user authorize a bounded shopping mission, then lets an AI agent propose products without specifying price or payee. The server prices proposals from its catalog and the deterministic gateway rejects or approves them; approval is bound to the exact cart before durable payment execution. The README documents recovery and audit guarantees. The map also retains discovery, negotiation, growth, and web-facing capabilities represented in the source tree. Some subsystem internals were not sampled, so uncertain connections are omitted.

Main entry points: [`apps/api/gateway/engine.py`](https://github.com/harshdubey23/sellable/blob/main/apps/api/gateway/engine.py) (Policy Gateway), [`apps/api/audit/chain.py`](https://github.com/harshdubey23/sellable/blob/main/apps/api/audit/chain.py) (Audit Chain), [`apps/api/products.py`](https://github.com/harshdubey23/sellable/blob/main/apps/api/products.py) (Product Catalog), [`apps/api/execution.py`](https://github.com/harshdubey23/sellable/blob/main/apps/api/execution.py) (Execution Machine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shopping["Shopping Experience"]
  node_agent["Buyer Agent<br/>[buyer.py]"]
  node_discovery["Market Discovery<br/>[pipeline.py]"]
  node_catalog[("Product Catalog<br/>[products.py]")]
  node_negotiation["Negotiation Engine<br/>[engine.py]"]
end

subgraph group_control["Safety Control"]
  node_mission["Signed Mission<br/>[missions.py]"]
  node_gateway{{"Policy Gateway<br/>[engine.py]"}}
  node_approval["Approval Binding<br/>[approval.py]"]
  node_mandates["User Mandates<br/>[mandates.py]"]
  node_audit[("Audit Chain<br/>[chain.py]")]
  node_db[("Application Store<br/>[db.py]")]
  node_chaos["Chaos Evaluator<br/>[engine.py]"]
end

subgraph group_payments["Payment Lifecycle"]
  node_execution["Execution Machine<br/>[execution.py]"]
  node_provider["Payment Provider"]
  node_razorpay["Razorpay<br/>[razorpay_client.py]"]
  node_recovery["Payment Recovery<br/>[engine.py]"]
  node_webhook["Webhook Receiver<br/>[receiver.py]"]
end

subgraph group_insight["Commerce Intelligence"]
  node_growth["Growth Engine<br/>[engine.py]"]
  node_intelligence["Growth Intelligence<br/>[intelligence.py]"]
end

subgraph group_interfaces["Interfaces"]
  node_mcp["MCP Server<br/>[server.py]"]
  node_mcpstate[("MCP State<br/>[store.py]")]
  node_web["Commerce Web UI<br/>[product_page.py]"]
end

node_user(("User"))

node_user -->|"submits shopping request"| node_mcp
node_user -->|"signs budget"| node_mission
node_mcp -->|"searches products"| node_catalog
node_mcp -->|"evaluates proposal"| node_gateway
node_mcp -->|"reads and records state"| node_mcpstate
node_mcpstate -->|"verifies mission"| node_gateway
node_agent -->|"proposes SKU and quantity"| node_gateway
node_discovery -->|"provides market evidence"| node_agent
node_discovery -->|"uses catalog data"| node_catalog
node_gateway -->|"checks server prices"| node_catalog
node_gateway -->|"approves exact proposal"| node_approval
node_approval -->|"authorizes execution"| node_execution
node_mandates -->|"co-signs cart"| node_approval
node_execution -->|"dispatches payment"| node_provider
node_provider -->|"creates provider order"| node_razorpay
node_execution -->|"reconciles uncertain result"| node_recovery
node_razorpay -->|"sends signed event"| node_webhook
node_gateway -->|"records verdict"| node_audit
node_execution -->|"records execution"| node_audit
node_audit -->|"persists chain entries"| node_db
node_web -.->|"displays products"| node_catalog
node_negotiation -->|"chains offers"| node_audit
node_growth -->|"uses growth analysis"| node_intelligence
node_growth -->|"uses product data"| node_catalog
node_chaos -->|"checks recorded events"| node_audit

click node_agent "https://github.com/harshdubey23/sellable/blob/main/apps/api/agent/buyer.py"
click node_discovery "https://github.com/harshdubey23/sellable/blob/main/apps/api/discovery/pipeline.py"
click node_catalog "https://github.com/harshdubey23/sellable/blob/main/apps/api/products.py"
click node_mission "https://github.com/harshdubey23/sellable/blob/main/apps/api/missions.py"
click node_gateway "https://github.com/harshdubey23/sellable/blob/main/apps/api/gateway/engine.py"
click node_approval "https://github.com/harshdubey23/sellable/blob/main/apps/api/approval.py"
click node_mandates "https://github.com/harshdubey23/sellable/blob/main/apps/api/mandates/mandates.py"
click node_execution "https://github.com/harshdubey23/sellable/blob/main/apps/api/execution.py"
click node_provider "https://github.com/harshdubey23/sellable/blob/main/apps/api/execution_provider.py"
click node_razorpay "https://github.com/harshdubey23/sellable/blob/main/apps/api/razorpay_client.py"
click node_recovery "https://github.com/harshdubey23/sellable/blob/main/apps/api/recovery/engine.py"
click node_webhook "https://github.com/harshdubey23/sellable/blob/main/apps/api/webhook/receiver.py"
click node_audit "https://github.com/harshdubey23/sellable/blob/main/apps/api/audit/chain.py"
click node_db "https://github.com/harshdubey23/sellable/blob/main/apps/api/store/db.py"
click node_mcp "https://github.com/harshdubey23/sellable/blob/main/mcp_server/server.py"
click node_mcpstate "https://github.com/harshdubey23/sellable/blob/main/mcp_server/store.py"
click node_web "https://github.com/harshdubey23/sellable/blob/main/apps/api/web/product_page.py"
click node_negotiation "https://github.com/harshdubey23/sellable/blob/main/apps/api/negotiation/engine.py"
click node_growth "https://github.com/harshdubey23/sellable/blob/main/apps/api/growth/engine.py"
click node_intelligence "https://github.com/harshdubey23/sellable/blob/main/apps/api/growth/intelligence.py"
click node_chaos "https://github.com/harshdubey23/sellable/blob/main/apps/api/chaos/engine.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_agent,node_discovery,node_catalog,node_negotiation,node_user toneBlue
class node_mission,node_gateway,node_approval,node_mandates,node_audit,node_db,node_chaos toneAmber
class node_execution,node_provider,node_razorpay,node_recovery,node_webhook toneMint
class node_growth,node_intelligence toneRose
class node_mcp,node_mcpstate,node_web toneIndigo
```

## Components

### Shopping Experience

- [Buyer Agent](https://github.com/harshdubey23/sellable/blob/main/apps/api/agent/buyer.py): `apps/api/agent/buyer.py`
- [Market Discovery](https://github.com/harshdubey23/sellable/blob/main/apps/api/discovery/pipeline.py): `apps/api/discovery/pipeline.py`
- [Product Catalog](https://github.com/harshdubey23/sellable/blob/main/apps/api/products.py): `apps/api/products.py`
- [Negotiation Engine](https://github.com/harshdubey23/sellable/blob/main/apps/api/negotiation/engine.py): `apps/api/negotiation/engine.py`

### Safety Control

- [Signed Mission](https://github.com/harshdubey23/sellable/blob/main/apps/api/missions.py): `apps/api/missions.py`
- [Policy Gateway](https://github.com/harshdubey23/sellable/blob/main/apps/api/gateway/engine.py): `apps/api/gateway/engine.py`
- [Approval Binding](https://github.com/harshdubey23/sellable/blob/main/apps/api/approval.py): `apps/api/approval.py`
- [User Mandates](https://github.com/harshdubey23/sellable/blob/main/apps/api/mandates/mandates.py): `apps/api/mandates/mandates.py`
- [Audit Chain](https://github.com/harshdubey23/sellable/blob/main/apps/api/audit/chain.py): `apps/api/audit/chain.py`
- [Application Store](https://github.com/harshdubey23/sellable/blob/main/apps/api/store/db.py): `apps/api/store/db.py`
- [Chaos Evaluator](https://github.com/harshdubey23/sellable/blob/main/apps/api/chaos/engine.py): `apps/api/chaos/engine.py`

### Payment Lifecycle

- [Execution Machine](https://github.com/harshdubey23/sellable/blob/main/apps/api/execution.py): `apps/api/execution.py`
- [Payment Provider](https://github.com/harshdubey23/sellable/blob/main/apps/api/execution_provider.py): `apps/api/execution_provider.py`
- [Razorpay](https://github.com/harshdubey23/sellable/blob/main/apps/api/razorpay_client.py): `apps/api/razorpay_client.py`
- [Payment Recovery](https://github.com/harshdubey23/sellable/blob/main/apps/api/recovery/engine.py): `apps/api/recovery/engine.py`
- [Webhook Receiver](https://github.com/harshdubey23/sellable/blob/main/apps/api/webhook/receiver.py): `apps/api/webhook/receiver.py`

### Commerce Intelligence

- [Growth Engine](https://github.com/harshdubey23/sellable/blob/main/apps/api/growth/engine.py): `apps/api/growth/engine.py`
- [Growth Intelligence](https://github.com/harshdubey23/sellable/blob/main/apps/api/growth/intelligence.py): `apps/api/growth/intelligence.py`

### Interfaces

- [MCP Server](https://github.com/harshdubey23/sellable/blob/main/mcp_server/server.py): `mcp_server/server.py`
- [MCP State](https://github.com/harshdubey23/sellable/blob/main/mcp_server/store.py): `mcp_server/store.py`
- [Commerce Web UI](https://github.com/harshdubey23/sellable/blob/main/apps/api/web/product_page.py): `apps/api/web/product_page.py`

### Other components

- **User**

## Connections

- User → MCP Server: submits shopping request
- User → Signed Mission: signs budget
- MCP Server → Product Catalog: searches products (evidence: `mcp_server/server.py`)
- MCP Server → Policy Gateway: evaluates proposal (evidence: `mcp_server/server.py`)
- MCP Server → MCP State: reads and records state (evidence: `mcp_server/server.py`)
- MCP State → Policy Gateway: verifies mission (evidence: `mcp_server/store.py`)
- Buyer Agent → Policy Gateway: proposes SKU and quantity
- Market Discovery → Buyer Agent: provides market evidence
- Market Discovery → Product Catalog: uses catalog data (evidence: `apps/api/discovery/pipeline.py`)
- Policy Gateway → Product Catalog: checks server prices (evidence: `apps/api/gateway/engine.py`)
- Policy Gateway → Approval Binding: approves exact proposal
- Approval Binding → Execution Machine: authorizes execution
- User Mandates → Approval Binding: co-signs cart
- Execution Machine → Payment Provider: dispatches payment
- Payment Provider → Razorpay: creates provider order
- Execution Machine → Payment Recovery: reconciles uncertain result (evidence: `apps/api/recovery/engine.py`)
- Razorpay → Webhook Receiver: sends signed event
- Policy Gateway → Audit Chain: records verdict
- Execution Machine → Audit Chain: records execution
- Audit Chain → Application Store: persists chain entries (evidence: `apps/api/audit/chain.py`)
- Commerce Web UI → Product Catalog: displays products
- Negotiation Engine → Audit Chain: chains offers (evidence: `apps/api/negotiation/engine.py`)
- Growth Engine → Growth Intelligence: uses growth analysis (evidence: `apps/api/growth/engine.py`)
- Growth Engine → Product Catalog: uses product data (evidence: `apps/api/growth/engine.py`)
- Chaos Evaluator → Audit Chain: checks recorded events (evidence: `apps/api/chaos/engine.py`)