# nitheeshdr/pulsecommerce architecture

> Architecture diagram of the GitHub repository nitheeshdr/pulsecommerce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nitheeshdr/pulsecommerce
- Repository: https://github.com/nitheeshdr/pulsecommerce

## Overview

#### 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`.

Main entry points: [`src/lib/analytics/engine.ts`](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/analytics/engine.ts) (Analytics engine), [`src/lib/woo/sync.ts`](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/woo/sync.ts) (Woo sync and mirror), [`src/lib/store/snapshot.ts`](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/store/snapshot.ts) (Tenant snapshot), [`src/app/api/auth/woo/start/route.ts`](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/auth/woo/start/route.ts) (Woo authorization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Next.js application"]
  node_ui["Public and app UI<br/>Next.js pages<br/>[layout.tsx]"]
  node_auth["Woo authorization<br/>OAuth-like flow<br/>[route.ts]"]
  node_tenant_session["Tenant sessions<br/>auth state<br/>[session.ts]"]
  node_app_api["Application APIs<br/>route handlers<br/>[route.ts]"]
  node_sync_triggers["Sync triggers<br/>API and cron<br/>[route.ts]"]
  node_assistant["AI assistant<br/>controlled tool execution<br/>[execute.ts]"]
  node_exports["Report exports<br/>CSV/XLSX/PDF generation<br/>[route.ts]"]
  node_operations["Platform operations<br/>cron and API docs<br/>[route.ts]"]
end

subgraph group_data["Data &amp; analytics"]
  node_woo_sync["Woo sync and mirror<br/>ingestion pipeline<br/>[sync.ts]"]
  node_snapshot[("Tenant snapshot<br/>cached store data<br/>[snapshot.ts]")]
  node_analytics["Analytics engine<br/>pure computation<br/>[engine.ts]"]
  node_analytics_domains["Analytics domains<br/>domain calculations<br/>[customers.ts]"]
end

subgraph group_integrations["External services"]
  node_supabase[("Supabase<br/>relational persistence<br/>[server.ts]")]
  node_woo{{"WooCommerce / WordPress<br/>store REST API<br/>[client.ts]"}}
  node_kv[("Optional snapshot KV<br/>filesystem or Redis<br/>[config.ts]")]
  node_openwa{{"OpenWA gateway<br/>self-hosted WhatsApp service<br/>[client.ts]"}}
end

subgraph group_automation["Campaign automation"]
  node_campaign_api["WhatsApp APIs<br/>broadcast and inbox routes<br/>[route.ts]"]
  node_audience_safety["Audience safety<br/>recipient processing<br/>[recipients.ts]"]
  node_broadcasts["Broadcast runner<br/>campaign execution<br/>[broadcast.ts]"]
  node_flows["Scheduled flows<br/>multi-step automation<br/>[flows.ts]"]
end

node_ui -->|"connects store"| node_auth
node_auth -->|"establishes"| node_tenant_session
node_auth -->|"credential callback"| node_woo
node_tenant_session -->|"scopes requests"| node_app_api
node_sync_triggers -->|"starts pulls"| node_woo_sync
node_woo_sync -->|"fetches REST data"| node_woo
node_woo_sync -->|"writes slimmed data"| node_snapshot
node_woo_sync -->|"updates mirror"| node_supabase
node_snapshot -->|"input"| node_analytics
node_analytics_domains -->|"contributes metrics"| node_analytics
node_analytics -->|"derived payloads"| node_app_api
node_app_api -->|"renders results"| node_ui
node_snapshot -.->|"optionally persists"| node_kv
node_campaign_api -->|"prepares audience"| node_audience_safety
node_snapshot -->|"recomputes audience"| node_audience_safety
node_audience_safety -->|"eligible recipients"| node_broadcasts
node_broadcasts -->|"dispatches HTTPS/API key"| node_openwa
node_flows -->|"advances due steps"| node_broadcasts
node_flows -->|"persists state"| node_supabase
node_operations -.->|"scheduled invocation"| node_sync_triggers
node_operations -.->|"scheduled invocation"| node_flows
node_assistant -->|"controlled read tools"| node_analytics
node_exports -->|"report data"| node_analytics

click node_ui "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/(app)/layout.tsx"
click node_auth "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/auth/woo/start/route.ts"
click node_tenant_session "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/auth/session.ts"
click node_app_api "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/analytics/route.ts"
click node_sync_triggers "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/sync/route.ts"
click node_woo_sync "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/woo/sync.ts"
click node_snapshot "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/store/snapshot.ts"
click node_analytics "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/analytics/engine.ts"
click node_analytics_domains "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/analytics/customers.ts"
click node_supabase "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/supabase/server.ts"
click node_woo "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/woo/client.ts"
click node_kv "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/store/config.ts"
click node_campaign_api "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/whatsapp/broadcast/route.ts"
click node_audience_safety "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/whatsapp/recipients.ts"
click node_broadcasts "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/whatsapp/broadcast.ts"
click node_flows "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/whatsapp/flows.ts"
click node_openwa "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/whatsapp/client.ts"
click node_assistant "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/ai/execute.ts"
click node_exports "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/reports/export/route.ts"
click node_operations "https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/openapi/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_auth,node_tenant_session,node_app_api,node_sync_triggers,node_assistant,node_exports,node_operations toneBlue
class node_woo_sync,node_snapshot,node_analytics,node_analytics_domains toneAmber
class node_supabase,node_woo,node_kv,node_openwa toneMint
class node_campaign_api,node_audience_safety,node_broadcasts,node_flows toneRose
```

## Components

### Next.js application

- [Public and app UI](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/(app)/layout.tsx): Next.js pages · Marketing, login, connect, and authenticated analytics views. · `src/app/(app)/layout.tsx`
- [Woo authorization](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/auth/woo/start/route.ts): OAuth-like flow · Three-leg store credential authorization flow. · `src/app/api/auth/woo/start/route.ts`
- [Tenant sessions](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/auth/session.ts): auth state · Signed session, pending state, and tenant selection. · `src/lib/auth/session.ts`
- [Application APIs](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/analytics/route.ts): route handlers · Analytics, customer, and guarded application endpoints. · `src/app/api/analytics/route.ts`
- [Sync triggers](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/sync/route.ts): API and cron · Manual and scheduled WooCommerce pulls. · `src/app/api/sync/route.ts`
- [AI assistant](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/ai/execute.ts): controlled tool execution · Groq-backed read tools and proposal-only actions. · `src/lib/ai/execute.ts`
- [Report exports](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/reports/export/route.ts): CSV/XLSX/PDF generation · Produces reports from shared analytics data. · `src/app/api/reports/export/route.ts`
- [Platform operations](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/openapi/route.ts): cron and API docs · Vercel cron invokes scheduled work; OpenAPI documents contracts. · `src/app/api/openapi/route.ts`

### Data & analytics

- [Woo sync and mirror](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/woo/sync.ts): ingestion pipeline · Fetches, slims, and mirrors WooCommerce entities. · `src/lib/woo/sync.ts`
- [Tenant snapshot](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/store/snapshot.ts): cached store data · Store-specific boundary between ingestion and computation. · `src/lib/store/snapshot.ts`
- [Analytics engine](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/analytics/engine.ts): pure computation · Reproducible KPIs and page payloads from snapshots. · `src/lib/analytics/engine.ts`
- [Analytics domains](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/analytics/customers.ts): domain calculations · Customer, cohort, acquisition, product, inventory, and operations stages. · `src/lib/analytics/customers.ts`

### External services

- [Supabase](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/supabase/server.ts): relational persistence · Multi-tenant app state, Woo mirror, RLS, recipients, and cron state. · `src/lib/supabase/server.ts`
- [WooCommerce / WordPress](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/woo/client.ts): store REST API · Primary external store-data and credential boundary. · `src/lib/woo/client.ts`
- [Optional snapshot KV](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/store/config.ts): filesystem or Redis · Alternative snapshot persistence, including serverless-compatible KV. · `src/lib/store/config.ts`
- [OpenWA gateway](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/whatsapp/client.ts): self-hosted WhatsApp service · Always-on gateway owning the persistent WhatsApp session. · `src/lib/whatsapp/client.ts`

### Campaign automation

- [WhatsApp APIs](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/app/api/whatsapp/broadcast/route.ts): broadcast and inbox routes · Broadcast, inbox, menu, session, and gateway API surfaces. · `src/app/api/whatsapp/broadcast/route.ts`
- [Audience safety](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/whatsapp/recipients.ts): recipient processing · Resolves phones, deduplicates, and enforces opt-outs server-side. · `src/lib/whatsapp/recipients.ts`
- [Broadcast runner](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/whatsapp/broadcast.ts): campaign execution · Creates broadcasts and advances tick-based delivery. · `src/lib/whatsapp/broadcast.ts`
- [Scheduled flows](https://github.com/nitheeshdr/pulsecommerce/blob/main/src/lib/whatsapp/flows.ts): multi-step automation · Persists due steps and advances campaign flows. · `src/lib/whatsapp/flows.ts`

## Connections

- Public and app UI → Woo authorization: connects store
- Woo authorization → Tenant sessions: establishes
- Woo authorization → WooCommerce / WordPress: credential callback
- Tenant sessions → Application APIs: scopes requests
- Sync triggers → Woo sync and mirror: starts pulls
- Woo sync and mirror → WooCommerce / WordPress: fetches REST data
- Woo sync and mirror → Tenant snapshot: writes slimmed data
- Woo sync and mirror → Supabase: updates mirror
- Tenant snapshot → Analytics engine: input
- Analytics domains → Analytics engine: contributes metrics
- Analytics engine → Application APIs: derived payloads
- Application APIs → Public and app UI: renders results
- Tenant snapshot → Optional snapshot KV: optionally persists
- WhatsApp APIs → Audience safety: prepares audience
- Tenant snapshot → Audience safety: recomputes audience
- Audience safety → Broadcast runner: eligible recipients
- Broadcast runner → OpenWA gateway: dispatches HTTPS/API key
- Scheduled flows → Broadcast runner: advances due steps
- Scheduled flows → Supabase: persists state
- Platform operations → Sync triggers: scheduled invocation
- Platform operations → Scheduled flows: scheduled invocation
- AI assistant → Analytics engine: controlled read tools
- Report exports → Analytics engine: report data