# Luma Market A CDN-only React home-goods storefront with persistent cart, GenMB/Stripe checkout hooks, customer order history, and admin reporting screens. ## Masterplan - Provide a polished static ecommerce demo that deploys on simple static hosting with no build step, no JSX transform, and hash-based routing. - Let shoppers browse curated home goods, persist a cart locally, authenticate with GenMB, and begin checkout when GenMB billing/Stripe is available. - Keep customer order history, staff order management, and owner dashboard/reporting views in the same browser app. - Remain useful without live GenMB services by using seeded products/orders and `localStorage` persistence. - Preserve portability: browser modules only, CDN imports only, no Node/package-managed frontend dependencies. ## Tech Stack & Architecture - **Static shell:** `index.html` loads Tailwind via CDN, `styles/main.css`, GenMB capability SDKs on `window.genmb`, then the module entry. Do not add Vite/Webpack/npm frontend dependencies. - **React:** `src/main.js` imports `react-dom@19.2.0/client` from `esm.sh` and renders `` into `#root`. - **No JSX:** All UI uses `html` from `src/jsx.js`, which binds `htm` to React `createElement`. ```js return html`<${Button} onClick=${save}>Save`; ``` Never write JSX syntax in `src/**/*.js`. - **Routing:** `src/App.js` uses `HashRouter`, `Routes`, `Route` from `react-router-dom@7.13.0?deps=react@19.2.0`. Routes are `/`, `/products`, `/cart`, `/orders`, `/admin`, `/dashboards`, `/auth`, and `*`. - **Layout:** All routes render inside `src/components/Layout.js`, which includes `Header`, ``, and a fixed six-item mobile bottom nav. - **Icons/CDNs:** Icons come from `lucide-react` via `https://esm.sh/lucide-react?deps=react@19.2.0`. Always include `?deps=react@19.2.0` on React-dependent CDN imports to avoid duplicate React instances. - **Provider order:** `src/mainProviders.js` wraps `ThemeProvider → ToastProvider → AuthProvider → BillingProvider`. Keep this order unless dependencies change. - **State:** - Cart: Zustand store in `src/store/useCartStore.js`, persisted to `localStorage["luma-cart-v1"]`. - Theme: `src/context/ThemeContext.js`, persisted to `localStorage["luma-theme"]`, toggles `.dark` on ``. - Toasts: `src/context/ToastContext.js`, fixed top-right, success/error, 4.2s auto-dismiss. - Auth: `src/context/AuthContext.js`, waits for `window.genmb.auth.ready()`, reads `getUser()`, subscribes with `onAuthStateChange`. - Billing: `src/context/BillingContext.js`, waits for `window.genmb.billing.ready()`, reads/subscribes to customer state. - Orders: `src/data/orders.js` merges seeded demo orders with `localStorage["luma-orders-v1"]`. - **Backend/function:** `functions/sendFormEmail.ts` is the only server-side code. It validates/sanitizes form payloads and sends email through Resend. No custom server API currently exists beyond this function. - **Enabled GenMB capabilities:** auth, billing/Stripe, products, commerce, relational-db, admin-table, dashboards, reports, functions, email, file-storage. The current frontend mostly uses injected auth/billing and local seeded data. ## File Structure ```text index.html Static shell; Tailwind CDN, GenMB SDK injection, #root, app module loading. styles/main.css Global tokens, dark mode variables, shadows, safe-area/mobile spacing, product/hero visuals. functions/sendFormEmail.ts Resend email function; validates name/email/message, escapes HTML, sends text+HTML email. src/main.js Browser entrypoint; renders Providers + App. src/jsx.js htm binding; required JSX replacement for all browser UI modules. src/mainProviders.js Global provider composition: theme, toast, auth, billing. src/App.js HashRouter route table under shared Layout. src/components/Layout.js Page shell, Header, Outlet, mobile bottom nav. src/components/Header.js Logo, desktop nav, theme toggle, cart badge, auth/account link. src/components/Button.js Shared button variants: primary, secondary, ghost, destructive; loading spinner. src/components/ProductCard.js Product tile with image fallback, stock/rating display, Add button. src/context/ThemeContext.js Light/dark state and localStorage persistence. src/context/ToastContext.js Toast queue and renderer. src/context/AuthContext.js GenMB auth integration and auth state. src/context/BillingContext.js GenMB billing/customer readiness state. src/store/useCartStore.js Zustand cart store with localStorage persistence. src/data/products.js Seed product catalog used by product/home/cart flows. src/data/orders.js Seed + stored order helpers: create, update, remove, list. src/pages/Home.js Storefront landing page and merchandising entry points. src/pages/Products.js Product browsing/catalog grid and add-to-cart actions. src/pages/Cart.js Cart quantity management, totals, checkout/order creation. src/pages/Orders.js Customer-facing order history/status view. src/pages/Admin.js Staff order dashboard/list controls backed by local order helpers. src/pages/Dashboards.js Owner metrics/reporting visualizations from order/product data. src/pages/Auth.js Sign-in/account surface for GenMB auth actions. src/pages/NotFound.js 404 route with return-home link. ``` ## Key Features - **Product browsing** - Catalog is seeded in `src/data/products.js`. - Product shape currently includes: `id`, `name`, `category`, `price`, `inventory`, `rating`, `description`, `initials`, `imageUrl`, `images`. - `src/components/ProductCard.js` accepts product variants from seed or capability-style data: supports `stock`/`inventory`, `rating`/`ratingAverage`, `imageUrl`/`thumbnailUrl`/`images`. - Image fallback order: first `images[]`, `imageUrl`, `thumbnailUrl`, category image, initials badge. - **Cart** - `src/store/useCartStore.js` stores only `{ id, name, price, quantity }`; do not assume image/category are present in cart items. - Actions: `add(product)`, `decrement(id)`, `remove(id)`, `clear()`. - Persistence is manual: every mutating action writes `localStorage["luma-cart-v1"]`. - **Checkout / orders** - Cart checkout should prefer GenMB billing/commerce if available, but must continue working as a demo by creating a pending local order with `createPendingOrder()` in `src/data/orders.js`. - Local pending orders have status `awaiting payment` and paymentStatus `pending`. - Seed orders are included in `getAllOrders()` unless shadowed by stored orders with the same id. - `updateOrder(id, patch)` can update seeded orders by copying patched versions into localStorage. - `removeOrder(id)` only removes stored orders; seeded orders reappear unless first updated/stored and then removed logic is extended. - **Authentication** - `src/context/AuthContext.js` gracefully handles missing `window.genmb.auth`; `loading` becomes false and `user` stays null. - `signOut()` assumes `window.genmb.auth` exists; guard call sites if adding unauthenticated/offline sign-out controls. - User shape from SDK: `{ id, email, name, picture }`. - **Admin and dashboards** - `src/pages/Admin.js` should manage/order-filter against `getAllOrders()`, `updateOrder()`, and `removeOrder()`. - `src/pages/Dashboards.js` should derive demo KPIs/charts from seeded products and orders rather than requiring live reports. - Database tables available when GenMB relational DB/admin capabilities are wired: `productCategories`, `products`, `productImages`, `customers`, `addresses`, `orders`, `orderItems`, `payments`, `shipments`, `adminUsers`, `adminOrderViews`, `ownerReports`, `dashboards`, `dashboardWidgets`. - **Email function API** - File: `functions/sendFormEmail.ts`. - Request body fields: `name`, `email`, `message` required; optional `source`, `topic`, `pageUrl`. - Responses: - `200`: `{ ok: true, id: string|null, sent: true }` - `400`: missing/invalid input - `500`: missing Resend config or unexpected error - Resend non-OK status is passed through with `{ ok: false, message }` - Required env/secrets: `RESEND_API_KEY`, `RESEND_TO_EMAIL`; optional `RESEND_FROM_EMAIL`. ## Design Guidelines - Visual system is token-driven in `styles/main.css` using HSL CSS variables such as `--background`, `--foreground`, `--card`, `--primary`, `--secondary`, `--accent`, `--destructive`, `--ring`, and semantic status tokens. - Use Tailwind utility classes with token references: `bg-[hsl(var(--card))]`, `text-[hsl(var(--muted-foreground))]`, `shadow-[var(--shadow-sm)]`. - Primary brand feel: warm, minimal, editorial home-goods marketplace; rounded cards, soft shadows, subtle hover lift. - Dark mode is class-based via `.dark` on `document.documentElement`; never use Tailwind’s media dark mode assumptions. - Buttons are minimum 44px high (`min-h-11`) for touch accessibility. - Mobile navigation is fixed bottom and uses `env(safe-area-inset-bottom)`; main content gets `safe-bottom` spacing. - Responsive pattern: desktop header nav appears at `md`, mobile bottom nav is hidden at `md`. ## App Flow - **Browse to cart:** User lands on `/`, goes to `/products`, taps Add on `ProductCard`, cart badge in `Header` updates from Zustand state. - **Edit cart:** `/cart` lets the user increment/add, decrement, remove, or clear items. Totals should be derived from `items.reduce(price * quantity)`. - **Checkout:** If signed in and GenMB billing is ready, initiate billing/checkout integration where available. Otherwise create a local pending order via `createPendingOrder()`, show a toast, and preserve demo continuity. - **Auth:** `/auth` exposes account/sign-in state using `useAuth()`. Missing GenMB auth must be presented as unavailable/demo mode, not as a crash. - **Customer orders:** `/orders` reads `getAllOrders()` and can filter to the current user email when appropriate; demo orders are visible for showcasing. - **Admin:** `/admin` is a staff-facing order management view. It can update order/payment/status fields locally; remember patched seed orders are persisted as stored overrides. - **Dashboards:** `/dashboards` shows owner-style metrics from local products/orders. It should not require live dashboard/report capability to render. - **404:** Unknown hash route renders `src/pages/NotFound.js`. ## Conventions - Use named exports for components and hooks: `export function Products() {}`. - Keep all browser imports as full CDN ESM URLs or relative local paths. For React-dependent CDN packages, pin React with `?deps=react@19.2.0`. - Use `html` tagged templates for all components. Component tags must use interpolation: `<${Component} />`; intrinsic tags stay literal: `

`. - Prefer small page-local helper functions for formatting totals, dates, and statuses. Shared logic belongs in `src/data/*`, `src/store/*`, or context files. - Styling is Tailwind utilities plus CSS variables from `styles/main.css`; do not add CSS-in-JS or component CSS files. - Add a new page by: 1. Creating `src/pages/NewPage.js` with `html` templates. 2. Importing it in `src/App.js` and adding a ``. 3. Adding navigation in `src/components/Header.js` and/or `src/components/Layout.js` only if it is a top-level destination. - Add a new capability integration behind existence checks, e.g. `if (!window.genmb?.commerce)`, and keep seeded/localStorage fallback behavior. - Avoid changing localStorage keys (`luma-cart-v1`, `luma-orders-v1`, `luma-theme`) unless adding migration logic. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.