StackwiseTechnologiesLtd · daniel-teddy · Aug 7, 2026 · Aug 20, 2026 · Aug 20, 2026 · Aug 20, 2026
diff --git a/.gitignore b/.gitignore
@@ -18,6 +18,7 @@
 /out/
 /.open-next/
 /.wrangler/
+.wrangler-secrets.tmp.json
 
 # production
 /build

diff --git a/README.md b/README.md
@@ -66,26 +66,94 @@ Locales:
 | `npm run lint` | ESLint |
 | `npm test` | Unit tests (Vitest) |
 | `npm run typecheck` | TypeScript (`tsc --noEmit`) |
+| `npm run db:migrate` | Apply SQL migrations to Neon (uses `.env.local` → `.env.prod` → `.env`) |
+| `npm run db:migrate:prod` | Apply migrations to **production** Neon (`MIGRATE_ENV=prod`, reads `.env.prod` only) |
+| `npm run db:reset:prod-payments` | Dry-run cleanup of sandbox rows in prod Neon; pass `--confirm` to apply |
 | `npm run preview` | Build OpenNext worker and preview in `workerd` via Wrangler |
 | `npm run build:worker` | Build the Cloudflare Worker bundle only |
 | `npm run deploy` | Build + deploy to Cloudflare Workers |
-| `npm run deploy:live` | Build + deploy current branch/commit as the **live** production Worker (tagged) |
+| `npm run deploy:live` | Full production deploy — see [Deploy to production](#deploy-to-production) |
+| `npm run cf:secrets` | Upload Worker secrets from `.env.prod` without redeploying |
 | `npm run cf:whoami` | Show Cloudflare auth account |
 | `npm run cf:status` | Show the live Workers deployment status |
 
-### Deploy from your machine
+### Environment files
+
+| File | Purpose |
+| --- | --- |
+| `.env.local` | Local development (gitignored). Copy from `.env.example`. |
+| `.env.prod` | Production secrets and config (gitignored). Used by deploy and prod migrations. |
+| `.env.example` | Template with placeholder keys — safe to commit. |
+
+Never commit `.env.local` or `.env.prod`.
+
+### Database migrations
+
+Migrations live in `migrations/*.sql` and are applied in filename order.
+
+```bash
+# Local / dev Neon
+npm run db:migrate
+
+# Production Neon (uses DATABASE_URL from .env.prod)
+npm run db:migrate:prod
+```
+
+The app also runs `ensureSchema()` on first DB access, which applies any pending migration files automatically.
+
+### Deploy to production
 
 You do not need GitHub Actions or the Cloudflare dashboard to ship:
 
 ```bash
-# one-time: log in if needed
+# One-time: log in to Cloudflare
 npx wrangler login
 
-# ship the current branch as production
+# Create .env.prod with production values (see .env.example)
+# Then ship:
 npm run deploy:live
 ```
 
-`deploy:live` tags the Worker version with the current git branch and short SHA (and marks `-dirty` if you have uncommitted changes), then rolls it out to 100% production traffic.
+#### What `npm run deploy:live` does
+
+Runs `scripts/deploy-live.sh`, which:
+
+1. **Checks auth** — exits if `wrangler whoami` fails.
+2. **Build env** — copies `.env.prod` → `.env.production.local` so `NEXT_PUBLIC_*` (e.g. site URL) is baked into the Next.js build, not localhost from `.env.local`.
+3. **Sync secrets** — calls `scripts/sync-cloudflare-env.mjs` to upload every key in `.env.prod` to the `stackwise-technologies` Worker via `wrangler secret bulk`.
+4. **Build** — runs `npm run build:worker` (OpenNext + Next.js production build).
+5. **Deploy** — publishes to Cloudflare Workers at 100% traffic, tagged with git branch + short SHA (e.g. `main@abc1234`).
+
+#### Sync secrets only (no redeploy)
+
+After editing `.env.prod`, push new secrets without rebuilding:
+
+```bash
+npm run cf:secrets
+# equivalent to: node scripts/sync-cloudflare-env.mjs .env.prod
+```
+
+Requires `wrangler` login. Uploads all non-comment `KEY=value` lines from the file as encrypted Worker secrets.
+
+#### Script reference (`scripts/`)
+
+| File | Invoked by | Description |
+| --- | --- | --- |
+| `scripts/deploy-live.sh` | `npm run deploy:live` | End-to-end production deploy: env, secrets, build, publish. |
+| `scripts/sync-cloudflare-env.mjs` | `npm run cf:secrets`, `deploy-live.sh` | Parses an env file and runs `wrangler secret bulk` for Worker `stackwise-technologies`. Optional arg: path to env file (default `.env.prod`). |
+| `scripts/migrate.mjs` | `npm run db:migrate`, `npm run db:migrate:prod` | Loads env files, connects to Neon, runs all `migrations/*.sql` in order. Set `MIGRATE_ENV=prod` to force `.env.prod`. |
+| `scripts/db-reset-prod-payments.mjs` | `npm run db:reset:prod-payments` | Removes test/sandbox payment links from production Neon and marks remaining drafts as live (`kpay_is_test = false`). Dry-run by default; `--confirm` to apply. |
+
+### Admin & payments (local)
+
+- Admin dashboard: [http://localhost:3000/admin](http://localhost:3000/admin)
+- Payment admin uses Neon Postgres, KPay, and SMTP — configure in `.env.local`.
+- For local payment E2E, set `NEXT_PUBLIC_SITE_URL=http://localhost:3000` in `.env.local`.
+- See [docs/PAYMENTS.md](docs/PAYMENTS.md) for payment flow, receipts, and legal notices.
+
+### Payments legal & compliance
+
+Customer payment pages (`/pay/*`) include a legal notice linking to [Payment processing & data](/pay/legal). See [docs/PAYMENTS.md](docs/PAYMENTS.md) for how payments, receipts, and personal data are handled.
 
 ---
 

diff --git a/docs/PAYMENTS.md b/docs/PAYMENTS.md
@@ -0,0 +1,61 @@
+# Payments — legal, receipts, and customer flow
+
+## Customer payment pages
+
+Public routes under `/pay/[slug]`:
+
+| Route | Purpose |
+| --- | --- |
+| `/pay/[slug]` | Invoice + pay (Card / Mobile Money via KPay) |
+| `/pay/[slug]/return` | KPay return handler |
+| `/pay/[slug]/receipt` | **Paid only** — printable receipt (A4) |
+| `/pay/legal` | Payment processing & data notice |
+
+Every pay page includes a **PaymentLegalNotice** footer linking to `/pay/legal`.
+
+## Payment processor
+
+- **KPay** handles checkout (card + Mobile Money).
+- Stackwise stores invoice metadata and payment status in Neon Postgres.
+- Card numbers and mobile-money PINs are never stored by Stackwise.
+
+## Audit logging
+
+Customer interactions on pay pages log IP address and user agent to `payment_audit_logs`:
+
+| Event | Trigger |
+| --- | --- |
+| `PAY_PAGE_VIEW` | Invoice page load |
+| `PAYMENT_INIT` | Pay button / KPay redirect |
+| `RETURN_CALLBACK` | KPay return URL |
+| `RECEIPT_VIEW` | Receipt page (paid only) |
+
+Logs are visible at `/admin/audit-logs` (latest 100 events) and on each payment-link detail page. Apply migration `0003_payment_audit_logs.sql` (or `npm run db:migrate`).
+
+## Receipt access
+
+Receipts are gated by payment status:
+
+- `canAccessReceipt(link)` returns true only when `status === "PAID"`.
+- Unpaid links redirect from `/pay/[slug]/receipt` to the pay page.
+- Admin “View receipt” is shown only for paid links.
+
+## Receipt email
+
+When payment completes (webhook or return URL sync), `finalizePaidPayment`:
+
+1. Marks the link `PAID`
+2. Sends receipt email to the customer via `sendPaymentReceiptEmails`
+3. Notifies admins listed in `ADMIN_NOTIFY_EMAILS`
+
+The email includes a **receipt URL** (`/pay/[slug]/receipt`) for viewing and printing.
+
+## Admin dashboard
+
+- Live links: `kpay_is_test = false` only (production DB filter)
+- Tables support **search** (invoice, customer, email) and **status filter**
+- **10 rows per page** pagination
+
+## Environment variables
+
+See `.env.example` for `KPAY_*`, `DATABASE_URL`, `SMTP_*`, and `ADMIN_EMAILS`.
diff --git a/migrations/0001_neon_init.sql b/migrations/0001_neon_init.sql
@@ -0,0 +1,49 @@
+CREATE TABLE IF NOT EXISTS admin_otps (
+  id UUID PRIMARY KEY,
+  subject_hash VARCHAR(64) NOT NULL,
+  otp VARCHAR(6) NOT NULL,
+  expires_at TIMESTAMPTZ NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_admin_otps_subject ON admin_otps(subject_hash);
+
+CREATE TABLE IF NOT EXISTS otp_verify_attempts (
+  subject_hash VARCHAR(64) PRIMARY KEY,
+  failed_count INT NOT NULL DEFAULT 0,
+  locked_until TIMESTAMPTZ NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS otp_send_throttle (
+  subject_hash VARCHAR(64) PRIMARY KEY,
+  last_attempt_at TIMESTAMPTZ NULL,
+  last_sent_at TIMESTAMPTZ NULL
+);
+
+CREATE TABLE IF NOT EXISTS payment_links (
+  id UUID PRIMARY KEY,
+  slug VARCHAR(32) UNIQUE NOT NULL,
+  customer_name TEXT NOT NULL,
+  customer_email TEXT NOT NULL,
+  currency VARCHAR(8) NOT NULL DEFAULT 'XAF',
+  amount_usd NUMERIC(12, 2) NOT NULL,
+  amount_local NUMERIC(14, 2) NOT NULL,
+  exchange_rate NUMERIC(16, 8) NOT NULL,
+  status VARCHAR(20) NOT NULL DEFAULT 'DRAFT',
+  line_items JSONB NOT NULL,
+  notes TEXT,
+  kpay_payment_id TEXT,
+  kpay_reference TEXT,
+  gateway_url TEXT,
+  invoice_number VARCHAR(32) UNIQUE NOT NULL,
+  sent_at TIMESTAMPTZ,
+  paid_at TIMESTAMPTZ,
+  receipt_sent_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_payment_links_slug ON payment_links(slug);
+CREATE INDEX IF NOT EXISTS idx_payment_links_status ON payment_links(status);
+CREATE INDEX IF NOT EXISTS idx_payment_links_created ON payment_links(created_at DESC);
diff --git a/migrations/0002_kpay_is_test.sql b/migrations/0002_kpay_is_test.sql
@@ -0,0 +1 @@
+ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS kpay_is_test BOOLEAN;
diff --git a/migrations/0003_payment_audit_logs.sql b/migrations/0003_payment_audit_logs.sql
@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS payment_audit_logs (
+  id UUID PRIMARY KEY,
+  payment_link_id UUID NOT NULL REFERENCES payment_links(id) ON DELETE CASCADE,
+  event VARCHAR(32) NOT NULL,
+  ip_address VARCHAR(45),
+  user_agent TEXT,
+  metadata JSONB,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_payment_audit_link ON payment_audit_logs(payment_link_id, created_at DESC);
diff --git a/migrations/0004_allowed_payment_methods.sql b/migrations/0004_allowed_payment_methods.sql
@@ -0,0 +1 @@
+ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS allowed_payment_methods VARCHAR(20) NOT NULL DEFAULT 'BOTH';
diff --git a/migrations/0005_manual_payment_fields.sql b/migrations/0005_manual_payment_fields.sql
@@ -0,0 +1,7 @@
+ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS payment_source VARCHAR(20);
+ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS payment_method VARCHAR(32);
+ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS amount_received_usd NUMERIC(12, 2);
+ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS amount_received_local NUMERIC(14, 2);
+ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS collected_at TIMESTAMPTZ;
+ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS payment_reference TEXT;
+ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS payment_notes TEXT;
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -3,6 +3,7 @@
   "version": "0.2.0",
   "private": true,
   "scripts": {
+    "db:migrate": "node scripts/migrate.mjs",
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
@@ -13,15 +14,21 @@
     "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
     "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
     "deploy:live": "bash scripts/deploy-live.sh",
+    "cf:secrets": "node scripts/sync-cloudflare-env.mjs .env.prod",
+    "db:migrate:prod": "MIGRATE_ENV=prod node scripts/migrate.mjs",
+    "db:reset:prod-payments": "MIGRATE_ENV=prod node scripts/db-reset-prod-payments.mjs",
     "cf:whoami": "wrangler whoami",
     "cf:status": "wrangler deployments status --name stackwise-technologies"
   },
   "dependencies": {
+    "@neondatabase/serverless": "^1.0.2",
     "next": "16.2.6",
+    "nodemailer": "^7.0.6",
     "react": "19.2.4",
     "react-dom": "19.2.4"
   },
   "devDependencies": {
+    "@types/nodemailer": "^7.0.1",
     "@opennextjs/cloudflare": "^1.20.2",
     "@tailwindcss/postcss": "^4",
     "@types/node": "^20",
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		ALTER TABLE payment_links ADD COLUMN IF NOT EXISTS kpay_is_test BOOLEAN;