# Client Demo / Handoff Runbook

This document is the current demo and handoff guide for the ELIT Gold/Silver Exchange storefront and admin build. It is intended for client demos, internal walkthroughs, and handoff discussions before production launch planning.

Do not place real credentials, sandbox account passwords, webhook keys, client secrets, access tokens, or private URLs in this file.

## Demo Overview

This is the current demo-ready build of the ELIT Gold/Silver Exchange platform.

- The storefront supports product browsing, cart, checkout, and sandbox payment demonstrations.
- Product checkout currently supports Square sandbox and PayPal sandbox for physical bullion products.
- The admin area supports product management, order review, payment visibility, reports, public form intake review, and service request handling.
- Several production items are intentionally deferred until the team has a stable production domain, final hosting decisions, and live provider credentials.

## Demo Flow Checklist

### A. Storefront

1. Open the homepage and explain the storefront positioning.
2. Show the products listing page and product discovery flow.
3. Open at least one product detail page.
4. Add a physical bullion product to cart.
5. Open the cart page.
6. Proceed to checkout.

Suggested routes:

- `/`
- `/products`
- `/products/[slug]`
- `/cart`
- `/checkout`

### B. Payments

At checkout, explain:

- Square is available for sandbox card checkout.
- PayPal is available for sandbox approval/capture checkout.
- Successful payments clear the cart and redirect to `/payment-success`.
- Failed or canceled payments keep the cart available for retry and redirect to `/payment-failed`.
- The local demo database preserves proof payment records that can be shown in admin:
  - one Square `PAID` proof order
  - one PayPal `PAID` proof order

### C. Admin

After login, walk through:

- products
- orders
- payments
- reports
- contact tickets
- sell-back requests
- IRA/trust applications
- service payments

Suggested routes:

- `/admin/login`
- `/admin/products`
- `/admin/orders`
- `/admin/payments`
- `/admin/reports`
- `/admin/contact-tickets`
- `/admin/sell-back-requests`
- `/admin/ira-trust-applications`
- `/admin/service-payments`

### D. Forms

Show that the following public intake flows exist and are stored for admin review:

- support/contact
- sell-back
- IRA/trust
- service fees

Suggested routes:

- `/support`
- `/sell-back`
- `/ira-trust`
- `/service-fees`

### E. Recommendation Engine

Show the homepage recommendation area and explain:

- Today's Best Product
- Top Alternatives
- Recommendation Picks
- admin-entered scoring factors drive the ranking
- results are informational only and not financial advice

## Feature Readiness

| Category | Item | Status Note |
| --- | --- | --- |
| Ready for demo | Storefront catalog | Product listing and detail flow are available for physical bullion products. |
| Ready for demo | Cart | Add, remove, update, and hydration behavior are working for demo. |
| Ready for demo | Square sandbox checkout | Implemented, hardened, and tested for product checkout. |
| Ready for demo | PayPal sandbox checkout | Implemented and tested for product checkout. |
| Ready for demo | Admin products, orders, payments, reports | Core admin review and management areas are available. |
| Ready for demo | Public request forms | Support, sell-back, IRA/trust, and service fee request flows are available. |
| Ready for demo | Recommendation Center | Homepage recommendation module is working with admin-managed scoring inputs. |
| Ready for demo | Product image upload local demo | Local upload flow works for demo and local staging use. |
| Ready for demo | Rate limit and honeypot first layer | Lightweight first-layer anti-abuse protection is in place. |
| Implemented, provider/config needed | Email notification readiness | Foundation exists, but real sending requires provider credentials and launch-time configuration. |
| Implemented, provider/config needed | Product image storage strategy | Production-safe storage needs a final hosting/storage decision if serverless hosting is used. |
| Deferred until production/stable URL | Square webhook | Deferred until stable production URL and final webhook setup plan. |
| Deferred until production/stable URL | Live Square and PayPal credentials | Sandbox is used for demo; live credentials should be added only during launch preparation. |
| Deferred until production/stable URL | Service-fee Square and PayPal payment flows | Currently marked as coming soon unless explicitly enabled in a later sprint. |
| Future enhancement | Refund and dispute sync | Not yet implemented. |
| Future enhancement | Production object storage implementation | Planned after storage provider decision. |
| Future enhancement | CAPTCHA / Turnstile / reCAPTCHA | Not yet implemented. |
| Future enhancement | Real email notification sending | Prepared, but not enabled yet. |
| Future enhancement | Legal and policy review | Required before live launch. |
| Future enhancement | Order confirmation emails | Not yet implemented. |

## Known Demo Notes

- Do not use live payment credentials during demo.
- Do not paste secrets into screenshots, chats, tickets, or docs.
- Cloudflare tunnel URLs can change during development.
- PayPal return and cancel URLs depend on `NEXT_PUBLIC_APP_URL`.
- Square webhook should not be tested against changing tunnel URLs.
- The local demo database was cleaned and now preserves only proof payment orders after test cleanup.
- Product image upload currently works locally and is acceptable for demo, but production persistence depends on the final hosting/storage decision.

## Production Handoff Requirements

Before live launch, the client or deployment team must provide or confirm:

- production domain
- production hosting choice
- production database choice
- live Square credentials
- live PayPal credentials
- Square webhook notification URL
- email provider credentials if email sending is desired
- production image storage decision
- final admin credentials
- final legal and policy content review

## Final Pre-Demo Manual QA Checklist

- Homepage desktop layout looks correct.
- Homepage mobile layout looks correct.
- Product filters, search, and sort behave correctly on `/products`.
- Product detail page loads correctly.
- Add to cart works.
- Cart refresh and hydration behave correctly.
- Checkout UI shows both Square and PayPal options.
- Payment success page renders correctly.
- Payment failed page renders correctly.
- Admin orders page loads and shows payment/provider data.
- Admin payments page loads and shows status/provider data.
- Admin reports page loads and shows paid-order-only revenue.
- Public forms render and submit with clean success/error handling.
- Service-fees page copy clearly marks unavailable provider flows honestly.
- Mobile layout sanity check passes for homepage, products, cart, and checkout.

## What To Show Vs. What To Explain

Show directly in the demo:

- storefront browsing
- cart and checkout flow
- Square and PayPal availability in sandbox
- admin product/order/payment/reporting views
- public form intake pages
- recommendation engine section on the homepage

Explain verbally instead of promising as complete:

- Square webhook reconciliation
- live payment credentials and launch cutover
- production object storage for product images
- real email delivery
- service-fee live provider payment enablement
- refund/dispute handling

## Related Documentation

- `README.md`
- `PRODUCTION_DEPLOY_CHECKLIST.md`
- `QA_CHECKLIST.md`