GripFit E-commerce: React + Vite Migration PRD

How this was produced. I read the full database schema, all URL routes, the config/constants, shared helpers, the checkout / cart / order / auth / NCM flows, the admin module list, the theme CSS variables and the logo files. I did not read every line of the ~27k lines of PHP. Items marked [Confirm] are places where the code was ambiguous (for example commented-out blocks) and need a short discovery check before build.

1. Summary

1.1 What exists today

A server-rendered PHP 8 / MySQLi / session-based store with:

• A customer storefront (home, shop, product, cart, checkout, order confirmation, order tracking, wishlist, account, static pages).
• A full admin panel (dashboard with analytics, products, catalog taxonomies, orders, users, coupons, hero slides, reviews, stock purchasing, audit logs, settings).
• Email/password + Google OAuth login stored in MySQL, an admin access-code second factor, PHPMailer emails, Web Push (VAPID), a PWA service worker, and Nepal Can Move (NCM) shipping webhooks.
• A 26-table MySQL schema, all money stored as integer rupees.

1.2 What we are building

1.3 A critical architectural point

MySQLi is a PHP extension. A React/Vite app runs in the browser and cannot connect to MySQL. So "React Vite with MySQLi" necessarily means:

• Frontend: React + Vite (static build).
• Backend: a slim PHP API that uses mysqli with prepared statements and returns JSON.

Firebase is used only to answer "who is this person?". Every authorization decision (customer vs admin, who owns which order) is made by the PHP API against MySQL. This is the design assumed throughout the document.

1.4 Assumptions

1. "Sophify" = Shopify. I interpret the theme as a Shopify-like look: generous whitespace, thin borders, restrained type, monochrome with almost no decoration.
2. Hosting is Apache/PHP shared hosting or a VPS (the current .htaccess, Cloudflare X-Forwarded-Proto handling, and Sundarharaicha, Morang shop address suggest this). The frontend deploys as static files; the API deploys as PHP.
3. Language and locale: English UI, Rs. currency, Asia/Kathmandu timezone (UTC+05:45).
4. Scope is parity. No new commerce features are added except those listed in section 14 (optional).
5. Logos: the four logo files already exist in the zip under assets/img/ (not assets/image/). Section 9.3 maps them. If you supply new versions, only filenames need to match.

2. Goals, non-goals, success criteria

2.1 Goals

• G1. Feature parity: every customer and admin capability in section 5 works in the new app.
• G2. Database continuity: the same tables, columns, enums and relationships. Changes are additive and listed in section 6.
• G3. Firebase as the identity provider only: no passwords, OAuth secrets or reset codes handled by our server.
• G4. Design unification: one monochrome design system, light and dark, used by both storefront and admin.
• G5. Lightweight and fast by default: small bundles, lazy-loaded images and routes, and measurable performance budgets enforced in CI (section 12.1). Target: fast on mid-range Android over 4G, the dominant Nepal audience.
• G6. Safe migration: existing customers, orders, reviews, wishlists and carts survive with no forced data loss.

2.2 Non-goals

• Replacing MySQL, moving to Firestore, or using Firebase for storage/hosting/database.
• Building online payment-gateway integrations (eSewa/Khalti APIs). Current flow is manual proof-of-payment and stays that way.
• Multi-language, multi-currency, or multi-vendor support.
• A native mobile app (the PWA covers mobile).

2.3 Success criteria

3. Users and roles

Role is stored in MySQL (as today). Firebase custom claims may mirror it as a convenience, but the API never trusts the claim alone; it re-reads users.role and users.status.

4. Target architecture

4.1 Diagram (logical)

Browser (React SPA, Vite build, PWA)
  ├─ Firebase JS SDK  ── sign in / sign up / Google / reset ──▶ Firebase Auth
  │        └─ getIdToken()
  └─ fetch('/api/...', Authorization: Bearer <Firebase ID token>)
            │
            ▼
PHP API (mysqli, prepared statements, JSON)
  ├─ verifies ID token (Google public keys, aud/iss/exp)
  ├─ maps firebase_uid ▶ users row (role, status)
  ├─ MySQL (same schema)
  ├─ PHPMailer (order/contact/payment-reminder/delete-code emails)
  ├─ minishlink/web-push (VAPID push)
  ├─ NCM webhook receiver + NCM API client
  └─ uploads/ (products, brands, categories, slides, avatars; payment_receipts private)

4.2 Frontend stack (recommended)

4.3 Backend stack

• PHP 8.1+, mysqli with mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT), prepared statements only.
• Composer: keep phpmailer/phpmailer, minishlink/web-push; add kreait/firebase-php (verification + user management) or firebase/php-jwt + Google JWKS caching if you want fewer dependencies.
• A minimal router (single api/index.php front controller, or a micro-framework such as Slim). No ORM; keep SQL close to today's queries so behavior stays identical.
• Response envelope: { "success": true, "data": {...}, "meta": {...} } / { "success": false, "message": "...", "errors": {...} } (extends today's {success, message} convention).
• JSON body for most endpoints; multipart/form-data for image uploads.
• CORS allow-list (your production domain + localhost dev). CSRF tokens are no longer needed for bearer-token calls; do not use cookies for auth.
• Front controller applies: rate limiting (existing rate_limits table), Firebase auth middleware, role middleware (customer, admin, superadmin), admin-access-code middleware, audit-log helper (existing logAudit).

4.4 Repo layout

gripfit/
├─ web/                      # React + Vite
│  ├─ src/
│  │  ├─ app/                # router, providers (Query, Theme, Auth)
│  │  ├─ features/           # catalog, cart, checkout, orders, account, wishlist, reviews, notifications
│  │  ├─ admin/              # dashboard, products, orders, users, coupons, ...
│  │  ├─ components/ui/      # Button, Input, Modal, Drawer, Toast, Skeleton, Pagination ...
│  │  ├─ lib/                # api client, firebase.ts, format.ts (Rs. formatting), nepalAddress.ts
│  │  ├─ styles/tokens.css   # light/dark variables
│  │  └─ assets/logos/       # grip.png, grip-dark.png, grip-icon.png, grip-icon-dark.png
│  └─ public/                # manifest, icons, offline.html, robots.txt
├─ api/                      # PHP
│  ├─ public/index.php       # front controller
│  ├─ src/{Http,Auth,Repositories,Services,Support}/
│  ├─ config/                # env loader, constants
│  ├─ migrations/            # 0001_baseline.sql, 0002_firebase.sql, ...
│  ├─ uploads/               # + .htaccess protections (as today)
│  └─ composer.json
└─ docs/                     # this PRD, API contract (OpenAPI), runbooks

5. Feature inventory and requirements

Priority: P0 = launch blocker, P1 = required for parity, ships in same release if possible, P2 = post-launch/optional.

5.1 Storefront

5.2 Authentication (Firebase)

5.3 Admin panel

All under /admin, lazy-loaded, protected by A-06/A-07, every mutation writes to audit_logs.

5.4 Integrations

6. Data model

6.1 Principle

Keep database.sql as the baseline (opencodegrip1), convert it to versioned migrations, apply only additive changes, and keep names, types and enums. All 26 tables are retained:

users, audit_logs, categories, brands, departments, products, product_images, sizes, colors, product_stock, cart, wishlist, orders, order_items, coupons, coupon_usage, site_settings, password_resets, rate_limits, stockadmin, stockadmin_variant, push_subscriptions, hero_slides, reviews, notifications, user_notifications

6.2 Required schema changes (migration 0002)

Everything else stays byte-for-byte identical. Character set stays utf8mb4_unicode_ci, engine InnoDB.

6.3 site_settings keys (unchanged)

site_name, announcement_bar, announcement_bar_enabled, maintenance_mode, shipping_cost, free_shipping_threshold, free_shipping_threshold_enabled, shop_email, shop_phone, shop_address, shop_whatsapp, social_facebook, social_twitter, social_instagram, social_youtube, smtp_user, smtp_pass, emails_enabled, admin_access_code, size_sort_order

Requirements:

• Public settings endpoint must return only non-secret keys (site name, announcement, contact, socials, shipping numbers, maintenance flag).
• smtp_pass and admin_access_code are write-only in the admin UI (never returned to the browser). Prefer storing them only in server env; DB values remain as an override for parity.

6.4 Key relationships to preserve

• products → departments/categories/brands (ON DELETE SET NULL), product_images and product_stock (CASCADE).
• product_stock unique on (product_id, size_id, color_id); all prices live on the variant; a product's displayed price is MIN(price) across in-stock variants.
• cart unique on (user_id, stock_id, product_id).
• order_items are snapshots (product_name, price, size, color) with nullable product_id/stock_id (SET NULL).
• coupon_usage per (coupon, user, order); coupons.used_count incremented in the order transaction.
• reviews unique on (user_id, product_id, order_item_id).

6.5 Seed data

database-seed.sql (settings, sizes, colors) becomes seeds/0001_defaults.sql. Add a dev-only sample catalog seed for demos and Playwright tests.

7. API specification (v1)

Base path /api/v1. Auth column: P public, U Firebase user, A admin (Firebase + role + admin token), S superadmin.

7.1 Public / catalog

7.2 Auth & account

7.3 Shopping

7.4 Admin (all A, all audited)

/admin/dashboard, /admin/products (+ bulk, lookup, image upload/reorder), /admin/{categories|brands|departments|sizes|colors}, /admin/orders (+ /{id}/status, /{id}/payment, /{id}/note, /{id}/transfer, /{id}/ncm, /{id}/reminder, /{id}/push, /{id}/receipt), /admin/users, /admin/coupons, /admin/hero-slides, /admin/reviews, /admin/stock-purchases, /admin/audit-logs, /admin/settings, /admin/notifications/send.

7.5 Cross-cutting API rules

1. Never trust client money. Line prices, discount and shipping are recomputed server-side from the DB at order time.
2. Validate token every request: signature, aud = Firebase project id, iss, exp; cache Google public keys per Cache-Control.
3. Stateless coupon: the old $_SESSION['applied_coupon'] becomes a client-held code that is revalidated at POST /orders.
4. Pagination uses page + per_page and returns meta: {total, pages}.
5. Idempotency: POST /orders accepts an Idempotency-Key header to prevent double orders on flaky mobile networks.
6. Uploads: max 2 MB; allowed real MIME jpeg/png/webp/gif (checked with finfo, not extension); re-encoded to WebP; random or order-based filenames; payment_receipts/ never publicly served.
7. Errors: consistent HTTP codes (401 unauthenticated, 403 forbidden, 404, 409 stock conflict, 422 validation, 429 rate limit).
8. Timezone: DB session set to +05:45 for NOW() semantics as today, or store UTC and convert in the API (decide once; see open question Q6).

7.6 Migrating existing users to Firebase

1. Export users (email, full_name, password hash, google_id).
2. Use Firebase Admin importUsers:
   • Email/password users: import with the bcrypt hash (PHP's PASSWORD_DEFAULT = bcrypt $2y$). Spike required to confirm Firebase accepts $2y$ hashes as-is (some setups need $2a$); if not, fall back to lazy migration: first login shows "set a new password" via reset email.
   • Google-only users: import with the Google provider info (email) so first Google sign-in links to the same account.
3. Write returned UIDs into users.firebase_uid. Users whose email cannot be matched are linked on first POST /auth/session by verified email.
4. Keep a rollback window with the old PHP site behind a maintenance banner.

8. Business rules (must not change)

8.1 Orders

• Statuses: pending → processing → shipped → delivered, plus cancelled.
• Payment statuses: unpaid, verifying, partial_paid, paid, failed, refunded.
• Types: online, offline (admin-created in-store).
• Payment methods: whatsapp (unpaid until confirmed), prepaid (gateway esewa | bank_transfer, screenshot required, starts as verifying).
• Order number: yymmdd + 8 uppercase hex chars, unique.
• Customer cancel: only pending, only owner; restores stock unless already paid; if paid → payment status becomes refunded.
• Stock: decremented when the order is placed, inside the transaction, with row-level locking or conditional UPDATE ... WHERE quantity >= ? so concurrent buyers cannot oversell; restored on cancel/return.

8.2 Shipping

shipping = 0 when free_shipping_threshold_enabled and (cart_total ≥ threshold or total_after_discount ≥ threshold); otherwise shipping_cost. The current default values are shipping_cost = 1000 and free_shipping_threshold = 500 in code (both DB-overridable). [Confirm production values; a 500 threshold with 1000 shipping looks like a placeholder.]

8.3 Coupons

Discount base is the eligible subtotal only (all / category / brand / product scope). Percentage discounts must be computed as integer rupees (the current code rounds to 2 decimals into an INT column). Choose ROUND() to nearest rupee and apply consistently client and server. A coupon cannot exceed the eligible amount.

8.4 Reviews

Verified purchaser only (has a non-cancelled purchase of that product). Starts pending; only verified reviews count toward rating aggregates.

8.5 Privacy & retention

Soft-deleted users keep order history for accounting; personal profile fields (phone/address/avatar) are cleared on deletion [Confirm policy]. Payment receipts are private.

9. Design system (Shopify-style black & white)

9.1 Principles

1. Monochrome first: black, white and neutrals carry the whole UI. Color appears only for semantic state (success, warning, danger, info) and in the brand logo.
2. Content over chrome: thin 1 px borders, minimal shadows, generous whitespace, product imagery is the hero.
3. Quiet motion: 150-200 ms opacity/transform transitions; respects prefers-reduced-motion.
4. Consistency: the admin panel uses the same tokens and components as the storefront, just denser.

9.2 Tokens (reuse existing values)

Defined in styles/tokens.css, exposed to Tailwind via CSS variables.

Primary buttons are solid black (light theme) / solid near-white (dark theme) with inverted text. Secondary buttons are 1 px bordered. Focus ring: 2 px --accent with 2 px offset.

9.3 Theme toggle requirements

9.4 Logo handling

Existing files in the zip (assets/img/), verified visually: a bold black-and-white "GT" mark and "GRIPFIT" wordmark with a red claw/FIT accent.

Requirements:

• A single <Logo /> component renders all four <img> variants and swaps them with CSS only ([data-theme] + media query → display), so there is no layout shift and no flash when the theme or viewport changes.
• Sizes: wordmark height 36 px in the nav (as today), icon 32-36 px on mobile; always give width/height attributes and alt="GripFit".
• Logos are above the fold and must not be lazy-loaded (see IMG-13). Only the variant matching the current theme and viewport is fetched: hidden variants use loading="lazy" or are swapped via CSS content/<picture> with media queries so the browser downloads one file, not four. Convert the logos to SVG (or optimized WebP under 10 KB each) to keep them tiny.
• Provide @2x versions (or SVG) for crisp rendering on retina phones; the current PNGs are small (512 px wide) for large screens. If you supply new files, keep these four names or tell the team the new names.
• Same components in the admin sidebar/header, emails (light version), PWA splash, and og:image.
• Favicons and PWA icons from assets/icons/ (16/32/180/192/512) are reused; add a maskable 512 icon and a dark-mode favicon variant (favicon-light-32.png already exists).
• Because the logo carries red, the "black and white" rule applies to UI chrome only; do not introduce red elsewhere (danger states use --danger).

9.5 Component inventory

Header (announcement bar, logo, search with live results, nav, wishlist, cart with count badge, notification bell with unread dot, account menu, theme toggle, mobile menu), Footer, Product card (image, brand, name, price/old price, on-sale and out-of-stock badges, wishlist heart, quick add), Product gallery + lightbox, Variant selectors (size chips, color chips), Quantity stepper, Mini-cart drawer, Filter sidebar/sheet (mobile bottom-sheet), Pagination, Breadcrumbs, Rating stars, Review card, Status badges (order/payment), Address picker (cascading selects), Toast, Modal, Confirm dialog, Skeleton loaders (cards, table rows, forms, order cards, summary, profile, product detail: parity with renderSkeleton*), Empty states, Admin data table (sortable, filterable, bulk select), Stat card, Chart card, Image uploader (drag-drop, reorder, preview).

9.6 Responsive & accessibility

• Breakpoints: 992 px (nav collapse, as today), 768 px (logo swap), 480 px (single-column grids).
• Keyboard-navigable menus, dialogs with focus trap, visible focus, aria-live for cart/toast updates, semantic landmarks, alt text on all images, form errors linked with aria-describedby.
• Touch targets ≥ 44 px on mobile.

10. Routes

10.1 Storefront

10.2 Legacy URL compatibility

The old site already 301-redirects *.php to clean URLs and product URLs are /shop/{slug}. Keep every clean URL identical so SEO, WhatsApp links and printed material keep working. Keep 301s for /product.php?slug= and other .php URLs.

10.3 Admin

/admin (dashboard), /admin/verify, /admin/products, /admin/products/new, /admin/products/:id, /admin/{categories|brands|departments|sizes|colors}, /admin/orders, /admin/orders/new, /admin/orders/:id, /admin/users, /admin/users/:id, /admin/coupons, /admin/hero-slides, /admin/reviews, /admin/stock, /admin/audit-logs, /admin/settings.

11. Security requirements

1. Rotate secrets found in the upload. The zip contains a real .env and the .git history. The .env holds DB credentials, SMTP password, admin access code, NCM token, Google client secret and VAPID private key, and one SMTP app password is pasted in plain text inside a comment. Treat all of them as exposed: rotate every one before launch, delete them from git history, and never ship .env, .git, .kilo, graphify-out, cache/, test_db.php or css-optimization-test.html to production.
2. Firebase config split: the web firebaseConfig (apiKey, projectId...) is public by design. The service-account JSON is private and lives only on the PHP server, outside the web root. Restrict the Firebase API key by HTTP referrer and enable authorized domains only.
3. Prepared statements everywhere; no string-built SQL.
4. AuthZ on every route, including owner checks on orders, cart, wishlist, reviews, and addresses.
5. Rate limits (existing table): login attempts are now Firebase's; keep server limits for register-sync, contact, tracking, coupon validation, admin-code (5 tries / 15 min), reset/delete codes.
6. Admin hardening: access-code second factor, short-lived admin token, audit trail on all writes, optional IP allow-list.
7. Uploads: as in 7.5 #6; upload directories get .htaccess (no PHP execution) as today; receipts served only through an authorised endpoint.
8. Headers: HTTPS redirect (existing), HSTS, X-Content-Type-Options, Referrer-Policy, a Content-Security-Policy that allows Firebase and Google Fonts only as needed.
9. XSS: React escapes by default; sanitize any admin-authored rich text (product description, FAQ) with DOMPurify before dangerouslySetInnerHTML.
10. PII: phone/address minimisation in logs; audit-log details must not store secrets.

12. Non-functional requirements

12.1 Performance: lightweight build, fast loading, lazy images

The storefront must feel instant on a mid-range Android phone over 4G. Everything below is a requirement, not a suggestion, and the budgets are enforced in CI.

12.1.1 Performance budgets (enforced by size-limit and Lighthouse CI)

12.1.2 Lazy image loading (all images)

Server-side image pipeline (new requirement, the current uploadImage() converts to WebP but does not resize): on upload, the API generates 400 / 800 / 1200 px WebP variants (quality ~75-80, strip metadata), stores the paths, and returns a srcset-ready structure. Existing images are backfilled by a one-off script. Uploaded originals over 2 MB are still rejected (existing rule).

12.1.3 JavaScript and CSS weight

1. Route-level code splitting with React.lazy for every page; the admin area is a separate chunk tree that shoppers never download.
2. Firebase Auth is lazy-loaded. Use the modular SDK (firebase/auth only, no other Firebase products) and load it with dynamic import(). It loads on /login, /register, /forgot-password, or on first page load only if a "was signed in" hint exists in localStorage, so anonymous shoppers never pay for it. Google sign-in code loads only when the Google button is pressed.
3. Heavy libraries load on demand: Chart.js only on /admin dashboard; image cropper/uploader only in admin forms; DOMPurify only where rich HTML is rendered.
4. Small runtime: React 18 + React Router + TanStack Query is the default. If the initial-JS budget cannot be met, swap React for Preact via preact/compat (about 30 KB smaller, same code). Decide with a bundle measurement in Phase 0.
5. CSS: Tailwind with purge (only used classes shipped), tokens in CSS variables, critical CSS for the header/hero inlined, the rest loaded non-blocking. No Font Awesome, no unused CSS frameworks.
6. Fonts: self-host Inter as a variable WOFF2, Latin subset only, font-display: swap, preload the primary file; or fall back to the system font stack if the 60 KB font budget is at risk. No Google Fonts request.
7. Build: Vite production build with minification, tree-shaking, manualChunks for vendor splitting, ES2020 target, no source maps in production, Brotli + gzip pre-compressed assets, content-hashed filenames.
8. Prefetching: prefetch the product chunk and its API data on link hover/touch-start and when a product card enters the viewport; prefetch /cart and /checkout chunks after add-to-cart.
9. Third-party scripts: none on first load (no analytics, chat or pixel loaded before the page is interactive; if added later, load them on idle).

12.1.4 API and network

• Fewer, smaller requests: GET /home returns everything the home page needs in one call. List endpoints return card-sized payloads only (id, slug, name, brand, price, old price, primary image, in-stock flag), never full product objects or all variants. Full detail loads only on the product page.
• HTTP caching: ETag/Cache-Control on public endpoints (/home 5 min, /taxonomy 10 min, /products 60 s with stale-while-revalidate), replacing the file-based cache/*.cache. Server-side cache via APCu or file cache behind it.
• Compression and protocol: Brotli/gzip for JSON and static files, HTTP/2 or HTTP/3, Cache-Control: immutable (1 year) for hashed JS/CSS/fonts and for product images.
• CDN: serve the SPA and /uploads images through a CDN (Cloudflare is already implied by the X-Forwarded-Proto handling in .htaccess); enable image caching rules there.
• Client data layer: TanStack Query with sensible staleTime (catalog 60 s) so navigating back to the shop or product pages is instant, plus request de-duplication. Debounce live search (250 ms) and cancel in-flight requests.
• Pagination: shop grid uses per_page of 12-24 with numbered pages (or "Load more"); never load the whole catalog. Long admin tables paginate server-side.
• Database: indexes on all filter/sort paths (existing idx_related plus additions in 6.2); avoid N+1 (batch-fetch variants and images for a page of products, as product.php already does for related items); EXPLAIN review for shop, search, dashboard queries.
• Cart/wishlist UX: optimistic updates so buttons respond instantly and the server confirms in the background.

12.1.5 Rendering and perceived speed

• Skeleton screens for every data view (parity with the current renderSkeleton* helpers), sized like the real content to avoid layout shift.
• content-visibility: auto on below-the-fold sections; long lists use windowing only where needed (admin tables).
• Animations use transform/opacity only and respect prefers-reduced-motion.
• Theme: the pre-paint inline script in index.html must be under 1 KB and blocking-free; theme switching only swaps CSS variables (no re-render of the tree).

12.1.6 PWA caching (vite-plugin-pwa / Workbox)

• Precache the app shell (HTML, main JS/CSS, logo files, offline page) only; do not precache product images.
• Runtime caching: images use CacheFirst with expiry (≈ 60 days, max ≈ 200 entries); catalog API uses StaleWhileRevalidate; cart, checkout, account and admin APIs are NetworkOnly.
• The service worker updates in the background and shows a small "New version available, refresh" toast; it must never block first load.

12.1.7 Monitoring

• Lighthouse CI on every pull request (fails below budget); bundle-size report attached to each PR.
• Real-user monitoring of Core Web Vitals through the web-vitals library, sent to a lightweight /api/v1/vitals endpoint or a free analytics tool, loaded on idle.
• Quarterly review of the heaviest images and slowest queries.

12.2 SEO and social sharing (biggest risk of going SPA)

The current PHP site delivers full HTML to crawlers and to WhatsApp/Facebook link previews (og: tags, JSON-LD, sitemap.xml). A client-rendered SPA would lose this. Requirements:

• Crawler shim (recommended): an .htaccess rule detects crawler/preview user agents (Googlebot, facebookexternalhit, WhatsApp, Twitterbot, etc.) for /shop/*, /shop, / and routes them to a small PHP script that returns HTML with the correct <title>, description, canonical, Open Graph image and Product JSON-LD from the DB. Humans get the SPA.
• Dynamic sitemap.xml generated from active products/categories/brands; keep robots.txt.
• react-helmet-async for per-route titles/meta in the SPA.
• (Alternative if budget allows: pre-render with vite-plugin-ssr/Vike or a Node SSR layer; not assumed here.)

12.3 Reliability and operations

• Health endpoint /api/v1/health; structured error logging; slow-query log review.
• Daily DB backup + weekly restore drill; uploads backup.
• Feature flag for maintenance mode remains a site_settings toggle honored by both API and SPA.
• Environments: local, staging (separate Firebase project), production.

12.4 Compatibility

Last 2 versions of Chrome, Safari (iOS 15+), Firefox, Edge; Android Chrome 100+. Graceful degradation for Web Push on iOS Safari (PWA-installed only).

12.5 Environment variables

Frontend (web/.env): VITE_API_BASE, VITE_FIREBASE_API_KEY, VITE_FIREBASE_AUTH_DOMAIN, VITE_FIREBASE_PROJECT_ID, VITE_FIREBASE_APP_ID, VITE_VAPID_PUBLIC_KEY. Backend (api/.env): DB_HOST, DB_USER, DB_PASS, DB_NAME, FIREBASE_PROJECT_ID, FIREBASE_CREDENTIALS_PATH, SMTP_*, ADMIN_ACCESS_CODE, ADMIN_TOKEN_SECRET, NCM_API_TOKEN, NCM_WEBHOOK_SECRET, VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT, APP_ENV, APP_DEBUG, ALLOWED_ORIGINS.

13. Delivery plan

Rough estimate for 2 developers (1 frontend-leaning, 1 PHP/backend-leaning). Adjust after the discovery spike.

13.1 Cut-over plan

1. Stand up staging with a copy of production data and imported users.
2. Freeze admin writes for a short window; run migration 0002, user import, and smoke tests.
3. Switch DNS/.htaccess to the new build; keep the old PHP app in a read-only folder for rollback for 2 weeks.
4. Monitor errors, checkout completions, and email delivery for the first 72 hours.

14. Optional enhancements (P2, not in parity scope)

• Guest cart in localStorage, merged into the DB cart at login (removes the biggest conversion friction).
• Saved multiple addresses per user.
• Order status timeline and email/push on each status change.
• Product variant image mapping (image per color).
• CSV export for orders and the audit log.
• Native eSewa/Khalti verification API in place of screenshot review.

15. Testing and acceptance

Definition of done for launch: all P0/P1 acceptance tests green; no critical/high security findings; all secrets rotated; rollback rehearsed.

16. Risks

17. Open questions

1. Hosting target: shared cPanel, VPS, or a mix (static on CDN + PHP elsewhere)? This decides CORS, deployment and SEO shim details.
2. TypeScript: OK to use TypeScript (recommended) or JavaScript only?
3. Guest checkout / guest cart: keep "login required to add to cart" or promote the P2 guest cart to P1?
4. Firebase sign-in methods: email/password + Google only, or also phone (SMS) OTP, which is popular in Nepal?
5. Logos: are the four files in assets/img/ (grip, grip-dark, grip-icon, grip-icon-dark) the final ones, or will you supply new files? Can we get SVG or @2x versions?
6. Timezone storage: keep local +05:45 timestamps in DB (as now) or normalise to UTC?
7. Superadmin-only actions and whether admins can bypass maintenance mode.
8. Which order lifecycle actions are live in production (several are commented out in order_detail.php)?
9. Shipping values: real production shipping_cost and free_shipping_threshold settings.
10. Account deletion policy: what personal data must be erased vs retained for accounting?
11. Review eligibility: does a verified purchase require the order to be delivered?

Appendix A. Legacy file → new module map

Appendix B. Order lifecycle (reference)

online / whatsapp:   pending(unpaid) ─▶ processing ─▶ shipped ─▶ delivered
                          └─▶ cancelled (customer if pending; admin any time; stock restored)
online / prepaid:    pending(verifying) ─▶ [admin verify] ─▶ processing(paid) ─▶ shipped ─▶ delivered
                          └─ reject payment ─▶ failed ─▶ cancelled
paid + cancelled ─▶ payment_status = refunded
offline (in-store):  created by admin, payment_method instore, gateway cash/esewa/bank

[Confirm exact transitions against admin/orders.php and order_detail.php.]