# Jaipur Handloomia — Platform (build)

This is the running platform described in [`docs/platform/`](../docs/platform/README.md):
a self-hosted Medusa v2 backend + Next.js storefront. **A deployable MVP store is in place
and verified end-to-end** (catalog → cart → checkout → order). To put it live, follow
[`deploy/CPANEL-DEPLOY.md`](../deploy/CPANEL-DEPLOY.md).

```
platform/
├── backend/      Medusa v2 (API + admin + custom modules + Razorpay)   ✅ runs & verified
└── storefront/   Next.js handloom store                                ✅ builds & serves catalog
```

## What's built & verified

**Increment 1 — foundation**
- **Medusa v2 backend** (2.16.0) — installs, migrates, builds, boots; `/health` → `OK`.
- **Custom `marketing` module** with the `ai_agent_run` model mirroring the legacy
  `data/<agent>.json` shape; **52 runs across 25 agents imported** (`03-data-model.md §2a`).
- **CI/CD auto-deploy** workflow (inert until host secrets are set).

**Increment 2 — deployable MVP store**
- **Handloom seed** (`backend/src/scripts/seed.ts`) — **India (INR) + International (USD)**
  regions, Jaipur stock location, INR/USD shipping, tax, **8 handloom products in 6
  categories** (razai, bedsheets, sarees, kurtis, dupattas, table linen) with inventory.
- **Razorpay payment provider** (`backend/src/modules/payment-razorpay`) — custom Medusa v2
  provider; registered only when `RAZORPAY_KEY_ID/SECRET` are set (manual/test provider
  otherwise). Storefront has a Razorpay Checkout button (`payment-button`).
- **Storefront** builds green and serves the live catalog (statically generates product +
  category pages from the backend).
- **Verified end-to-end in dev:** Store API returns the catalog with INR prices; a full order
  was placed through cart → shipping → manual payment → completion (**Order #1, ₹1,498**);
  the backend also boots cleanly with Razorpay configured (dummy keys).
- **Deploy package** (`deploy/`) — `CPANEL-DEPLOY.md` runbook, `.env.production` templates,
  and `package-release.sh` (clean uploadable tarball).

**Not yet built** (next increments, per `docs/platform/`): AI Store Copilot / Control API +
MCP, theme/content draft→preview→publish, campaign + inventory guard, WhatsApp channel.

> Only source + lockfiles are committed. `node_modules/`, `.medusa/`, `.next/`, and `.env*`
> are gitignored and reproduced on install/build.

## Deploy to your hosting

See **[`deploy/CPANEL-DEPLOY.md`](../deploy/CPANEL-DEPLOY.md)** — numbered cPanel steps
(database → Node apps → env → install → migrate → seed → build → start → SSL → Razorpay).

## Run the backend locally

```bash
cd platform/backend
cp .env.template .env          # set DATABASE_URL etc.
npm install
createdb medusa_platform       # or use your Postgres; match DATABASE_URL
npx medusa db:migrate          # core schema + the marketing module table
npx medusa exec ./src/scripts/import-agent-runs.ts   # import the 25-agent history
npm run build                  # builds backend + admin into .medusa/server
```

**Start in production** (this is the command the cPanel Passenger app runs — note it runs
from the **build output**, not the project root):

```bash
cd platform/backend/.medusa/server
npm install --omit=dev
npx medusa start               # serves API + admin on :9000 ; GET /health -> OK
```

For local development with hot reload, use `npm run dev` from `platform/backend` instead.

## Run the storefront locally

```bash
cd platform/storefront
cp .env.template .env.local
npm install
npm run dev                    # http://localhost:8000
```

**Before a production `next build`** the storefront needs the backend running and a real
**publishable API key**:
1. Create an admin user: `cd platform/backend && npx medusa user -e you@example.com -p yourpass`
2. Seed base data (region, sales channel, publishable key, sample products):
   `npm run seed`
3. Copy the generated **publishable key** into `platform/storefront/.env.local`
   (`NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...`) and `MEDUSA_BACKEND_URL`.
4. With the backend running, `cd platform/storefront && npm run build`.

`npm run build` is **green** (the starter's `next.config.js` sets `typescript.ignoreBuildErrors`
and `eslint.ignoreDuringBuilds`, so the upstream `@medusajs/js-sdk: latest` type drift doesn't
block the build). Tidying those types by pinning the SDK to 2.16.x is an optional follow-up.

> Product images in the seed use Unsplash placeholders (allowed in `next.config.js`). Replace
> them with your real product photos from the admin (or an asset host) before launch.

## Next increments (per `docs/platform/`)

Control API + MCP connector · theme/content modules with draft→preview→publish · campaign +
inventory-guard modules · WhatsApp channel · Razorpay/Stripe providers. Each attaches to the
foundation above.
