# Jaipur Handloomia — AI-Native Commerce Platform (Architecture & Roadmap)

This folder specifies a **self-hosted, AI-native e-commerce platform** for Jaipur
Handloomia — our own "Shopify," built on **Medusa.js**, with an in-admin AI assistant and
the existing 25 marketing agents baked in. It is a **design blueprint** (no platform code
yet); building happens in follow-up tasks once this is approved.

> ### The two rules that drive everything
> 1. **Zero manual deploy** — theme & content are *data*, edited via API and rendered live;
>    changes show up in seconds with no rebuild/upload. (Fixes the WooCommerce deploy loop.)
> 2. **Run it all from Claude chat** — a platform connector (MCP) lets Claude do everything:
>    theme, products, orders, test orders, SEO/listings, support agent. Even platform *code*
>    changes auto-deploy via CI/CD, so nothing is uploaded by hand.

## Decisions locked

- **Single store** for Jaipur Handloomia (not a multi-merchant SaaS).
- Built on **Medusa.js** (open-source Node/TypeScript commerce engine) + **Next.js** storefront.
- Hosted on the owner's **cPanel host** (Node.js apps via Passenger + PostgreSQL).
- AI: **Claude** for the in-admin Store Copilot, **Gemini** for background marketing agents.

## Read in this order

| # | Doc | What you'll learn |
|---|---|---|
| 0 | [00-overview.md](./00-overview.md) | Vision, scope, and the full reference-sidebar → feature map |
| 1 | [01-architecture.md](./01-architecture.md) | Components, diagrams, request flows, hosting shape |
| 2 | [02-ai-agents.md](./02-ai-agents.md) | The three AI pillars, providers, tool-use, guardrails |
| 3 | [03-data-model.md](./03-data-model.md) | Commerce entities + custom modules + migrating existing data |
| 4 | [04-themes-and-plugins.md](./04-themes-and-plugins.md) | Theme system + plugin/extension model |
| 5 | [05-deployment-cpanel.md](./05-deployment-cpanel.md) | Deploy on cPanel + the host-capability checklist |
| 6 | [06-roadmap.md](./06-roadmap.md) | Phased MVP → v1 → v2 plan with checklists |
| 7 | [07-architecture-hardening.md](./07-architecture-hardening.md) | Review-driven hardening: Control-API core (AI as a client), draft→preview→publish, event bus, workflow engine, AI memory, permissions, channel manager, cPanel mitigations |
| 8 | [08-growth-and-sales-engine.md](./08-growth-and-sales-engine.md) | Revenue-first growth: KPI dashboard, customer journey, WhatsApp-first selling, campaign mode + coordinator, inventory guard, retention, bundles, trust layer, attribution, B2B |

## Hardening decisions (from two architecture reviews)

- **AI is a client, not the core.** A stable **Control API** is the permanent center; Claude/
  MCP, the Admin UI, and n8n are all clients. The business runs from the Admin UI even with no AI.
- **Hosting:** stay **all-cPanel**, hardened — keep-alive cron, **Upstash Redis from day 1**,
  careful migrations.
- **AI edits:** **Draft → Preview → Publish** with version history + rollback (still zero-deploy).
- **Framing:** commerce-first, but the core is **OS-ready** for future modules.

See `07-architecture-hardening.md` for the full rationale and diagrams.

## Revenue-first growth layer (from the growth review)

The platform is a **sales engine**, not just a marketing controller: it leads with a **business
KPI dashboard**, sells **WhatsApp-first** (the channel that converts in India) alongside
Instagram/YouTube, runs **one campaign at a time** via a **Campaign Coordinator** (replacing
25 always-on agents), **never promotes out-of-stock SKUs** (inventory guard), and adds
retention, bundles, a trust layer, attribution, and B2B/wholesale. Full design in
`08-growth-and-sales-engine.md`.

## What this reuses from this repo

The existing marketing-agent system (`agents/manifest.json`, `scripts/run-agents.mjs`, the
n8n runner, the dashboard, the brand context) is **not thrown away** — it becomes the
platform's marketing-AI pillar. The agent run JSON shape maps 1:1 onto the new
`ai_agent_run` data model, so history migrates with no loss. See `03-data-model.md §2a`.

## Biggest risk to validate first

The **cPanel + Passenger** hosting path. Before building, run the host-capability checklist
in [05-deployment-cpanel.md §1](./05-deployment-cpanel.md) (Node ≥20, PostgreSQL, persistent
Passenger processes, SSH). Fallbacks are listed there if any check fails — none change the
architecture, only where each Node app runs.
