ChatCart Software Manual

This manual documents the current application as built: its purpose, infrastructure, customer and operator usage, backend setup requirements, integrations, security posture, deployment expectations, and the remaining live-production configuration work still outstanding.

Product: ChatCart Company: InsightSphere Technologies Stack: Next.js + PostgreSQL + Prisma Recommended hosting: Vercel + Railway

1. Purpose of the application
2. Who uses the system
3. Product plans and feature separation
4. Infrastructure and architecture
5. Main application modules
6. Customer and operator journeys
7. Backend setup and environment configuration
8. Billing status and payment-provider notes
9. Security and recovery features
10. Running, testing, and operating the app
11. Outstanding configuration and go-live checklist

1. Purpose of the application

ChatCart is a multi-tenant SaaS application for businesses that sell, support, and manage customer interactions through WhatsApp. The product turns WhatsApp conversations into structured business operations.

What it solves

Scattered WhatsApp sales and support activity becomes a shared inbox, order workflow, payment workflow, reporting layer, and management dashboard.

Business value

Businesses can reply faster, capture orders consistently, send payment requests, track performance, and prepare for live Meta operations.

Commercial model

The app supports two plans, Starter and Growth, with enforced feature gating and trial-to-billing logic.

2. Who uses the system

Customer workspace users

Business owners, admins, agents, and viewers log into the tenant workspace to run daily operations.

/login for workspace access
Features include inbox, orders, billing, reports, templates, WhatsApp setup, and team management
Feature visibility depends on onboarding status, role, and plan entitlement

Platform operators

Internal SaaS operators log into a separate operator console to manage tenants and monitor platform readiness.

/admin/login for operator access
Features include tenant list, plan management, onboarding status, deletion requests, and environment/config oversight
Operator access is managed in-app and can also be bootstrapped from PLATFORM_ADMIN_EMAILS

3. Product plans and feature separation

The product has two real plans. The distinction is enforced in the application and visible in the customer subscription experience.

Capability	Starter	Growth
Monthly price	R99/mo	R199/mo
Seats included	3	10
Shared inbox	Included	Included
Order capture	Included	Included
Manual payment links	Included	Included
Template sync and send	Included	Included
Core reporting	Included	Included
Rules-based automations	Not included	Included
Advanced reporting	Not included	Included
PDF and Excel report exports	Not included	Included
Scheduled report emails	Not included	Included

4. Infrastructure and architecture

Frontend and backend

Framework: Next.js 15
UI and routes: App Router under app/
Backend logic: server actions and route handlers
Main languages: TypeScript and React

Database

Database: PostgreSQL
ORM: Prisma
Recommended provider: Railway PostgreSQL
Current operation depends on a valid DATABASE_URL

Hosting recommendation

Web app: Vercel
Database: Railway
Public domain recommended before live billing/Meta use
OneDrive-hosted local folders are discouraged

External integrations

WhatsApp target: Meta Cloud API
Embedded Signup is already built
Billing provider currently implemented: PayFast
Stripe remains available only as a legacy provider path

Current high-level architecture

Public app / Marketing pages
  -> Signup / Login / Forgot Password / Reset Password
  -> Customer workspace (/app/...)
  -> Platform operator console (/admin/...)

Next.js server actions + route handlers
  -> Prisma ORM
  -> PostgreSQL database

External systems
  -> Meta Cloud API + webhooks
  -> Billing provider (currently PayFast)
  -> Email webhook endpoint
  -> Cron scheduler for daily maintenance

5. Main application modules

Public pages

/ landing page
/signup plan-first signup
/login customer login
/forgot-password recovery request
/reset-password password reset

Customer workspace

/app overview
/app/getting-started onboarding checklist
/app/inbox shared conversation workspace
/app/reports reporting and exports
/app/test-setup guided live validation

Customer settings

Business profile
Team
WhatsApp
Templates
Billing / Subscription
Security / Activity / Automations

Operator console

/admin platform dashboard
/admin/tenants all customer tenants
/admin/tenants/[organizationId] per-tenant support view
/admin/settings platform admin management, policy view, deletion requests, env summary

Important backend endpoints

/api/webhooks/whatsapp
/api/whatsapp/connect/embedded-signup-session
/api/whatsapp/connect/embedded-signup-callback
/api/webhooks/payfast (production ITN endpoint)
/api/webhooks/stripe (legacy)
/api/internal/cron/daily
/api/exports/[id]

6. Customer and operator journeys

Customer onboarding flow

Customer lands on the marketing page.
Customer chooses Starter or Growth.
Customer creates an account.
Customer creates a workspace and enters business details.
The app starts a 14-day trial for the selected plan.
The user is directed into Getting Started.
The user connects WhatsApp, syncs templates, and completes guided setup.
The user can then go live and use the full workspace.

Operator flow

Operator logs into /admin/login.
Operator reviews platform state, tenants, deletion requests, plan assignment, and environment readiness.
Operator can grant or revoke platform-admin access, create operator accounts, and support tenants without logging into tenant pages manually.

Subscription access logic currently enforced

Trial active -> full access
Trial expired + no paid subscription -> billing and reports only
Active paid subscription -> full access
Past due -> billing only
Cancelled -> immediate restriction and 5-business-day cleanup schedule

7. Backend setup and environment configuration

The current environment surface is defined in .env.example and summarized in the operator console.

Variable	Purpose	Status
`DATABASE_URL`	PostgreSQL connection string	Required
`APP_URL`	Base URL for links, callbacks, and email links	Required
`APP_NAME`	Display/application name	Required
`BILLING_PROVIDER`	Selects the live billing provider	Required for production
`SESSION_SECRET`	Signs customer and operator sessions	Required
`APP_ENCRYPTION_KEY`	Encrypts sensitive tokens	Required
`APP_ENCRYPTION_KEYS`	Supports key rotation	Optional / recommended later
`CRON_SECRET`	Protects the daily cron endpoint	Required for production
`EMAIL_WEBHOOK_URL`	Sends deletion, scheduled-report, and password-reset emails	Required for real email delivery
`EMAIL_WEBHOOK_SECRET`	Secures the email webhook	Recommended
`PLATFORM_ADMIN_EMAILS`	Optional bootstrap operator allow-list	Optional
`META_APP_ID`	Meta Embedded Signup / Cloud API app id	Required for live Meta setup
`NEXT_PUBLIC_META_APP_ID`	Client-side Meta app id	Required for live Meta setup
`META_APP_SECRET`	Meta app secret	Required for live Meta setup
`META_EMBEDDED_SIGNUP_CONFIG_ID`	Meta Embedded Signup config id	Required for live Meta setup
`NEXT_PUBLIC_META_EMBEDDED_SIGNUP_CONFIG_ID`	Client-side signup config id	Required for live Meta setup
`META_BUSINESS_ID`	Meta business context	Required for live Meta setup
`META_SYSTEM_USER_ACCESS_TOKEN`	Meta API token	Required for live Meta setup
`META_WEBHOOK_VERIFY_TOKEN`	Webhook verification	Required for live Meta setup
`META_GRAPH_API_VERSION`	Meta Graph version	Required
`SECURITY_ALERT_EMAIL`	Security/ops alert destination	Optional
`BACKUP_STORAGE_PATH`	Backup posture tracking	Optional
`PAYFAST_*`	PayFast merchant, return, cancel, and notify configuration	Required for the implemented billing flow
`PAYFAST_SANDBOX`	Optional sandbox mode for local or test environments	Recommended outside production
`STRIPE_*`	Legacy Stripe provider configuration	Optional / legacy only

Recommended local startup

npm install
npm run prisma:push
npm run prisma:seed
npm run dev

8. Billing status and payment-provider notes

The application currently contains a working PayFast billing architecture in code, including secure checkout handoff, ITN-driven plan activation, trial expiry rules, cancellation rules, and access gating.

For deployment readiness, PayFast is the selected production billing provider. Stripe remains in the codebase as a legacy provider path and should not be presented to customers unless the billing configuration is intentionally switched back.

9. Security and recovery features

Security already built

Sensitive token encryption
Encryption key rotation support
Webhook idempotency
Security headers
Rate limiting
Tenant isolation logic
Role-based access control

Compliance and lifecycle

Deletion request workflow
5-business-day deletion policy
Company identity preservation after deletion for trial-reuse detection
Data export records
Audit and activity logs
Retention policy settings

Account recovery

Forgot-password flow
Reset-password flow
One-time reset tokens with expiry
Session invalidation after reset
Password policy enforcement on reset

Password policy

Minimum 8 characters
Uppercase required
Lowercase required
Number required
Special character required

10. Running, testing, and operating the app

npm install
npm run prisma:push
npm run prisma:seed
npm run dev
npm test
npm run build

Email delivery is abstracted behind EMAIL_WEBHOOK_URL. Until that webhook is configured, email-dependent features are safe but non-delivering.

11. Outstanding configuration and go-live checklist

Domain and company email
Hosting: deploy the app to Vercel and the database to Railway
Meta live configuration: fill all Meta environment variables and register the live webhook/callback URLs
Email service: configure EMAIL_WEBHOOK_URL and EMAIL_WEBHOOK_SECRET
PayFast live configuration: add merchant credentials, passphrase, return/cancel URLs, and notify URL
Live webhook testing
Backups and monitoring