# PulseForge Analytics Responsive authenticated SaaS analytics dashboard for subscription revenue, retention, acquisition, account-health monitoring, and workspace preferences. ## Masterplan - Provide SaaS operators, revenue leaders, and customer-success teams a secure command center for MRR, active workspaces, churn, NPS, acquisition, retention, plans, regions, and priority accounts. - Prioritize fast executive scanning through KPI cards, mixed Chart.js visualizations, image-backed insight sections, and a compact paginated account table. - Gate all dashboard routes behind GenMB authentication: Google, password login, magic link, OTP signup verification, and password reset. - Deliver a responsive dashboard shell with desktop collapsible sidebar, sticky header, mobile bottom nav, safe-area spacing, and persisted dark mode. - Current implementation is static/demo-only: database schema and file-storage capability exist conceptually but are not wired to live CRUD, uploads, or analytics APIs. ## Tech Stack & Architecture - **Runtime:** Browser-native ES modules; no bundler, package manager, transpilation, or JSX compilation. - **Entry point:** `index.html` - Loads Tailwind via CDN. - Loads `styles/main.css`. - Injects GenMB Auth SDK as `window.genmb.auth`. - Provides `

` for React. - **React:** `react@19.2.0` and `react-dom@19.2.0` from `https://esm.sh`. - **Templating:** `htm@3.1.1` bridge in `src/jsx.js`. - All components use ``html`...` `` templates. - Do **not** add raw JSX unless introducing a build step. - **Routing:** `HashRouter` from `react-router-dom@7`. - Routes are declared in `src/App.js`. - `/` → `Overview` - `/analytics` → `Analytics` - `/settings` → `Settings` - `*` → `NotFound` - `AuthGate` wraps the route tree, so every dashboard route requires auth. - **Charts:** `src/components/Charts.js` - Imports Chart.js exactly as: ```js import Chart from 'https://esm.sh/chart.js@4/auto'; ``` - `ChartPanel` creates a Chart.js instance inside `useEffect` and destroys it on cleanup. - It derives colors from CSS custom properties using `getComputedStyle(document.documentElement)`. - **Icons:** `lucide-react` from `https://esm.sh/lucide-react?deps=react@19.2.0`. - **Styling:** Tailwind CDN utility classes plus HSL CSS tokens/custom utilities in `styles/main.css`. - Components frequently use arbitrary Tailwind values like `bg-[hsl(var(--card))]`. - **State management:** Local React state plus providers in `src/mainProviders.js`. - `ThemeContext`: `theme`, `toggleTheme`, `setTheme`; persists `pulseforge-theme` in `localStorage`, toggles `document.documentElement.dark`, and sets `colorScheme`. - `AuthContext`: `user`, `loading`, `available`, `authenticated`, `signOut`; reads and subscribes to `window.genmb.auth`. - `ToastContext`: `notify(message, type)`; fixed toast stack with manual dismiss and 4.2s auto-timeout. - **Data source:** Static arrays in `src/data/sampleData.js`. - No database reads/writes are implemented. - No file-storage calls are implemented. ### Important Gotchas - Keep all imports browser-resolvable `.js` modules or full CDN URLs; there is no bundling or aliasing. - Theme changes do not automatically recolor already-mounted charts unless `ChartPanel` remounts or receives changed `type`, `labels`, or `datasets` references. - Always preserve `return () => chart.destroy()` in `ChartPanel`; otherwise Chart.js will leak canvases/listeners or duplicate charts. - `AuthGate` does **not** bypass auth if the GenMB SDK is unavailable. It shows an unavailable warning/state instead. - `Layout` sidebar collapsed state is in-memory only. The proposed `userSettings.sidebarCollapsed` table is not currently used. - `DataTable` has a fixed `perPage = 5`; the proposed `userSettings.defaultPageSize` and `dataTables.pageSize` are not currently used. - Because templates use HTM, nested components must be written as `<${Component}>...`, not JSX syntax. ## File Structure ```txt CLAUDE.md Project instructions/documentation for AI coding agents. index.html App shell; Tailwind CDN, custom CSS, injected GenMB auth SDK, root element. styles/main.css Global HSL tokens, dark theme variables, shadows, chart sizing, safe-area helpers. src/main.js React root; renders . src/jsx.js HTM bridge; exports html tagged template for JSX-free React components. src/mainProviders.js Theme, toast, and GenMB auth providers/hooks. src/App.js HashRouter route tree wrapped by AuthGate and Layout. src/components/AuthGate.js Full GenMB auth UI: Google, password, magic link, signup verify, reset. src/components/Layout.js Dashboard shell: sidebar, sticky header, mobile bottom nav, dark toggle, sign out. src/components/Button.js Shared button with primary/secondary/ghost variants and loading spinner. src/components/KpiCard.js KPI metric card with trend pill styling. src/components/Charts.js Chart.js wrapper component using CSS-token colors. src/components/DataTable.js Static priority accounts table with pagination and empty state. src/pages/Overview.js Main dashboard page with KPIs, hero/insights, charts, and account table. src/pages/Analytics.js Deeper analytics page with additional chart/image sections. src/pages/Settings.js User/workspace preferences page backed by local UI state. src/pages/NotFound.js Authenticated 404 card with link back to overview. src/data/sampleData.js Static KPI, chart, image, and account datasets. ``` ## Key Features ### Authentication Implemented in `src/components/AuthGate.js` and `src/mainProviders.js`. Requirements: - All routes must remain behind `AuthGate`. - Use `window.genmb.auth` only after checking availability. - Support: - Google sign-in via `auth.signIn()` - Magic link via `auth.sendMagicLink(email)` - Email/password via `auth.signInWithPassword(email, password)` - Signup via `auth.signUp(email, password, name)` followed by `auth.verifySignUp(pendingEmail, code)` - Password reset via `auth.requestPasswordReset(email)` and `auth.confirmPasswordReset(pendingEmail, code, password)` - Sign out via `auth.signOut()` - Toast user-facing success/error messages through `useToast().notify`. GenMB user object: ```js { id, email, name, picture } ``` Auth states: - `loading`: show secure workspace loading state. - `available === false`: show SDK unavailable messaging. - `user`: render dashboard children. - no user: render marketing/auth landing page. ### Dashboard Layout Implemented in `src/components/Layout.js`. Requirements: - Desktop sidebar is visible at `lg` and can collapse between `w-64` and `w-20`. - Mobile uses bottom nav with Overview, Analytics, Settings. - Header is sticky, includes current page title based on `location.pathname`. - Theme toggle uses `useTheme()`. - Sign-out button shows the GenMB user picture or a DiceBear initials avatar fallback. ### Overview Dashboard Implemented in `src/pages/Overview.js`, powered by `src/data/sampleData.js`. Expected content: - KPI grid using `kpis` and `KpiCard`. - SaaS visual storytelling sections using `heroImage` and `insightImages`. - Chart.js panels for revenue, signups, channels, retention, plans, and/or regional metrics. - Priority accounts table via `DataTable`. ### Analytics Page Implemented in `src/pages/Analytics.js`. Expected content: - Additional mixed Chart.js visualizations using: - `retentionLabels` / `retentionData` - `planLabels` / `planData` - `regionLabels` / `regionData` - other sample arrays from `sampleData.js` - Image-backed analytic cards using `analyticsImages`. - Should remain static unless real analytics APIs are added. ### Settings Page Implemented in `src/pages/Settings.js`. Requirements: - Settings UI is currently local/demo state only. - Theme changes should call `useTheme()` rather than manually editing DOM classes. - If adding persistent settings later, map to `userSettings`, `themes`, and `userProfiles`. ### KPI Cards Implemented in `src/components/KpiCard.js`. Data shape: ```js { id: string, label: string, value: string, delta: string, tone: 'success' | 'info' } ``` Notes: - Current card always uses `TrendingUp`; negative-but-good values like churn improvement are represented by string delta (`-0.7%`) and success tone. ### Charts Implemented in `src/components/Charts.js`. Props: ```js { title: string, description: string, type: 'line' | 'bar' | 'doughnut' | 'pie' | 'polarArea' | string, labels: string[], datasets: ChartJsDataset[] } ``` Requirements: - Keep chart container class `chart-box`; sizing is controlled by `styles/main.css`. - For non-radial charts, `x` and `y` scales use CSS-token grid/tick colors. - For `doughnut`, `pie`, and `polarArea`, scales are disabled. ### Data Table Implemented in `src/components/DataTable.js`. Data shape from `accounts`: ```js { id, company, owner, plan, mrr, health: 'Strong' | 'Watch' | 'At risk', renewal, logo } ``` Requirements: - Paginate client-side, 5 rows per page. - Horizontal overflow is required on small screens; table uses `min-w-[48rem]`. - Health pill colors: - `Strong` → success - `Watch` → warning - anything else → destructive - Empty state appears if `accounts.length === 0`. ### External Integrations and Assets - **GenMB Auth SDK:** injected in `index.html`, consumed as `window.genmb.auth`. - **Unsplash images:** static remote images in `sampleData.js`. - **DiceBear avatars/logos:** account logos and fallback user avatars. - **Chart.js CDN:** direct ESM import in `Charts.js`. ### Database Schema Status The app prompt includes tables for: - user profiles/settings/themes - dashboards/data sources/metrics/KPI cards/charts/chart series - data tables/columns - analytics pages/sidebar items - images/system settings Current generated app does **not** call any backend APIs for these tables. Treat them as future persistence targets, not existing runtime data models. If wiring backend later: - `userProfiles` should be keyed by `window.genmb.auth.getUser().id`. - `userSettings.darkModeEnabled` should synchronize with `pulseforge-theme`. - `userSettings.sidebarCollapsed` can replace local `Layout` collapsed state. - `images` can replace hardcoded Unsplash/DiceBear URLs where uploaded assets are desired. - `metricDefinitions`, `metricValues`, `charts`, and `chartSeries` should replace hardcoded chart arrays in `sampleData.js`. ## Design Guidelines - **Style:** Modern SaaS command-center UI: rounded cards, subtle borders, soft shadows, executive dashboard density. - **Color system:** Use HSL CSS variables from `styles/main.css`; do not hardcode one-off hex colors in components. - Primary, card, background, foreground, muted, border, ring, success, warning, destructive, info are consumed through `hsl(var(--token))`. - **Dark mode:** Driven by `.dark` class on `` and CSS variables. Use existing tokens so components work in both themes. - **Typography:** Tailwind default sans stack; headings use `font-semibold`/`font-bold` and tight tracking. - **Spacing:** Cards generally use `p-6`, sections use `gap-6`/`gap-8`, and dashboard page max width is controlled by `Layout` (`max-w-7xl`). - **Responsive behavior:** - Desktop sidebar only at `lg`. - Mobile bottom nav fixed at bottom. - Main content has `pb-24` on mobile to avoid bottom nav overlap. - Tables scroll horizontally. - Use `safe-top`/`safe-bottom` helpers for notched devices. - **Interactivity:** Buttons/cards use subtle translate/shadow transitions; focus rings must remain visible. ## App Flow 1. Browser loads `index.html`. 2. `src/main.js` mounts React into `#root`. 3. `Providers` initialize: - theme from `localStorage` - toast system - GenMB auth session via `auth.ready()` 4. `App` renders `HashRouter`. 5. `AuthGate`: - shows loading while session is checked - shows auth landing page if unauthenticated - renders dashboard routes if authenticated 6. Authenticated users land on `/` Overview. 7. Users can navigate: - Desktop: sidebar `NavLink`s - Mobile: fixed bottom nav 8. User can: - toggle dark mode from header - collapse desktop sidebar - review KPIs/charts/accounts - visit Analytics and Settings - sign out from header Edge cases: - Missing GenMB SDK: auth UI cannot proceed; do not silently allow dashboard access. - Popup Google sign-in can return `null` if no session is created; current UI shows informational toast. - Auth SDK may clean magic-link tokens from URL during `ready()`. - Unknown hash routes render `NotFound` inside the authenticated layout. - If static account data is empty, `DataTable` renders an empty state instead of a table. ## Conventions - Use named exports for components/pages: `export function ComponentName()`. - Every UI file that renders markup should import: ```js import React from 'https://esm.sh/react@19.2.0'; import { html } from '../jsx.js'; // or './jsx.js' from src root ``` - Use HTM syntax: ```js return html`

<${Child} prop=${value} />

`; ``` - For route links, import from: ```js import { Link, NavLink } from 'https://esm.sh/react-router-dom@7?deps=react@19.2.0'; ``` - For icons, import only needed icons from Lucide CDN. - Prefer static data additions in `src/data/sampleData.js` until a real API is introduced. - Keep styling inline with Tailwind utility classes and CSS variables; add reusable primitives to `styles/main.css` only when utilities become awkward or repeated. - New charts should use `ChartPanel`; do not instantiate Chart.js directly in pages unless `ChartPanel` is insufficient. - New buttons should use `src/components/Button.js` unless a semantic native button is simpler, such as icon-only header controls. - New authenticated pages: 1. Create `src/pages/NewPage.js`. 2. Export `NewPage`. 3. Import and add a `` in `src/App.js`. 4. Add a nav item to `navItems` in `src/components/Layout.js`. 5. Update header title logic in `Layout` if the path needs a custom title. - If introducing real persistence, keep GenMB auth as the source of user identity and document any new API surface here. ## 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.