nitheeshdr/pulsecommerce

Purpose and entry points

PulseCommerce is a self-hosted WooCommerce analytics and WhatsApp campaign system. It ingests a store’s WooCommerce REST data, derives analytics from a cached snapshot, and sends WhatsApp through a separately hosted OpenWA gateway.

UI entry points are the public/authentication pages and route groups: src/app/(marketing)/page.tsx, src/app/login/page.tsx, src/app/connect/page.tsx, and the authenticated application shell at src/app/(app)/layout.tsx. Server entry points are Next.js route handlers under src/app/api/; deployment targets Node/Vercel via vercel.json.

Store authorization, tenancy, and persistence

WooCommerce authorization is a three-leg flow: browser start, WooCommerce server-to-server credential callback, then browser return. Its handlers are src/app/api/auth/woo/start/route.ts, src/app/api/auth/woo/callback/route.ts, and src/app/api/auth/woo/return/route.ts. Signed session/state and tenant selection live in src/lib/auth/session.ts, src/lib/auth/pending.ts, and src/lib/auth/tenant.ts.

Supabase supplies durable relational state and migrations establish the KV, Woo mirror, app tables, multi-tenancy, RLS, broadcast recipients, and cron support: src/lib/supabase/server.ts, supabase/migrations/20260811140000_multi_tenant.sql, supabase/migrations/20260811150000_rls.sql. The app can also use filesystem/Redis-style snapshot persistence through src/lib/store/config.ts and src/lib/store/snapshot.ts.

WooCommerce ingestion and snapshot boundary

The Woo integration fetches orders, products, customers, coupons, and attribution through the Woo REST API; it is the primary external data boundary. Core modules are src/lib/woo/client.ts, src/lib/woo/sync.ts, and src/lib/woo/mirror.ts.

Sync routes trigger or schedule pulls at src/app/api/sync/route.ts and src/app/api/cron/sync/route.ts. Data is trimmed/slimmed and cached as a tenant/store-specific snapshot before downstream computation. This isolates Woo I/O and retries from request-time analytics; re-authorization updates credentials without conceptually changing the analytical model.

Pure analytics and application pages

src/lib/analytics/engine.ts is the central computation boundary: snapshot input produces reproducible KPIs and page payloads without external I/O. Domain stages split into customer/RFM and cohorts (src/lib/analytics/customers.ts, src/lib/analytics/cohorts.ts), acquisition (src/lib/analytics/acquisition.ts), and merchandise/operations/inventory (src/lib/analytics/products.ts, src/lib/analytics/inventory.ts, src/lib/analytics/operations.ts).

The aggregate analytics API is src/app/api/analytics/route.ts; individual customer history is loaded on demand through src/app/api/customers/[key]/route.ts. App pages such as src/app/(app)/dashboard/page.tsx, src/app/(app)/customers/page.tsx, and src/app/(app)/inventory/page.tsx render those derived results. Phone numbers remain server-side; browser-facing data uses reachability rather than raw contact details.

WhatsApp campaigns, flows, and inbox

WhatsApp is an outbound integration boundary: the app calls a self-hosted OpenWA gateway over HTTPS/API key; the gateway owns the persistent WhatsApp session. Client/configuration and recipient safety logic reside in src/lib/whatsapp/client.ts, src/lib/whatsapp/recipients.ts, and src/lib/whatsapp/opt-out.ts.

Broadcast creation and tick-based progress are exposed at src/app/api/whatsapp/broadcast/route.ts and implemented in src/lib/whatsapp/broadcast.ts. Audiences are recomputed server-side from snapshots, then phone resolution, deduplication, and opt-out filtering occur before dispatch. Scheduled multi-step flows persist due state and advance through src/app/api/cron/flows/route.ts and src/lib/whatsapp/flows.ts. Inbox, menu, session/QR, and gateway settings are separate API surfaces under src/app/api/whatsapp/.

Assistant, exports, and operational infrastructure

The Groq-backed assistant uses controlled tools in src/lib/ai/tools.ts and src/lib/ai/execute.ts, exposed by src/app/api/ai/chat/route.ts. Read tools operate on store data; actions are proposals that require later use of ordinary guarded endpoints.

Reports derive from the same analytics data and generate CSV/XLSX/PDF through src/lib/export/csv.ts, src/lib/export/xlsx.ts, and src/lib/export/pdf.ts, served by src/app/api/reports/export/route.ts.

Material runtimes/services are Next.js 16/React 19/TypeScript, Supabase, WooCommerce/WordPress, optional Redis-compatible KV on serverless, Vercel Cron for flows/sync, Groq for AI, and an always-on VPS/container-hosted OpenWA gateway. API contracts are published from src/app/api/openapi/route.ts and rendered at src/app/api-docs/route.ts.