[DO NOT MERGE until #672] promote: beta → main (adopt new ladder)

.coderabbit.yaml

@@ -0,0 +1,99 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: "en-US"
+
+reviews:
+  # Keep automated reviews enabled. Financial and provider changes require
+  # correctness-focused feedback, even when a PR is otherwise small.
+  profile: "chill"
+  auto_review:
+    enabled: true
+    drafts: true
+  instructions: |
+    You are reviewing Twizrr, a Nigerian social-commerce marketplace. Focus on
+    correctness, security, financial safety, and architectural boundaries over
+    minor styling or docstring nits. Do not report a concern unless you can
+    describe a concrete failure scenario from the changed code.
+
+    1. Financial correctness and ledger
+       - All persisted money is BigInt in kobo. Never use float/Number for
+         financial calculation or JSON audit metadata; serialize JSON amounts as
+         decimal strings.
+       - LedgerEntry is append-only and is the source of truth for money
+         movement. Completion ledger entries require both a provider-confirmed
+         outcome and the committed guarded state transition.
+       - Check idempotency and concurrency for payment, refund, payout, escrow,
+         settlement, webhook, retry, reconciliation, outbox, and notification
+         changes. Duplicate delivery must not duplicate a provider submission,
+         ledger entry, durable notification, or completion transition.
+       - Flag external provider calls inside Prisma transactions and unguarded
+         read-modify-write state transitions.
+
+    2. Provider architecture and switching
+       - Domain services must depend on Twizrr-owned provider contracts, not raw
+         provider SDKs, clients, request payloads, response shapes, or status
+         strings.
+       - New operations use the configured provider only. Existing payment,
+         refund, payout, and settlement operations remain immutably bound to the
+         provider and provider reference recorded when they were created.
+       - Never silently fall back from one financial provider to another. A
+         provider switch must not collapse, overwrite, or orphan prior provider
+         attempts/references needed for webhook or reconciliation handling.
+       - Provider adapters must normalize errors and statuses. Raw provider
+         payloads, secrets, bank details, credentials, and headers must not
+         reach domain DTOs, events, logs, or public responses.
+
+    3. Payments, refunds, payouts, and webhooks
+       - Every explicit payment/refund/payout webhook must fail closed when raw
+         body or signature data is absent, malformed, or invalid. Verify the
+         provider-specific signature before any order, payout, refund, or ledger
+         state change.
+       - Do not mark REFUND_COMPLETED or PAYOUT_COMPLETED before a confirmed
+         provider success. Submitted, processing, timeout, and ambiguous states
+         require reconciliation or manual review, never a blind retry.
+       - Verify that provider references remain searchable in provider-neutral
+         admin, dispute, payout, and reconciliation views.
+       - Preserve payout holds and dispute/settlement safeguards. A settlement
+         leg may only act through its own approved, deterministic path.
+
+    4. Database and Prisma
+       - Use transactions for related database writes, but never include
+         external provider calls in them.
+       - Check for lost updates, race conditions, missing unique constraints,
+         unstable query ordering used for idempotency, and non-deterministic
+         legacy aggregation keys.
+       - Review migrations for checkout safety on populated tables. Flag
+         destructive drift, unsafe locking/index creation, and modified applied
+         migrations. Do not suggest db push for shared environments.
+
+    5. Security and privacy
+       - Every non-public controller route needs JwtAuthGuard and appropriate
+         ownership/role checks. Admin routes need the appropriate OPERATOR or
+         SUPER_ADMIN protection.
+       - Never expose or log passwords, OTPs, cookies, Authorization headers,
+         access/refresh tokens, raw request bodies/headers, provider payloads,
+         bank information, delivery addresses, delivery codes, raw NIN/selfies,
+         or private prompt values.
+       - Request security context and coarse IP geo are risk/audit signals only:
+         do not turn them into blocking, GPS collection, fingerprinting, or
+         automatic enforcement without an explicit product decision.
+
+    6. Realtime, notifications, and delivery
+       - PostgreSQL/REST remains authoritative. Outbox events and Socket.IO are
+         durable bridges/cache-invalidation hints, never the source of truth.
+       - Check deterministic outbox and notification dedupe keys. Pending or
+         submitted states must not send copy claiming money or delivery is
+         complete.
+       - Shipping provider adapters verify and normalize webhooks; delivery
+         domain services own guarded state changes. Delivery OTP, address, phone,
+         notes, and raw provider payloads must never appear in logs, outbox,
+         notification metadata, or socket payloads.
+
+    7. Product boundaries
+       - Preserve escrow protection for every order. Do not reintroduce direct
+         seller payment, supplier/B2B/RFQ/wholesale/trade-financing concepts, or
+         store-management flows in WhatsApp.
+       - Keep KYB tier rules unchanged: Tier 1 and Tier 2 are active MVP flows.
+         Provider abstractions may support future CAC/Tier 3 capability but must
+         not activate a new Tier 3 business flow without explicit approval.
+       - Frontend changes must be mobile-first, have loading/error states, and
+         use Twizrr language. Do not introduce emojis in UI or WhatsApp copy.

.dockerignore

@@ -0,0 +1,41 @@
+.git
+.gitignore
+
+# Dependencies
+node_modules
+**/node_modules
+
+# Build and cache outputs
+.turbo
+**/.turbo
+.next
+**/.next
+dist
+**/dist
+coverage
+**/coverage
+
+# Environment files and local secrets
+.env
+.env.*
+**/.env
+**/.env.*
+
+# Logs and temporary files
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+tmp
+temp
+*.tmp
+
+# OS/editor files
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+.idea
+.vscode

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @onerandomdevv

.github/pull_request_template.md

@@ -1,47 +1,48 @@
 ## What does this PR do?
 
-<!-- Brief description of the changes -->
-
-## Module(s) affected
-
-<!-- Check all that apply -->
-- [ ] Auth
-- [ ] Merchant
-- [ ] Product
-- [ ] RFQ
-- [ ] Quote
-- [ ] Order
-- [ ] Payment
-- [ ] Inventory
-- [ ] Notification
-- [ ] Frontend
-- [ ] Shared
-- [ ] Infrastructure
+<!-- One paragraph: what changed and why. -->
 
 ## Type of change
 
 - [ ] New feature
 - [ ] Bug fix
-- [ ] Refactor
+- [ ] Refactor / cleanup
+- [ ] Database migration included
+- [ ] Chore / maintenance
 - [ ] Documentation
-- [ ] Tests
 
-## Checklist
+## Area affected
 
-- [ ] My code builds without errors (`pnpm build`)
-- [ ] I've tested this locally
-- [ ] I haven't added features outside V1 scope
-- [ ] All money values use BigInt kobo (not floats)
-- [ ] Merchant-scoped queries include merchantId filter
-- [ ] No direct inventory mutations (events only)
-- [ ] No business logic in controllers (services only)
-- [ ] No `.env` files or secrets in this PR
-- [ ] No `console.log` left in code (except health/dev logging)
+- [ ] Backend
+- [ ] Web
+- [ ] WhatsApp
+- [ ] Shared package
+- [ ] Database / Prisma
+- [ ] GitHub / CI / infrastructure
 
-## How to test
+## How to test this
 
-<!-- Steps for reviewer to verify the changes -->
+1. 
+2. 
+3. 
+Expected result: 
 
-## Screenshots (if frontend)
+## Pre-commit checklist
 
-<!-- Add screenshots for UI changes -->
+- [ ] Backend lint/type/build pass when backend is affected
+- [ ] Web lint/type/build pass when web is affected
+- [ ] Shared package build passes when shared is affected
+- [ ] No `console.log` left in production code
+- [ ] No secrets or `.env` files committed
+- [ ] No new `any` types added
+- [ ] No non-MVP legacy features reintroduced
+- [ ] All money values are BigInt kobo, never float
+- [ ] Paystack webhook changes verify HMAC before processing
+- [ ] Database migrations are Prisma migrations, not `db push`
+- [ ] Database migrations are backward-compatible or risk is documented
+
+## Screenshots
+
+<!-- Required for UI changes. Add before/after screenshots or write N/A. -->
+
+## Notes for reviewer