# VoxCart AI Voice Order Desk A multilingual, browser-based AI order assistant that guides customers through product selection, shipping, address verification, checkout, and order confirmation. ## Masterplan - Help e-commerce customers complete an order conversationally in English, Indonesian, or Spanish. - Combine a structured checkout workspace with a voice/text assistant so customers can self-serve without losing clarity or order accuracy. - Support configurable agent identity and speaking rate for a more branded, approachable ordering experience. - Prevent fulfillment errors by requiring validated shipping addresses before payment. - Increase order value through catalog add-ons and the `WELCOME10` discount flow. ## Tech Stack & Architecture - **React + TypeScript + Vite** entrypoint: `src/main.tsx`; build configuration: `vite.config.ts`. - **Routing:** `react-router-dom` with `HashRouter` in `src/App.tsx`. Routes are hash-based so deployed static hosting does not need server-side route rewrites. - **Styling:** Tailwind-style utility classes plus design tokens/custom global CSS in `src/styles/main.css`. Use `cn()` from `src/lib/utils.ts` for conditional classes. - **Icons:** `lucide-react`. - **Accessible modal:** `@radix-ui/react-dialog` in `src/components/PolicyDialog.tsx`. - **Internationalization:** custom `LanguageProvider` / `useLanguage` from `src/i18n.tsx`, backed by: - `src/locales/en.json` - `src/locales/id.json` - `src/locales/es.json` - **App state:** `AgentProvider` in `src/context/AgentContext.tsx` owns order state, agent settings, messages, totals, draft persistence, and rule-based conversational responses. Components consume it through `useAgent()`. - **Capability integrations exposed globally:** - `window.genmb.address` for address autocomplete, validation, and formatting. - `window.genmb.billing` for hosted payment checkout. - Browser Web Speech APIs for recognition and speech synthesis. - **No custom backend/API exists.** The app is a client-side checkout shell; payment and address requests are delegated to injected GenMB SDKs. Provider nesting is intentional in `src/App.tsx`: ```tsx ... ``` Keep stateful feature components inside these providers. ## File Structure ```text index.html # HTML shell; injected GenMB billing/address capability SDKs. src/main.tsx # React bootstrap; imports global styles. src/App.tsx # Hash routes and root provider composition. src/types.ts # Shared Order, Address, Product, Message, Settings, and language types. src/i18n.tsx # Translation provider, language selection, t() helper. src/styles/main.css # Global CSS variables, base styling, animations, Tailwind layer setup. src/data/catalog.ts # Fixed product/add-on catalog and pricing source of truth. src/context/AgentContext.tsx # Central order/agent state, calculations, draft persistence, chat behavior. src/lib/utils.ts # cn() class merger and locale-aware formatCurrency(). src/hooks/usePageMeta.ts # Page title/metadata helper used by pages. src/components/AppShell.tsx # Header, responsive navigation, language selector, route outlet, footer. src/components/LanguageSelect.tsx # Global EN/ID/ES selector. src/components/VoiceConsole.tsx # Text chat, speech recognition, speech synthesis, conversation shortcuts. src/components/OrderWorkspace.tsx # Product, quantity, shipping, discount, add-ons, special request, drafts. src/components/AddressCard.tsx # Address form plus GenMB autocomplete/validation flow. src/components/OrderSummary.tsx # Live totals, copy review, policies, and GenMB checkout trigger. src/components/PolicyDialog.tsx # Shipping/returns modal. src/components/ui/Button.tsx # Shared accessible button variants and loading state. src/components/ui/TextField.tsx # Shared labeled input with hint/error semantics. src/components/ui/ToastProvider.tsx# Global toast context and notification UI. src/pages/OrderPage.tsx # Main ordering workspace composition. src/pages/SettingsPage.tsx # Voice agent name/personality/rate configuration. src/pages/ConfirmationPage.tsx # Post-checkout confirmation route. src/locales/en.json # English copy. src/locales/id.json # Indonesian copy. src/locales/es.json # Spanish copy. ``` ## Key Features ### Multilingual order desk - The global language selector supports `en`, `id`, and `es`. - All visible application copy must use `t('key')`; do not hardcode user-facing strings in components. - Currency formatting uses `formatCurrency(value, language)` from `src/lib/utils.ts`. - Browser speech recognition and synthesis map languages to `en-US`, `id-ID`, and `es-ES`. ### Voice and text assistant - `src/components/VoiceConsole.tsx` displays the shared conversation held in `AgentContext`. - Customers may: - Type a message. - Use product/shipping/return quick prompts. - Start browser speech recognition. - Play or stop the latest assistant reply through speech synthesis. - Recognition is progressive enhancement only. Unsupported browsers must show the existing localized `voice.unsupported` error rather than blocking ordering. - Agent replies currently come from client-side `submitMessage()` logic, not an LLM endpoint. Do not imply live AI inference or external model calls unless one is actually added. - Voice settings are shared through context and configured on `/settings`. ### Structured order builder The order state includes: - `productId` - `quantity` - `shipping`: `standard` or `express` - `addonIds` - `discountCode` - `specialRequest` - `address` - `addressVerified` Catalog products and upsell add-ons are static and must be defined in `src/data/catalog.ts`; UI labels are translation keys, not catalog literals. Pricing is derived in context and surfaced in `OrderSummary`: - `subtotal` - `discountAmount` - `shippingCost` - `total` Discount behavior is deliberately limited: - `WELCOME10` is the recognized code. - Invalid codes show localized feedback and do not create a discount. - Preserve this behavior in context/calculation logic when changing pricing. ### Address verification `src/components/AddressCard.tsx`: - Performs basic required-field validation locally. - Requests autocomplete after address-line blur when at least four characters are entered. - Calls `window.genmb.address.validate(order.address)` when the customer chooses validation. - Only a successful validation normalizes the address and sets `addressVerified: true`. - Checkout is blocked until `addressVerified` is true. - Suggestions are currently applied as `line1` text only; they do not independently guarantee verification. Treat GenMB Address SDK absence or errors as recoverable UI errors. Never mark an address verified after an SDK failure. ### Hosted checkout `src/components/OrderSummary.tsx` calls: ```ts window.genmb.billing.checkout({ amount: Number(total.toFixed(2)), currency: 'usd', productName: `${t(product.titleKey)} order`, successUrl: `${origin}${pathname}#/order-confirmed`, cancelUrl: `${origin}${pathname}#/`, metadata: { product, quantity, shipping, discount }, }) ``` Requirements and gotchas: - Amounts are in major USD units, not cents. - Call `window.genmb.billing.ready?.()` before checkout. - Preserve hash URLs for success and cancellation. - Handle `CONNECT_REQUIRED` and `NETWORK_ERROR` with the existing localized messages. - Do not collect card details in React; GenMB owns payment collection. - Current checkout metadata is lightweight and client-originated. There is no server-side order persistence or payment-webhook verification. ### Drafts, reset, copy, and policies - `saveDraft()` and `resetOrder()` are context operations used by `OrderWorkspace`. - Notifications must use `useToast()` rather than ad hoc alerts. - `OrderSummary` can copy a localized order review via `navigator.clipboard`. - `PolicyDialog` presents the localized shipping and returns policy. ## Design Guidelines - **Style:** clean operational checkout dashboard; warm, trustworthy, compact cards with rounded corners, light borders, soft shadows, and Lucide icons. - **Tokens:** use semantic utility classes already used across the app: `bg-background`, `bg-card`, `text-foreground`, `text-muted-foreground`, `bg-primary`, `bg-accent`, `bg-destructive`, and `ring-ring`. Do not introduce raw colors where tokens exist. - **Typography:** system sans-serif styling from `src/styles/main.css`; headings use bold, tight tracking; body copy favors readable `text-sm` with `leading-6`. - **Interaction:** buttons/cards use small translate/shadow hover feedback and `active:scale-[0.98]`. Preserve visible keyboard focus rings. - **Responsive layout:** shell max width is `max-w-7xl`; desktop navigation appears at `md`, while mobile navigation moves below the header. Form grids collapse to one column on smaller screens. - **Accessibility:** retain semantic labels, `aria-live` conversation updates, error `role="alert"`, descriptive modal labeling, and icon `aria-hidden` usage. ## App Flow 1. Customer opens `#/` and sees the order workspace, voice console, address card, and summary. 2. Customer optionally changes language; this changes UI copy and speech locale, not catalog currency. 3. Customer selects a product, quantity, shipping method, optional add-ons, discount code, and special request. 4. Customer can ask the assistant about products, delivery, and returns through text or supported speech input. 5. Customer enters delivery details, reviews suggestions, then validates the address. 6. Customer reviews live totals and may copy the order review or inspect policies. 7. Checkout remains unavailable logically until quantity is valid and `addressVerified` is true. 8. The checkout button opens GenMB hosted billing. Success returns to `#/order-confirmed`; cancellation returns to `#/`. 9. `/settings` lets the customer configure voice-agent presentation; it does not configure an external AI provider. Key edge cases: - A blank/invalid quantity is rejected at checkout and on quantity blur. - Address SDK or billing SDK absence should show localized error feedback. - Speech features can fail due to browser support, permissions, or synthesis failure; text ordering remains available. - The confirmation page is route-based and is not proof of a server-verified order. ## Conventions - Use PascalCase React component filenames and exports: `OrderSummary.tsx`, `VoiceConsole.tsx`. - Use camelCase for functions, state, and context methods: `handleCheckout`, `updateAddress`, `addressVerified`. - Keep shared domain types in `src/types.ts`; do not duplicate shapes locally except narrow UI-only types. - Keep catalog/pricing inputs in `src/data/catalog.ts`; derive totals in `AgentContext`, not individual components. - Use `useAgent()` for shared order, settings, messages, and mutations. Components should render state and invoke context actions rather than maintain shadow order state. - Use `Button` and `TextField` from `src/components/ui/` for standard controls to retain consistent focus, loading, and validation behavior. - Add all new visible copy to all three locale JSON files. Use stable namespaced keys such as `summary.*`, `voice.*`, or `settings.*`. - Use `cn()` for conditional class strings; preserve semantic design tokens and responsive utility patterns. - Add a page by creating `src/pages/NewPage.tsx`, registering its route in `src/App.tsx`, and adding navigation in `src/components/AppShell.tsx` only when it is a primary destination. - Add an order feature by updating, in order: `src/types.ts`, `AgentContext.tsx`, relevant translations, and the consuming UI. Update the summary and checkout metadata if the feature affects fulfillment or price. ## 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.

Multilingual Order Voice Agent