# Mzeru Pay Polished mobile-first static web app for buying Malawi study notes, paying from a simulated Mzeru Wallet, generating `ORDER-MZERU-*` / `PAYREF-MW-*` references, unlocking notes with admin tokens, and tracking PDF access. ## Masterplan - Help Malawi learners and guardians browse MSCE, JCE, and Primary study notes with transparent page-count pricing. - Provide a native-feeling commerce experience in a static web app: splash screen, mobile shell, bottom tabs, cart, wallet, orders, and theme switching. - Simulate realistic local payment flow with Airtel Money/TNM Mpamba instructions, wallet-backed checkout, generated order/payment references, and single-use unlock tokens. - Support lightweight deployment anywhere: CDN dependencies, hash routing, persisted browser state, no build pipeline. - Include optional GenMB authentication for Google sign-in and email magic links without making browsing or checkout depend on auth. ## Tech Stack & Architecture - **Runtime:** Static browser app served from `index.html`; no bundler or build step. - **React:** React `19.2.0` and ReactDOM from `esm.sh`. - **Templating:** HTM, not JSX. `src/jsx.js` exports `html = htm.bind(React.createElement)`. - All components must return ``html`...` `` templates. - Do not add raw JSX unless a build step is introduced. - **Routing:** `react-router-dom@7.13.0` with `HashRouter` in `src/App.js`. - `/` renders `SplashScreen`. - `/home`, `/market`, `/cart`, `/orders`, `/wallet` are nested under `Layout`. - `*` renders `NotFound`. - Hash routing is intentional for static hosting. - **State:** Zustand store in `src/store/useShopStore.js`. - Persists cart, orders, wallet balance, and token/unlock-related state to `localStorage`. - Checkout is client-only and deducts from simulated wallet balance. - Store exports constants used by UI, including `PAYMENT_NUMBER` and `ADMIN_NUMBER`. - **Theme:** `ThemeProvider` in `src/mainProviders.js`. - Persists `dark`/`light` to `localStorage` key `mzeru-theme`. - Toggles `.dark` on `document.documentElement`. - `Header` consumes `useTheme()` for the sun/moon toggle. - **Auth:** GenMB auth SDK is injected in `index.html`. - `AuthProvider` in `src/mainProviders.js` wraps the SDK as `useAuth()`. - Supports `signIn()`, `signOut()`, and `sendMagicLink(email)`. - Auth state appears in `Header`; app remains usable if `window.genmb.auth` is unavailable. - **Styling:** Tailwind CDN plus app-specific CSS in `styles/main.css`. - Uses CSS variables: `--primary`, `--primary-foreground`, `--secondary`, `--background`, `--foreground`, `--card`, `--border`, `--muted`, `--muted-foreground`, `--accent`, `--destructive`, radii, and shadows. - Important custom classes: `native-shell`, `glass`, `slide-up`, `safe-bottom`, `no-scrollbar`, and splash/animation helpers. - **Icons:** `lucide-react` from `esm.sh`. - **Formatting:** `src/utils/format.js` provides `money(value)` and `shortDate(value)` using `en-MW`. ## File Structure ```text index.html # Static entry; Tailwind CDN, styles/main.css, GenMB auth SDK, and src/main.js module. CLAUDE.md # Existing project-agent instructions; keep aligned with this document. styles/main.css # Theme tokens, native mobile shell, glass UI, safe-area padding, animations, scrollbar helpers. src/main.js # React root creation; renders . src/jsx.js # HTM binding; required import for component templates. src/mainProviders.js # ThemeProvider, AuthProvider, useTheme(), useAuth(), provider composition. src/App.js # HashRouter route table and Layout nesting. src/components/Layout.js # Mobile app frame with sticky Header, routed Outlet, fixed BottomNav. src/components/Header.js # App title, wallet balance, auth controls, theme toggle, notification button. src/components/BottomNav.js # Five-tab nav and cart quantity badge from store. src/components/ProductCard.js # Note card UI and add-to-cart action. src/data/products.js # Subjects, levels, page-pricing, note catalog, seeded recent orders. src/store/useShopStore.js # Zustand cart/order/wallet/token store, checkout/ref generation, token unlock logic. src/utils/format.js # MWK currency and compact date formatting helpers. src/pages/SplashScreen.js # Initial animated splash; redirects into main app. src/pages/Home.js # Hero, trust cards, subjects rail, popular notes, recent seeded orders. src/pages/Market.js # Search, level filters, subject shortcuts, ProductCard list. src/pages/Cart.js # Cart editing, payment method selection, wallet checkout, unlock token entry. src/pages/Orders.js # Displays persisted orders plus seeded recent order context/statuses. src/pages/Wallet.js # Wallet balance and local payment/top-up style controls/history. src/pages/NotFound.js # Branded fallback for unknown hash routes. ``` ## Key Features ### Catalog and pricing - Source of truth is `src/data/products.js`. - `subjects` contains Malawi school subject metadata with emoji icons and colors. - `levels` are `MSCE`, `JCE`, and `Primary`. - `calculateNotePrice(pages)` defines page-tier pricing: - `<=20`: MWK 1,000 - `<=40`: MWK 1,200 - `<=60`: MWK 1,500 - `<=80`: MWK 1,800 - `<=100`: MWK 2,200 - `<=120`: MWK 2,700 - `>120`: MWK 3,000 - `products` are study note objects with: - `id`, `subject_id`, `level`, `name/title`, `category`, `pages`, `price`, `unit`, `emoji`, `seller`, `eta` - social proof fields: `rating`, `stock`, `downloads` - learning content: `chapters`, `preview`, `description` ### Market browsing - `src/pages/Market.js` supports: - text search across name, category, level, description, and chapters - level filter pills: `All`, `MSCE`, `JCE`, `Primary` - subject shortcut grid from the first six subjects - Product display is delegated to `ProductCard`. - Empty results show a friendly no-match state. ### Cart and checkout - `src/components/ProductCard.js` adds full product objects to the cart through `useShopStore().addToCart`. - `src/pages/Cart.js` supports: - quantity increment/decrement - item removal - payment method selection: `Airtel Money` or `TNM Mpamba` - checkout only when cart is non-empty and `walletBalance >= total` - navigation to `/orders` after successful checkout - Checkout creates an order locally, empties cart, deducts wallet balance, and generates realistic references in `src/store/useShopStore.js`. - Reference formats must remain: - order: `ORDER-MZERU-{year}-{digits}` - payment: `PAYREF-MW-{digits}` ### Admin unlock token flow - `Cart.js` imports `unlockWithToken` from `src/store/useShopStore.js`. - User-facing copy says payment is sent to `PAYMENT_NUMBER`; `ADMIN_NUMBER` verifies and sends a single-use token. - Token input placeholder is `2026 - 2040`. - Valid unlock tokens should stay aligned with the year-like token range from the original product spec. - Unlock behavior should return `{ ok, message }` so `Cart.js` can display feedback and clear the token on success. ### Orders - `src/data/products.js` includes `recentOrders` seed data for realism. - `src/pages/Orders.js` should merge or present persisted store orders alongside seeded examples. - Order rows/cards should show order ID, status, total, delivery/PDF access route, and `PAYREF-MW-*` ref where available. - This is a notes/PDF delivery app now; avoid reverting copy to physical groceries unless intentionally changing product direction. ### Wallet - `walletBalance` is shown in `Header` and used by `Cart`. - Initial simulated balance is expected to be high enough for demo purchases. - `Wallet.js` should treat wallet activity as local/demo state unless a real backend is added. ### Authentication - `Header.js` is the only visible auth UI: - if signed out: Google button and email magic-link form - if signed in: signed-in label and logout button - `AuthProvider` must gracefully degrade when `window.genmb.auth` is absent. - Do not gate catalog, cart, checkout, or orders behind auth unless explicitly requested. ## Design Guidelines - Mobile-first, app-shell feel with max-width native frame via `native-shell`. - Bottom navigation is fixed, glassy, and constrained to `max-w-[460px]`. - Header is sticky and glass-styled; bottom nav uses `safe-bottom` for mobile safe-area spacing. - Visual language: - rounded cards using `var(--radius-md/lg)` - soft borders with `hsl(var(--border))` - dark mode default unless `mzeru-theme` is `light` - primary action color from `hsl(var(--primary))` - destructive states from `hsl(var(--destructive))` - Typography is Tailwind utility-based with heavy headings (`font-black`) and compact supporting text. - Product and order UI should remain dense but thumb-friendly: large tap targets, rounded buttons, clear hierarchy. - Keep horizontal scrollers hidden with `no-scrollbar` for subject and featured rails. - Avoid adding external CSS frameworks beyond Tailwind CDN and `styles/main.css`. ## App Flow 1. **Launch** - User lands on `/#/`. - `SplashScreen` shows branded loading animation, then redirects to `/home`. 2. **Browse** - `/home` introduces the product, shows trust cards, subject rail, popular notes, and recent note orders. - User taps “Browse notes” or bottom nav “Market”. 3. **Search and add** - `/market` filters notes by keyword and level. - User taps “Add” on `ProductCard`. - Bottom nav cart badge updates from total cart quantity. 4. **Checkout** - `/cart` shows selected notes, quantities, total, payment method, and wallet validation. - If wallet is insufficient, buy button is disabled and warning text appears. - On successful checkout, store creates order/payment refs, deducts wallet, clears cart, and navigates to `/orders`. 5. **Unlock token alternative** - User pays externally to `PAYMENT_NUMBER`. - Admin at `ADMIN_NUMBER` verifies and sends token. - User enters token in cart; `unlockWithToken(token, cartProductIds)` validates and returns message. 6. **Track** - `/orders` shows local order history and seeded examples with statuses such as “Payment confirmed” or “Downloaded”. - PDF access is represented as instant/local status, not a real file download. 7. **Wallet and auth** - `/wallet` manages/reviews simulated wallet balance. - Header auth can sign in with Google or magic link but does not change commerce flow. ### Edge cases - Unknown hash route uses `NotFound` with a link back to `/home`. - Empty cart shows empty-state card. - Empty market search shows no-results card. - Auth SDK missing should only stop auth UI actions, not app rendering. - Store persistence means test data can survive refresh; clear the relevant localStorage keys when debugging. ## Conventions - **Components:** Default-export function components. Import `html` from `../jsx.js` or `./jsx.js`. - **Templates:** Use HTM syntax: - Components: `<${Component} prop=${value} />` - Dynamic classes: `className=${condition ? '...' : '...'}` - Lists must include stable `key`. - **Imports:** CDN imports should include React dependency pins where already used, e.g. `?deps=react@19.2.0`. - **State access:** Select only needed Zustand slices: - good: `useShopStore((s) => s.walletBalance)` - avoid subscribing to the whole store in large components. - **Styling:** Prefer Tailwind utilities plus existing CSS variables. Do not hardcode many one-off colors when a CSS token exists. - **Data changes:** Add or edit catalog items in `src/data/products.js`; keep product fields compatible with `ProductCard`, `Market`, `Cart`, and order generation. - **Adding a page:** 1. Create `src/pages/NewPage.js` using HTM. 2. Add a `` under `Layout` in `src/App.js`. 3. If it is a primary tab, add an item to `items` in `src/components/BottomNav.js`. 4. Ensure bottom padding remains adequate because nav is fixed. - **Adding store behavior:** Extend `src/store/useShopStore.js` actions and persisted state carefully; avoid renaming persisted keys unless migration/clear behavior is intentional. - **Backend/API:** There is no app backend. The only external API surface is the injected GenMB auth SDK in `index.html`; commerce, wallet, orders, and unlocks are local browser simulations. ## 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.