# Shopify Product Configurator — Setup Guide

## How to Make the App Appear in Shopify Admin

### Architecture Overview

```
Shopify Admin (admin.shopify.com)
    └── Apps section
            └── "Product Configurator" ← Our app appears here
                    └── Loads our app in an iframe
                            └── http://YOUR_NGROK_URL/admin
```

---

## Step 1: Create a Shopify Partner App

1. Go to **https://partners.shopify.com**
2. Log in (or create a free account)
3. Click **Apps** → **Create app** → **Create app manually**
4. Fill in:
   - **App name**: `Ardry Product Configurator`
   - **App URL**: `https://YOUR_NGROK_URL` (you'll update this after Step 2)
   - **Allowed redirection URLs**: `https://YOUR_NGROK_URL/shopify/callback`
5. Click **Create app**
6. Copy your **API key** and **API secret key**

---

## Step 2: Install ngrok (expose localhost to internet)

Shopify requires HTTPS. ngrok creates a secure tunnel.

```bash
# Install ngrok
npm install -g ngrok

# OR download from https://ngrok.com/download

# Start tunnel (in a new terminal)
ngrok http 3000
```

You'll see output like:
```
Forwarding  https://abc123.ngrok-free.app -> http://localhost:3000
```

Copy the `https://abc123.ngrok-free.app` URL.

---

## Step 3: Update Your .env File

```env
PORT=3000
NODE_ENV=development

# Database
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=kspl@1234
DB_NAME=ardry

# Shopify App Credentials (from Step 1)
SHOPIFY_API_KEY=your_api_key_from_partners
SHOPIFY_API_SECRET=your_api_secret_from_partners
SHOPIFY_SCOPES=read_products,write_products,read_orders,write_orders,read_script_tags,write_script_tags
SHOPIFY_APP_URL=https://YOUR_NGROK_URL

# Session
SESSION_SECRET=change_this_to_a_random_string_in_production
```

---

## Step 4: Update App URL in Shopify Partners

1. Go back to your app in Shopify Partners
2. Click **App setup** → **URLs**
3. Update:
   - **App URL**: `https://YOUR_NGROK_URL`
   - **Allowed redirection URLs**: `https://YOUR_NGROK_URL/shopify/callback`
4. Save

---

## Step 5: Install the App on Your Store

1. In Shopify Partners → Your app → **Test your app**
2. Click **Select store** → choose `ardry-group`
3. Click **Install app**
4. You'll be redirected through OAuth → approve permissions
5. After install, the app appears under **Apps** in your Shopify admin!

---

## Step 6: Start the Server

```bash
# Terminal 1: Start ngrok
ngrok http 3000

# Terminal 2: Start the app
cd /var/www/html/ArdryProductConfigurator
node server.js
```

---

## Step 7: Access the App

- **Via Shopify Admin**: Go to `admin.shopify.com/store/ardry-group` → Apps → Product Configurator
- **Direct URL**: `https://YOUR_NGROK_URL/admin`

---

## How the Embedded App Works

When Shopify loads our app:
1. Shopify opens `https://YOUR_NGROK_URL/?shop=ardry-group.myshopify.com&host=BASE64_HOST`
2. Our server checks if the shop is installed
3. If not installed → redirects to OAuth
4. If installed → serves the admin React app
5. The React app initializes **App Bridge** which communicates with Shopify admin
6. Our app appears seamlessly inside the Shopify admin UI

---

## Install Script Tag on Store (for Frontend Configurator)

After the app is installed, register the script tag so the configurator appears on product pages:

```bash
curl -X POST https://YOUR_NGROK_URL/shopify/install-script \
  -H "Content-Type: application/json" \
  -d '{"shop": "ardry-group.myshopify.com"}'
```

This installs `snippet/configurator.js` on all pages of the store.

---

## Workflow Summary

```
Admin creates attributes
        ↓
Admin associates attributes with products
        ↓
Script tag auto-loads on product pages
        ↓
Customer sees custom options on product page
        ↓
Customer fills options & adds to cart
        ↓
Options saved as Line Item Properties in Shopify order
        ↓
Admin sees order configurations in our app
```

---

## File Structure

```
ArdryProductConfigurator/
├── server.js              ← Express backend (port 3000)
├── .env                   ← Your credentials
├── database/
│   └── schema.sql         ← MySQL schema (ardry DB)
├── routes/
│   ├── attributes.js      ← /api/attributes
│   ├── products.js        ← /api/products
│   └── shopify.js         ← /shopify (OAuth + webhooks)
├── controllers/
│   ├── attributeController.js
│   └── productController.js
├── admin/                 ← React admin panel
│   ├── src/
│   │   ├── App.js         ← Routes
│   │   ├── pages/
│   │   │   ├── Dashboard.js
│   │   │   ├── AttributesPage.js
│   │   │   ├── AttributeForm.js
│   │   │   ├── GroupsPage.js
│   │   │   ├── ProductsPage.js
│   │   │   └── OrdersPage.js
│   │   └── components/
│   │       ├── Layout.js
│   │       └── Toast.js
│   └── build/             ← Built React app (served by Express)
└── snippet/
    └── configurator.js    ← Injected into Shopify store frontend