# VVS Jewelry Store — Deployment Guide

Live inventory powered by a real-time VDB proxy. Customers see only VVS branding and marked-up prices.

## Architecture

```
Customer → Next.js Storefront (Vercel)
              ↓ API key
         VDB Session Service (Contabo VPS + PM2)
              ↓ Playwright + VDB login
         app.vdbapp.com (hidden)
```

## 1. Prerequisites

- VDB account with active login session
- Contabo VPS with Node.js 20+ and PM2
- Vercel account for the storefront
- Domain pointed to Vercel (e.g. vvsjewelrystore.com)

## 2. Initial VDB Login

On your local machine or VPS:

```bash
npm run login
```

Log in to VDB, apply your default filters, press Enter. This saves `auth/session.json`.

Optionally capture filters:

```bash
npm run save-filters
```

## 3. Deploy Session Service (Contabo VPS)

### Install

```bash
cd /home/youruser/vdb-script
npm run session:install
npm install -g pm2
```

### Environment

Create `services/vdb-session/.env`:

```
VDB_SESSION_PORT=3100
VDB_SESSION_API_KEY=your-long-random-api-key
VVS_TOKEN_SECRET=your-long-random-token-secret
HEADLESS=true
```

Copy `auth/session.json` to the VPS at `auth/session.json`.

### Start with PM2

From project root:

```bash
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup
```

### Nginx reverse proxy (WHM/cPanel)

Create subdomain `vdb-api.yourdomain.com` pointing to `localhost:3100`.

Restrict access: only allow Vercel outbound IPs or keep port firewalled and rely on API key auth.

### Health check

```bash
curl -H "X-API-Key: your-api-key" http://localhost:3100/internal/health
```

## 4. Deploy Storefront (Vercel)

### Install locally

```bash
npm run storefront:install
cp storefront/.env.local.example storefront/.env.local
```

Edit `storefront/.env.local`:

```
VDB_SESSION_URL=https://vdb-api.yourdomain.com
VDB_SESSION_API_KEY=your-long-random-api-key
VVS_TOKEN_SECRET=your-long-random-token-secret
VVS_MARGIN_PERCENT=20
VVS_MARGIN_MIN_FLAT=20
```

### Vercel settings

- **Root Directory:** `storefront`
- **Framework:** Next.js
- Add the same env vars in Vercel dashboard
- Enable parent directory access (the app imports from `../lib` via `externalDir`)

Alternatively deploy the whole repo with root directory `storefront` and ensure `lib/` is included.

### Run locally

Terminal 1 — Session Service:

```bash
npm run session
```

Terminal 2 — Storefront:

```bash
npm run storefront
```

Open http://localhost:3000

## 5. Session Refresh

When VDB session expires:

1. Run `npm run login` (locally or on VPS via SSH)
2. Copy updated `auth/session.json` to VPS if logged in locally
3. Reload session service:

```bash
curl -X POST -H "X-API-Key: your-api-key" http://localhost:3100/internal/reload-session
```

Or restart PM2:

```bash
pm2 restart vdb-session
```

## 6. Margin Configuration

Adjust pricing without code changes via env vars:

```
VVS_MARGIN_PERCENT=20
VVS_MARGIN_MIN_FLAT=20
```

Formula: `margin = max(VVS_MARGIN_MIN_FLAT, base × VVS_MARGIN_PERCENT%)`

## 7. Security Checklist

- [ ] Change `VDB_SESSION_API_KEY` from default
- [ ] Change `VVS_TOKEN_SECRET` from default
- [ ] Never commit `auth/session.json`
- [ ] Session Service not publicly browsable (API key required)
- [ ] Firewall blocks direct access to port 3100 except Nginx
- [ ] Vercel env vars set for production

## 8. What Customers See vs. What's Hidden

| Visible | Hidden |
|---------|--------|
| VVS Jewelry Store branding | VDB name/logo/URLs |
| VVS reference IDs | VDB diamond IDs |
| VVS marked-up prices | Base cost, margin |
| Proxied images/certs | Supplier names, contacts |
| Diamond specs | Vendor locations |