# Jaipur Handloomia — AI-Native Commerce Platform: Overview

> **Status:** Architecture proposal (no code yet). Approved direction; pending build.
> **Audience:** the store owner (non-technical) + whoever builds it.

> ### Why now — and the two rules that fix the real problem
> The owner already runs a WooCommerce store driven through Claude, and hit a wall: **every
> theme change is code you deploy by hand.** Iterating a design 15–20 times means 15–20
> manual redeploys, plus bugs each round. That loop — not missing features — is the pain.
>
> So this platform is built on **two non-negotiable rules:**
> 1. **Zero manual deploy.** Theme and content are *data*, not files. Claude changes a color,
>    text, image, section order, or whole page → the store updates **live in seconds**. No
>    rebuild, no upload. (A brand-*new* type of building block still needs a one-time
>    developer add; everything iterated day-to-day is a live edit.)
> 2. **Run it all from Claude chat.** A platform connector (MCP) lets Claude do everything —
>    theme, products, orders, **test orders**, SEO, listings, support agent — from chat. Even
>    changes to the platform's *own code* auto-deploy via CI/CD, so nothing is uploaded by hand.

## 1. What we're building

A **self-hosted online store** for Jaipur Handloomia that the owner controls completely —
the storefront customers shop on, the admin the owner runs the business from, and an
**AI assistant + AI agents** built into both. Think "our own Shopify," tuned for a
handloom/artisanal textile brand, running on our own hosting.

It is built on **Medusa.js** — a free, open-source commerce engine that already provides
products, carts, checkout, orders, payments, discounts and a plugin system. We add the
storefront design, the AI layer, and the management screens on top. This saves years
versus writing a checkout/payments/inventory engine from scratch.

## 2. Scope (read this first)

| | |
|---|---|
| **In scope** | A **single store** for Jaipur Handloomia's own business. |
| **Out of scope (for now)** | A multi-merchant SaaS where strangers sign up and open their own stores (Shopify's actual business model). We are *not* building that. |

This single-store decision keeps the build realistic. Everything below is designed so the
store can grow, but we are not paying the large "let anyone open a store" tax (tenant
isolation, per-tenant billing, signups) that we don't need.

**Non-goals:** building our own payment processor (we integrate Razorpay/Stripe), building
our own email-sending infrastructure (we use a provider), or matching every niche Shopify
app on day one.

## 3. Reference: the admin we're matching

The owner's reference screenshots show a Shopify-class admin with this sidebar and an
"Amboras Business Assistant" AI chat. Here is **every item mapped** to how this platform
delivers it and in which phase it lands. (Phases are detailed in `06-roadmap.md`.)

| Sidebar item | What it is | How we deliver it | Phase |
|---|---|---|---|
| **Home / Dashboard** | At-a-glance KPIs, tasks, AI prompt | Medusa Admin home + custom KPI widget + embedded AI copilot bar | MVP → v1 |
| **Store** | Store settings, regions, currencies, domains | Medusa "Settings" (Store, Regions, Currencies) | MVP |
| **Orders** | Order list, fulfillment, refunds, returns | Medusa Orders (built in) | MVP |
| **Products** | Catalog, variants, inventory, collections | Medusa Products & Inventory (built in) | MVP |
| **Content** | Pages, blog, homepage sections, media | Custom `content_block` module + storefront CMS sections; AI-drafted copy | v1 |
| **Discounts** | Coupons, automatic discounts, promotions | Medusa Promotions/Discounts (built in) | MVP → v1 |
| **Analytics** | Sales, traffic, conversion, product reports | Analytics module reading Medusa data + web analytics; admin dashboard | v1 |
| **Emails** | Transactional + marketing email | Notification provider (transactional) + Mailchimp/marketing-agent (campaigns) | v1 |
| **A/B Testing** | Experiments on storefront/pricing/copy | Custom `ab_experiment` module + storefront variant assignment | v2 |
| **Integrations** | Connect external tools (ads, feeds, CRM) | Plugin/integration registry: Meta, Google feeds, Mailchimp, n8n | v2 |
| **AI Assistant** ("Business Assistant") | Chat that *does* things in the store | In-admin **Store Copilot** + **Claude-chat control via the Platform MCP** (primary surface) | MVP (1 action) → v1+ |
| **Run from Claude chat** | Manage the whole store from chat, no manual steps | **Platform Control API + MCP connector** (the live, typed successor to the n8n/`claude-wp-manager` bridge) | MVP |
| **Live theme editing** | Restyle/rearrange the store with no redeploy | Theme/content as **data**, rendered live (dynamic SSR + on-demand revalidation) | MVP |
| **Test orders** | Place test orders to verify checkout | Test-mode payments / draft orders Claude can create from chat | MVP |
| **SEO & product listing** | Write & optimize listings, run SEO | Claude (via MCP) writes titles/descriptions/schema/alt + runs the 25 SEO agents | v1 |
| **Self-evolving platform** | Change the platform itself, no manual deploy | Platform is code in this repo; Claude edits it → **GitHub Actions auto-deploy** to the host | MVP (Phase 0) |
| **Meta Ads insights** | See ad spend/ROAS/campaigns | Meta integration surfaced in Analytics/Integrations, queryable from Claude | v2 |
| **Marketplace channels** | List products on Amazon & Flipkart | Channel sync from Medusa catalog (Amazon SP-API, Flipkart Seller API) — credential-gated | v2 |
| **Business KPI dashboard** | Revenue, conversion, AOV, repeat, cart recovery, channel ROI | Revenue-first dashboard above agent activity (`08`) | MVP → v1 |
| **Inventory guard** | Never promote out-of-stock / dead / low-margin SKUs | Live-stock filter on agents + channels via the event bus (`08 §11`) | MVP |
| **WhatsApp commerce** | Catalog, broadcasts, cart recovery, order updates, buy flows | WhatsApp Business **Cloud API** channel + workflow engine (`08 §4a`) — credential-gated | v1 |
| **Campaign mode** | All agents work toward one goal (Diwali, weddings…) | `campaign` object + **Campaign Coordinator** (`08 §10`); replaces always-on | v1 |
| **Retention engine** | Post-purchase journeys, reorder, reviews, VIP, comeback | Workflow engine + segments + WhatsApp/email (`08 §5`) | v1 |
| **Instagram / YouTube commerce** | Reels→tag→site, UGC, influencer, how-to video funnel | IG + YouTube channels; reuse `youtube-seo` agent (`08 §4b–c`) | v1 → v2 |
| **Smart bundles** | Gift sets / festival / office wear → higher AOV | `bundle` module + AI bundle generator (`08 §6`) | v1 |
| **Trust layer** | Artisan story, proof, badges, delivery promise, social proof on PDPs | Content-block storefront sections (`08 §7`) | v1 |
| **Channel attribution + influencer** | Revenue by WhatsApp/IG/YouTube/SEO/influencer + referral codes | UTM + referral codes + event bus (`08 §9`) | v1 |
| **Wholesale / B2B** | Wholesale lead capture, gifting, corporate, local pickup | Lead-capture page + Medusa customer groups / price lists (`08 §12`) | v2 |

Nothing in the reference is silently dropped — each row has a home and a phase.

> **Revenue-first stance (from the growth review):** the platform isn't just a marketing
> controller — it's a **sales engine**. It leads with a business KPI dashboard (revenue,
> conversion, AOV, repeat rate, cart recovery, channel ROI), sells where India converts
> (**WhatsApp-first**, Instagram, YouTube), runs **one campaign at a time** via a coordinator,
> and never promotes what's out of stock. Full design in `08-growth-and-sales-engine.md`.

## 4. The AI is the differentiator

Three AI "pillars" make this more than a plain Medusa store (full detail in `02-ai-agents.md`):

1. **Store Copilot, driven from Claude chat** — the owner types *"add a Sanganeri double
   bedsheet at ₹2,400, 12 in stock"*, *"restyle the homepage hero in festive colors"* or
   *"which razai sold best last week?"* and Claude actually performs it via the **Platform MCP
   connector** (with confirmation before anything destructive). The same assistant is also
   embedded inside the admin as a secondary surface.
2. **Marketing AI agents** — the **25 agents this repo already runs** (SEO, content, social,
   CRO, competitor intel…). They survive as the platform's marketing brain, now reading live
   store data and surfacing deliverables inside the admin.
3. **Storefront AI** — smart search, product recommendations, and a customer support chat on
   the customer-facing site.

## 5. Why Medusa, and what we reuse

- **Medusa.js** gives us a production commerce core (Node/TypeScript) we'd otherwise spend
  years building, with an official **Next.js storefront starter** and a **React admin** we
  can extend with our own screens and the AI copilot.
- **What we keep from this repo:** the 25-agent `agents/manifest.json`, the
  `scripts/run-agents.mjs` LLM-runner pattern, the n8n cloud runner, the dashboard UX, and
  the brand context. They become Pillar 2 — see `03-data-model.md` for how the existing run
  data migrates into the new system with zero loss.

## 6. Document set

| File | Contents |
|---|---|
| `00-overview.md` | This file — vision, scope, feature map |
| `01-architecture.md` | System components, diagrams, request flows, hosting shape |
| `02-ai-agents.md` | The three AI pillars, providers, tool-use, guardrails |
| `03-data-model.md` | Commerce entities + our custom modules + migration of existing data |
| `04-themes-and-plugins.md` | Theme system and the plugin/extension model |
| `05-deployment-cpanel.md` | Deploying on the owner's cPanel (Node + Postgres) |
| `06-roadmap.md` | Phased MVP → v1 → v2 plan with checklists |
| `07-architecture-hardening.md` | **Review-driven hardening:** Control-API core (AI is a client), draft→preview→publish, event bus, workflow engine, AI memory, permissions, channel manager, cPanel mitigations |
| `08-growth-and-sales-engine.md` | **Revenue-first growth layer:** KPI dashboard, customer journey, WhatsApp-first selling, campaign mode + coordinator, inventory guard, retention, bundles, trust layer, attribution, B2B |

> **Architecture stance (from two external reviews):** AI is a powerful **client** of a stable
> **Platform Core + Control API**, not the platform itself — so the business keeps running from
> the Admin UI even if AI is unavailable. Commerce ships first, but the core is built **OS-ready**
> for future modules (accounting, CRM, POS). Details in `07-architecture-hardening.md`.