# Themes & Plugins (Extension Model)

Two extension systems: **themes** (how the storefront looks) and **plugins** (what the
platform can do). Both are how we match Shopify's "swap a theme / install an app" feel.

## 1. Theme system (storefront look & feel)

The storefront is **Next.js** (Medusa's `nextjs-starter`). "A theme" = a combination of:

1. **Design tokens** — colors, typography, spacing, radius, logo. Stored in `theme_setting`
   (see `03-data-model.md`), exposed to the storefront as CSS variables / a Tailwind config
   preset. Changing tokens restyles the whole site without touching components.
2. **Section components** — reusable, swappable building blocks: `Hero`, `FeaturedCollection`,
   `ProductGrid`, `StorySection` (Jaipur heritage), `Testimonials`, `Newsletter`, `Footer`,
   plus **trust-layer** sections (`08 §7`): `ArtisanStory`, `CraftProof` (Sanganeri/Bagru),
   `QualityBadges`, `DeliveryPromise` (ships-before-Diwali countdown), `ReturnPolicy`,
   `SocialProof` (reviews/UGC) — surfaced prominently on product pages to lift conversion.
3. **Layout/section order** — the homepage and key pages are an ordered list of sections
   stored in `theme_setting` + `content_block`, so the owner can reorder/add/remove sections
   from the admin (a lightweight page builder), not via code.

```mermaid
flowchart LR
    TS[("theme_setting<br/>tokens + section order")] --> SF
    CB[("content_block<br/>section content")] --> SF
    subgraph SF["Next.js storefront"]
      direction TB
      H[Hero] --> FC[FeaturedCollection] --> PG[ProductGrid] --> ST[StorySection]
    end
    ADMIN["Admin: Theme & Content editor"] --> TS
    ADMIN --> CB
```

**Theme packaging.** A theme is a folder of section components + a default token set + a
default section layout. Switching themes swaps the component set and default tokens; the
owner's content (`content_block`) carries over. MVP ships **one** well-built handloom theme;
additional themes are additive later.

> **Live rendering — the zero-deploy rule (the most important part).** The storefront
> **never hard-codes look or content.** On every request it reads the active `theme_setting`
> (tokens + section order) and `content_block` (section content) from the database and renders
> them — **dynamic SSR**, or ISR with **on-demand revalidation** fired the instant an edit is
> saved. So when Claude changes a color, swaps an image, edits copy, or reorders sections, the
> store updates **within seconds — no rebuild, no file upload.** And because edits are
> **structured, schema-validated data** (a typed token/section model), they can't produce the
> broken-/half-deployed-theme bugs that made the WooCommerce workflow so painful. This is the
> mechanism that ends the "edit → redeploy → repeat 20×" loop.

**Safety (review-driven — see `07-architecture-hardening.md`):** edits don't hit the live store
directly. Claude writes a **draft version**, it renders on a **preview URL** (cache bypassed),
and a `commit_changes` step **publishes** it (instant, still zero-deploy) — with full **version
history + rollback**. The model is split into **Content** (what) vs **Presentation** (colors/
fonts/spacing/layout) so AI editing stays clean and the same content can later feed mobile/AMP/
email. Every write is **JSON-Schema-validated**, so a malformed block is rejected instead of
crashing the storefront.

**Why this design:** owner-editable look (tokens + section order) covers 90% of "I want to
change my store's design" without a developer, while deeper changes are still just React
components a developer can add.

## 2. Plugin / extension model (capabilities)

We use **Medusa's own extension mechanisms** rather than inventing a plugin format:

| Layer | Mechanism | Examples |
|---|---|---|
| **Backend capability** | Medusa **module / plugin** | Payment providers (Razorpay, Stripe), shipping calculators, search (MeiliSearch), the AI service |
| **Provider plugins** | Medusa **provider modules** | `payment-razorpay`, `payment-stripe`, `notification-email` |
| **Admin screens** | Medusa Admin **UI extensions** (widgets/routes) | Store Copilot, Marketing, Content editor, A/B, Integrations |
| **Storefront blocks** | Next.js section components | Theme sections above |
| **Workflows/automation** | n8n + Medusa subscribers/workflows | "order placed → send to marketing agents / feeds" |

**The Integrations screen** reads `plugin_registry` and lets the owner enable/configure each
integration (keys entered are stored as env references, not raw). Planned integrations:

- **Payments:** Razorpay (India — UPI/cards/netbanking), Stripe + PayPal (international).
- **Email:** a transactional provider (order/shipping emails) + Mailchimp for campaigns
  (Mailchimp MCP tools already exist in this environment).
- **Ad insights:** **Meta Ads** — spend, ROAS, and campaign performance pulled into the
  Analytics/Integrations screen and queryable from Claude (Meta MCP tools already available).
- **Feeds:** Meta catalog + Google Merchant product feeds.
- **Marketplace channels:** **Amazon** (SP-API) + **Flipkart** (Seller API) — push the Medusa
  catalog out and manage those listings from the platform/Claude. **Credential-gated:** needs
  the owner's seller accounts + API app approval; lands in v2.
- **Selling channels (`08 §4`):** **WhatsApp** (Business **Cloud API** — catalog, segmented
  broadcasts, abandoned-cart recovery, order updates, broadcast-to-buy), **Instagram**
  (Reels→product-tag→site, UGC, product drops), **YouTube** (how-to funnel) — all via the
  **Channel Manager** interface (`07 §12`). WhatsApp/IG are credential-gated on Meta onboarding
  (dedicated number + template approval for WhatsApp).
- **Automation:** the existing n8n instance for scheduling agent runs and webhooks.

```mermaid
flowchart TB
    REG[("plugin_registry")] --> INTG["Integrations screen (admin)"]
    INTG -->|enable/config| PAYP["Payment plugins"]
    INTG --> MAILP["Email/Mailchimp"]
    INTG --> METAP["Meta Ads insights"]
    INTG --> FEEDP["Meta/Google feeds"]
    INTG --> MKTP["Amazon / Flipkart channels"]
    INTG --> SELL["WhatsApp / Instagram / YouTube"]
    INTG --> N8N["n8n automation"]
    PAYP --> API["Medusa backend"]
    MAILP --> API
    METAP --> API
    FEEDP --> AGENTS["Marketing agents"]
    MKTP --> API
    SELL --> API
```

## 3. Build vs. integrate (so we don't over-build)

| Need | Decision |
|---|---|
| Payments | **Integrate** Razorpay/Stripe via Medusa provider plugins (don't build) |
| Email sending | **Integrate** a provider; don't run our own SMTP |
| Search | **Start** with Postgres FTS; **integrate** MeiliSearch/Algolia when needed |
| Themes | **Build** one handloom theme; make the system pluggable for more |
| Page building | **Build** a light section-ordering editor; not a full drag-drop builder in MVP |
| Ad insights | **Integrate** Meta Ads API (read-only reporting) |
| Marketplace listing | **Integrate** Amazon SP-API / Flipkart Seller API; credential-gated, v2 |
| Marketplace of apps | **Defer** to v2 (`plugin_registry` is the seam that makes it possible) |