# Roadmap — MVP → v1 → v2

Phased so each stage is shippable and useful on its own. Checkboxes are the working backlog.

## Phase 0 — Validate & scaffold (before features)

- [ ] Run the **host capability checklist** (`05-deployment-cpanel.md §1`): Node ≥20,
      PostgreSQL, persistent Passenger, SSH, RAM, outbound HTTPS.
- [ ] Stand up **Medusa backend** (`medusa-starter-default`) + **Postgres** locally and on
      the host; confirm admin login works.
- [ ] Stand up **Next.js storefront** (`nextjs-starter`) wired to the backend.
- [ ] **CI/CD auto-deploy** pipeline (GitHub Actions → SSH to host: pull/build/migrate/restart)
      — set this up first so we *never* deploy by hand from day one.
- [ ] **Hardened cPanel base** (07 §14): **Upstash Redis from day 1** (durable event bus/queues)
      + **keep-alive cron** + serialized maintenance-window migrations.
- [ ] **Control-API core + Admin UI fallback** (07 §1): domain-verb API as the spine; the Admin
      UI must run the business with no AI.
- [ ] Decide payment + email provider accounts (Razorpay, Stripe/PayPal, email).
- **Exit criteria:** a bare Medusa store loads on the host with a test product, and a push to
      the release branch auto-deploys.

## Phase 1 — MVP (a real store the owner can sell from)

Goal: take real orders for Jaipur Handloomia.

- [ ] **Products**: import the handloom catalog (razai, bedsheets, sarees, kurtis, dupattas,
      table linen) with variants, images, collections.
- [ ] **Storefront**: one polished handloom **theme** — home, collection, product, cart,
      checkout; mobile-first; SEO basics (reuse agent recommendations).
- [ ] **Checkout & payments**: **Razorpay** (UPI/cards/netbanking) + **Stripe/PayPal** for
      international; INR + USD/GBP/AUD regions.
- [ ] **Orders**: order management, fulfillment, basic returns/refunds (Medusa built-in).
- [ ] **Discounts**: coupon codes + one automatic promo.
- [ ] **Admin**: working Medusa Admin with store settings.
- [ ] **Platform MCP connector**: the control layer that lets Claude run the store from chat
      (products, orders, theme/content) — the primary control surface.
- [ ] **Live theme editing (zero deploy)**: data-driven storefront (theme as `theme_setting`/
      `content_block`, rendered via dynamic SSR + on-demand revalidation) so Claude restyles
      the store with no rebuild.
- [ ] **Draft → Preview → Publish + versioning** (07 §5): AI edits a draft, previews it, then
      publishes (instant); full rollback. **JSON-Schema validation** on every AI write (07 §6).
- [ ] **Test orders** with an **`is_test` flag** filtered from revenue reporting (07 §10): Claude
      places test-mode orders to verify checkout end-to-end without polluting financials.
- [ ] **Asset service** (S3/R2 + CDN, 07 §11): product images/creatives off the cPanel disk.
- [ ] **Store Copilot v0**: at least one working write action (e.g. "create a product") behind
      the confirm-before-write guardrail, plus read actions (sales/order questions).
- [ ] **Inventory guard** (08 §11): agents + channels read live stock and never promote
      out-of-stock / dead / low-margin SKUs — a top-priority revenue-protection fix.
- [ ] **Business KPI dashboard v0** (08 §1): revenue-first view (sales, conversion, AOV) above
      agent activity.
- **Exit criteria:** a customer can buy a razai end-to-end; from **Claude chat** the owner can
  add a product, restyle the homepage live (no deploy), and place a test order; the dashboard
  shows revenue and agents never surface out-of-stock items.

## Phase 2 — v1 (content, marketing AI, analytics, email)

- [ ] **Content section**: page/section/blog editor (`content_block`) + light homepage
      section ordering; AI-drafted copy as drafts.
- [ ] **Marketing AI integration**: migrate the **25 agents** + run history into
      `ai_agent_run`; "Marketing" admin screen showing statuses + deliverables (the current
      dashboard, native). Agents read live store data.
- [ ] **Analytics**: sales/conversion/product reports in the admin; web analytics hookup.
- [ ] **Emails**: transactional emails (order/shipping confirmations) + Mailchimp campaign
      sync.
- [ ] **SEO + listings executed by Claude**: from chat, Claude writes/optimizes product
      listings (titles, descriptions, JSON-LD schema, image alt, collections) and runs the SEO
      agents — action, not just advice.
- [ ] **Event bus + workflow engine** (07 §7–8): "when order placed → invoice → WhatsApp →
      Meta event → email" automations.
- [ ] **AI Memory** (07 §9): brand voice/policies/suppliers/personas the AI always loads.
- [ ] **Permissions/RBAC** incl. least-privilege AI role (07 §10); **cost monitoring +
      observability** for every AI action (07 §13).
- [ ] **Copilot v1**: more tools (pricing, inventory, discounts, content drafting), audit log.
- [ ] **Search**: Postgres full-text product search on the storefront.
- [ ] **WhatsApp Cloud API selling** (08 §4a): catalog, segmented broadcasts, abandoned-cart
      recovery, order updates, broadcast-to-buy — the primary conversion channel.
- [ ] **Campaign mode + Campaign Coordinator** (08 §10): one goal at a time; agents
      revenue-classified and prioritized; duplicate work eliminated (replaces 25 always-on).
- [ ] **Retention engine** (08 §5): post-purchase journeys, reorder nudges, review requests,
      VIP segments, festival comeback.
- [ ] **Instagram commerce, smart bundles, channel attribution + referral codes, trust layer,
      and a continuous A/B framework** (08 §4b,6,7,8,9).
- **Exit criteria:** owner manages content + marketing from one admin; customers get
  transactional emails; the marketing agents run grounded in real store data; Claude writes
  and optimizes listings from chat; WhatsApp recovers carts and campaign mode focuses the system
  on one goal.

## Phase 3 — v2 (experiments, advanced AI, integrations, marketplace)

- [ ] **A/B Testing**: `ab_experiment` module; storefront variant assignment + results.
- [ ] **Storefront AI**: natural-language search, recommendations, support chat.
- [ ] **Meta Ads insights**: ad-account spend/ROAS/campaign performance in Analytics,
      queryable from Claude.
- [ ] **Marketplace channels** via the **Channel Manager** interface (07 §12): list & manage
      products on **Amazon** (SP-API) and **Flipkart** (Seller API), plus Instagram/WhatsApp —
      credential-gated on the owner's seller accounts + API approval.
- [ ] **Multi-model router** (07 §2) + **semantic/typo-tolerant search** (MeiliSearch/vector,
      07 §14) for descriptive textile queries; **multi-renderer** theme engine (mobile/AMP/PDF).
- [ ] **YouTube funnel scale, influencer payout tracking, B2B/wholesale (lead capture + groups/
      price lists), and a loyalty/VIP program** (08 §4c,9,12,5).
- [ ] **Integrations screen**: Meta catalog + Google Merchant feeds, more providers, all via
      `plugin_registry`.
- [ ] **Plugin marketplace** (optional): browse/enable additional capabilities.
- [ ] **Search upgrade**: MeiliSearch/Algolia or vector search.
- **Exit criteria:** the store optimizes itself with experiments + AI, surfaces ad performance,
  and lists products across Amazon/Flipkart from one place.

## Feature → phase summary (matches the reference sidebar)

| Capability | MVP | v1 | v2 |
|---|:--:|:--:|:--:|
| Store / settings / regions | ✅ | | |
| Products / inventory | ✅ | | |
| Orders / fulfillment | ✅ | | |
| Discounts | ✅ | ➕ | |
| Checkout & payments | ✅ | | |
| Storefront theme | ✅ | ➕ | |
| Store Copilot (AI assistant) | ✅ (1 action) | ➕ | ➕ |
| Content (pages/blog/CMS) | | ✅ | |
| Marketing AI agents (25) | | ✅ | |
| Analytics | | ✅ | |
| Emails (transactional + campaigns) | | ✅ | |
| Search | | ✅ (FTS) | ➕ |
| A/B Testing | | | ✅ |
| Storefront AI (search/recs/support) | | | ✅ |
| Integrations / feeds | | | ✅ |
| Plugin marketplace | | | ✅ |
| Control-API core + Admin UI fallback | ✅ | ➕ | |
| Draft→Preview→Publish + versioning | ✅ | ➕ | |
| Hardened cPanel (Upstash + keep-alive) | ✅ | | |
| Event bus + workflow engine | | ✅ | ➕ |
| AI memory | | ✅ | |
| Permissions/RBAC + cost/observability | | ✅ | ➕ |
| Channel Manager (multi-channel) | | | ✅ |
| Business KPI dashboard (revenue-first) | ✅ | ➕ | |
| Inventory guard (stock protection) | ✅ | | |
| WhatsApp Cloud API selling | | ✅ | ➕ |
| Campaign mode + coordinator | | ✅ | |
| Retention engine | | ✅ | ➕ |
| Instagram commerce · smart bundles · trust layer | | ✅ | |
| Channel attribution + referral codes | | ✅ | ➕ |
| Continuous A/B framework | | ✅ | |
| YouTube funnel · influencer payouts · B2B/wholesale · loyalty | | | ✅ |

## Guiding principles

- **Ship the store first** (Phase 1) — revenue before refinement.
- **Revenue-first** — judge every agent/feature by its effect on the KPI hierarchy (08 §1);
  sell where India converts (**WhatsApp-first**); run **one campaign at a time**.
- **Reuse, don't rebuild** — Medusa for commerce, the existing agents for marketing.
- **AI guardrails always on** — confirm-before-write, audit, cost ceilings (`02-…§4`).
- **Each phase stands alone** — the store is useful at the end of every phase.