# Billify Flow Polished static billing/invoice SaaS UI with GenMB authentication, billing/customer SDK hooks, and legacy local SMA billing modules present but mostly not routed. ## Masterplan - Provide a Billify-inspired SaaS workspace for invoices, clients, products, quotes, payments, reports, dashboards, settings, and pricing. - Run as a fully static browser app: no build step, no owned backend, no server runtime; dependencies and GenMB SDKs load from `index.html`. - Use GenMB Auth/Billing/Invoicing capabilities when available, while gracefully falling back to sample/demo data on pages that depend on cloud SDKs. - Preserve older SHREE MAHESHWARA AGENCIES local billing assets and utilities for print/PDF/WhatsApp/local-store workflows, but treat current routed app as the SaaS shell. - Keep generated database tables as cloud integration targets; current runtime is mostly SDK calls, React state, and legacy local store modules. ## Tech Stack & Architecture - Static entry point: `index.html` - Loads Tailwind via CDN. - Loads `styles/main.css`. - Injects GenMB capability SDKs. - Mounts React at `#root` through `src/main.js`. - React runs directly in the browser from ESM CDNs: - `react@19.2.0` - `react-dom@19.2.0/client?deps=react@19.2.0` - `react-router-dom@7.13.0?deps=react@19.2.0` - `lucide-react?deps=react@19.2.0` - `htm` for template syntax. - There is **no JSX transpilation/build step**. Components must import `html` from `src/jsx.js` and return HTM templates: - Correct: ``return html`

${value}

` `` - Do not add JSX like `

{value}

` unless a bundler is introduced. - CDN gotcha: keep `?deps=react@19.2.0` on `react-dom`, `react-router-dom`, and `lucide-react` imports to prevent duplicate React instances and invalid hook errors. - App boot: - `src/main.js` renders `html`<${Providers}><${App} />``. - `src/mainProviders.js` exposes `useAppContext()` with `user`, `loading`, `isAuthed`, `customer`, `systemMessage`, `setSystemMessage`, and `capabilitiesReady`. - Routing: - `src/App.js` uses `HashRouter`; keep hash routing for static hosting. - Current active shell is `Shell()` in `src/App.js`, which renders `src/components/Header.js` and an `Outlet`. - There is currently **no route guard** in `src/App.js`; signed-out users can view routed pages, but cloud write actions may fail. - Auth and capabilities: - `Providers` calls `window.genmb.auth.ready()` if available. - Subscribes via `window.genmb.auth.onAuthStateChange`. - Calls `ready()` for optional GenMB capabilities when present: `billing`, `invoicing`, `reports`, `dashboards`, `db`. - Billing customer state is read from `window.genmb.billing.getCustomer?.()` and `onCustomerChange?.()`. - Always feature-check `window.genmb` APIs before calling them. - Data/state: - Current routed SaaS pages use a mix of local React state and GenMB SDK calls. - Legacy operational SMA pages use `src/store/useBillingStore.js`, persisted in browser storage. - Do not assume the generated database tables are automatically wired to UI pages unless a specific GenMB SDK method exists. ## File Structure ```txt CLAUDE.md # Existing AI guidance; keep synchronized with this document. index.html # Static shell; Tailwind CDN, GenMB SDK injection, root mount. styles/main.css # Theme variables, cards, responsive nav, print/safe-area rules. src/main.js # React root; renders Providers + App. src/jsx.js # HTM binding; required because there is no JSX build step. src/mainProviders.js # AppContext; GenMB auth/capability readiness/customer state. src/App.js # HashRouter route table and active Shell layout. src/components/Header.js # Active sidebar/topbar/mobile nav; sign-in/sign-out buttons. src/components/AuthPanel.js # Full GenMB auth UI for Google, magic link, password, signup, reset; not globally routed by default. src/components/CompanyPrintHeader.js # Legacy SMA document header for print/PDF pages. src/components/EmptyState.js # Reusable empty-state card. src/components/StatCard.js # Reusable dashboard metric card. src/pages/Home.js # Main dashboard/landing workspace page. src/pages/Clients.js # Active cloud-oriented client list/create page using GenMB invoicing clients API. src/pages/Products.js # Active products page. src/pages/Invoices.js # Active invoices page. src/pages/Quotes.js # Active quotes page. src/pages/Payments.js # Active payments/billing page. src/pages/Reports.js # Active reports page. src/pages/Dashboards.js # Active dashboards/analytics page. src/pages/Settings.js # Active settings page. src/pages/Pricing.js # Active pricing/subscription page. src/pages/NotFound.js # 404 fallback. src/pages/Customers.js # Legacy SMA local party/customer + product entry page; currently not routed in App.js. src/pages/Items.js # Legacy local inventory/items page; currently not routed. src/pages/InvoiceEditor.js # Legacy local invoice editor; currently not routed. src/pages/InvoiceView.js # Legacy printable invoice view; currently not routed. src/pages/Quotations.js # Legacy local quotations page; currently not routed. src/pages/Estimates.js # Legacy local estimates page; currently not routed. src/pages/PurchaseOrders.js # Legacy local purchase orders page; currently not routed. src/pages/Expenses.js # Legacy local expenses page; currently not routed. src/pages/Ledger.js # Legacy local ledger page; currently not routed. src/pages/DataSync.js # Legacy/local cloud sync and backup UI; currently not routed. src/store/useBillingStore.js # Legacy browser-persisted billing store for customers/items/docs/settings. src/utils/cloudSync.js # Legacy GenMB/local backup-sync helpers. src/utils/companyPdf.js # Company PDF/print generation helpers. src/utils/format.js # Money/date/number formatting utilities. src/utils/whatsappPdf.js # WhatsApp sharing/PDF helper utilities. ``` ## Key Features ### Active routed SaaS workspace - `src/App.js` routes: - `/` → `Home` - `/clients` → `Clients` - `/products` → `Products` - `/invoices` → `Invoices` - `/quotes` → `Quotes` - `/payments` → `Payments` - `/reports` → `Reports` - `/dashboards` → `Dashboards` - `/settings` → `Settings` - `/pricing` → `Pricing` - `*` → `NotFound` - `src/components/Header.js` - Desktop: sticky left sidebar with all primary routes plus Pricing. - Mobile: fixed bottom nav showing only first five `navItems` (`Dashboard`, `Clients`, `Products`, `Invoices`, `Quotes`). - Uses `useAppContext()` for signed-in user display. - Calls `window.genmb.auth.signIn()` / `signOut()` only after checking `window.genmb?.auth`. ### Authentication - `src/mainProviders.js` is the global auth source. - `src/components/AuthPanel.js` supports: - Google sign-in: `window.genmb.auth.signIn()` - Magic link: `sendMagicLink(email)` - Password sign-in: `signInWithPassword(email, password)` - Signup + OTP verification: `signUp(email, password, name)`, `verifySignUp(email, code)` - Password reset: `requestPasswordReset(email)`, `confirmPasswordReset(email, code, newPassword)` - Sign out: `signOut()` - Current `App.js` does not mount `AuthPanel` as a dedicated route; add it to a page or route if full auth UX is needed beyond the header sign-in button. ### Clients cloud integration - `src/pages/Clients.js` - Loads clients with `window.genmb.invoicing.clients.list({ limit: 25 })`. - Creates clients with `window.genmb.invoicing.clients.create({ name, email, company, userId })`. - Falls back to hardcoded `sampleClients` and displays an explanatory message if API is unavailable. - Requires `app?.user?.id` for user ownership on create, but UI allows submission while signed out; failure message prompts sign-in. ### Legacy SMA local billing modules - Legacy pages (`Customers`, `Items`, `InvoiceEditor`, `InvoiceView`, `Quotations`, `Estimates`, `PurchaseOrders`, `Expenses`, `Ledger`, `DataSync`) are present but not included in the current route table. - These pages generally use `src/store/useBillingStore.js`. - They preserve Indian small-business billing behavior: parties/customers, GSTIN, HSN/SAC, units, stock, invoices/quotes/estimates, purchase orders, expenses, ledgers, settings, print/PDF, and WhatsApp sharing. - `src/components/CompanyPrintHeader.js` defaults to: - Business name: `SHREE MAHESHWARA AGENCIES` - Phone: `9489544470` - GSTIN from `settings.gstin` or `settings.taxId` - If re-enabling legacy routes, import the page into `src/App.js` and add a `` under `Shell`. ### Generated cloud data model targets Current generated tables/capabilities exist but are not necessarily fully wired to UI: - `billify_notes` - `userProfiles` - `businesses` - `businessAddresses` - `clients` - `clientAddresses` - `products` - `invoiceStatuses` - `invoices` - `invoiceItems` - `payments` - `subscriptionPlans` - `userSubscriptions` - `invoiceTemplates` - `webhookEvents` - `systemSettings` Enabled capabilities from the prompt/code environment: - `billing` - `search` - `auth` - `docs` - `email` Code also probes optional: - `invoicing` - `reports` - `dashboards` - `db` ## Design Guidelines - Visual style: polished SaaS billing dashboard with soft cards, rounded corners, subtle shadows, and glassy card backgrounds. - Styling is Tailwind utility classes plus project CSS variables from `styles/main.css`. - Components use CSS variable tokens heavily: - Colors: `hsl(var(--primary))`, `--foreground`, `--background`, `--card`, `--muted`, `--border`, `--secondary` - Radii: `--radius-sm`, `--radius-md`, `--radius-lg` - Shadows: `--shadow-sm`, `--shadow-md` - Motion: `--transition-fast` - Cards commonly use: - `rounded-[var(--radius-lg)]` - `border border-[hsl(var(--border))]` - `bg-[hsl(var(--card)/0.92)]` - `shadow-[var(--shadow-md)]` - Inputs/buttons should be touch-friendly: most active forms use `min-h-12`. - Responsive behavior: - Desktop uses a `lg:grid lg:grid-cols-[280px_1fr]` app shell. - Header/sidebar is sticky on desktop. - Mobile uses a fixed bottom nav and `pb-28` main padding to avoid overlap. - Use `safe-top` and `safe-bottom` classes where nav touches device safe areas. - Print/PDF: - Preserve `CompanyPrintHeader` centered layout and inline style fallbacks; print rendering often ignores some utility styling. ## App Flow ### First load 1. `index.html` loads SDKs/CSS and `src/main.js`. 2. `Providers` initializes GenMB auth and capability readiness. 3. `App` renders `HashRouter` and `Shell`. 4. `Header` shows signed-in user or a sign-in button. 5. User lands on `/` (`Home`). ### Sign in/out - Header sign-in calls `window.genmb.auth.signIn()`. - On auth state change, `mainProviders.js` updates `user` and `isAuthed`. - Header sign-out calls `window.genmb.auth.signOut()` and navigates to `/`. - Edge case: if GenMB Auth is absent, sign-in/sign-out handlers return silently; do not crash. ### Client management 1. User opens `#/clients`. 2. Page attempts `window.genmb.invoicing.clients.list`. 3. If unavailable, shows sample clients and a warning. 4. Add-client form attempts `window.genmb.invoicing.clients.create`. 5. On failure, shows “Client could not be saved. Please sign in and try again.” ### Navigation edge cases - Unknown hash routes render `src/pages/NotFound.js`. - Mobile nav intentionally exposes only five core routes; use desktop nav or direct URLs for reports/settings/pricing on small screens unless the mobile nav is expanded. - Current app is not protected; if a feature needs required auth, add checks in the page or implement a route wrapper in `src/App.js`. ## Conventions - Use named files and imports with `.js` extensions. - Use HTM templates everywhere: ```js import { html } from '../jsx.js'; export default function Example() { return html`

Hello

`; } ``` - React hooks must be called inside function components or custom hooks only; CDN duplicate React versions will break hooks. - Use `useAppContext()` for global auth/capability/customer state. - Feature-check GenMB SDKs: ```js if (!window.genmb?.invoicing?.clients?.list) { // fallback } ``` - Prefer graceful degradation: - Show sample data/read-only UI if cloud APIs are unavailable. - Show user-facing messages instead of throwing uncaught errors. - Component naming: - Components/pages are PascalCase: `Clients`, `AuthPanel`, `StatCard`. - Utilities are camelCase exports from `src/utils/*`. - Styling approach: - Prefer Tailwind utilities and existing CSS variables. - Reuse established card/input/button class patterns instead of introducing separate CSS files. - Adding a new active page: 1. Create `src/pages/NewPage.js`. 2. Import it in `src/App.js`. 3. Add a ``} />`. 4. Add nav metadata to `navItems` in `src/components/Header.js` if it should appear in navigation. 5. If mobile access is required, remember mobile nav currently renders only `navItems.slice(0, 5)`. - Re-enabling legacy SMA pages: - Import the page into `src/App.js`. - Add routes deliberately; do not assume all legacy pages are production-ready in the SaaS flow. - Verify compatibility with `useBillingStore.js`, print/PDF helpers, and current CSS before exposing to users. - Updating auth: - `mainProviders.js` is the single global auth context. - `AuthPanel.js` is a reusable UI panel, not the context owner. - Avoid adding a second auth provider or separate user state source. ## 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.