Skip to content

README.md

Latest commit

 

History

History
263 lines (196 loc) · 8.34 KB

README.md

File metadata and controls

263 lines (196 loc) · 8.34 KB

twizrr

twizrr is a Nigerian social commerce marketplace for shoppers and store owners. Stores list products, shoppers discover and buy through the web app or WhatsApp, and every transaction is escrow-protected until delivery is confirmed.

MVP Scope

The MVP is focused on B2C social commerce:

  • Shopper signup, browsing, cart, checkout, orders, and delivery confirmation.
  • Store owner signup, store setup, product listing, order management, and payouts.
  • Paystack escrow payments with webhook verification.
  • Ledger-backed money movement tracking.
  • BullMQ workers for checkout reminders, auto-confirmation, notifications, payouts, and async channel work.
  • WhatsApp shopper assistant for product discovery, search, and order updates.
  • Cloudinary image handling.
  • Gemini / Google AI assisted product search and intent handling.
  • Tier 1 auto verification and Tier 2 identity/NIN verification.
  • Admin tools for moderation, verification, disputes, payouts, users, inventory, and operations.

Deferred or removed from the MVP:

  • Supplier/B2B workflows.
  • RFQ and quote flows.
  • Trade financing / BNPL.
  • Direct payments outside escrow.
  • Tier 3 / CAC verification.
  • Review and reorder systems.
  • Sentry.
  • Mobile app.

Monorepo Structure

twizrr/
├── apps/
│   ├── backend/          # NestJS API, workers, channels, integrations
│   └── web/              # Next.js App Router frontend
├── packages/
│   └── shared/           # Shared TypeScript types, enums, constants, utilities
├── docker-compose.yml    # Local services
├── pnpm-workspace.yaml   # Workspace package config
├── turbo.json            # Turborepo config
└── README.md

Backend Architecture

The backend is a NestJS modular monolith with clear boundaries:

  • core/: infrastructure setup such as config, Prisma, Redis, health checks, logging, throttling, and static assets.
  • channels/: external entry points such as WhatsApp and USSD.
  • integrations/: third-party provider clients such as Paystack, Cloudinary, Resend, Meta WhatsApp, AI, Shipbubble, Prembly, and Google Places.
  • domains/: high-level domain composition boundaries for commerce, orders, money, users, social, and platform concerns.
  • modules/: active business modules such as auth, product, cart, order, payment, payout, ledger, merchant/store, verification, upload, notifications, and admin.
  • queue/: BullMQ queues and processors.

Tech Stack

Layer Technology
Frontend Next.js 14, React 18, Tailwind CSS, React Query
Backend NestJS 10, TypeScript
Database Neon PostgreSQL with Prisma
Cache and Queues Redis, BullMQ
Payments Paystack
Messaging Meta WhatsApp Cloud API, Africa's Talking
AI Gemini / Google AI, Google Vision, Vertex AI
Email Resend
Images Cloudinary
Monorepo pnpm workspaces, Turborepo

Local Setup

Prerequisites:

  • Node.js 20+
  • pnpm
  • Docker Desktop if using local services
  • Backend and web environment files

Install dependencies:

pnpm install

Start local services when you want local infrastructure:

docker compose up -d postgres redis

Docker is optional for local development. The backend can run directly with pnpm and connect either to managed/cloud Redis or to the local Docker Redis service.

Redis options for local development:

  • Managed/cloud Redis: set REDIS_URL to a Redis protocol URL such as rediss://....
  • Local Docker Redis: run docker compose up -d redis and set REDIS_URL=redis://localhost:6379.

docker compose up -d redis starts Redis infrastructure only. It does not start the backend dev server because the compose file does not define a backend app service.

Set up environment files:

  • Copy apps/backend/.env.example to apps/backend/.env.
  • Copy apps/web/.env.example to apps/web/.env.local.

Run database migrations for local development:

cd apps/backend
pnpm exec prisma migrate dev
pnpm exec prisma db seed

Run the apps:

cd apps/backend
pnpm run dev

cd ../web
pnpm run dev

Or from the repo root:

pnpm --filter @twizrr/backend dev
pnpm --filter @twizrr/web dev

Backend: http://localhost:4000

Frontend: http://localhost:3000

Verification

Backend:

cd apps/backend
npx prisma validate --schema=prisma/schema.prisma
npx tsc --noEmit
pnpm run lint
pnpm run build

Web:

cd apps/web
npx tsc --noEmit
pnpm run lint
pnpm run build

Shared package:

cd packages/shared
pnpm run build

Database Rules

  • Use Prisma migrations for shared environments.
  • Do not use prisma db push on shared Neon databases.
  • Application queries use the pooled database URL.
  • Migrations use the direct database URL.
  • Money is stored as BigInt kobo values.
  • Ledger entries are append-only.

Dev Deployment Checklist

Use this checklist for dev-branch deployment verification only. This is not the production launch plan.

Current dev deployment targets:

  • Vercel deploys apps/web from the dev branch.
  • Render deploys apps/backend from the dev branch.
  • Use generated Vercel and onrender.com URLs only.
  • Do not configure custom domains yet.
  • Do not deploy from main for Twizrr yet; main still contains old Swifta state and is not production-ready for Twizrr.

Branch strategy:

  • Feature branches merge into dev.
  • Dev deployment verifies the integrated Twizrr app before promotion.
  • Pre-launch promotion remains: dev -> staging -> beta.
  • DNS and custom domains (twizrr.com, api.twizrr.com) wait until main is ready and the Hostinger/Vercel/Render domain setup is approved.

Deployment order:

  1. Merge to dev.
  2. GitHub Prisma migration workflow runs prisma migrate deploy against the dev Neon branch.
  3. Render backend deploy runs after migrations are applied.
  4. Vercel web deploy points to the Render dev backend URL.

Never run prisma db push or prisma migrate dev against shared environments.

Vercel dev web environment:

  • NEXT_PUBLIC_API_URL = generated Render dev backend URL.
  • NEXT_PUBLIC_PAYSTACK_PUBLIC_KEY = Paystack public test key for dev.
  • WEB_URL = generated Vercel URL or approved dev web URL.

Render dev backend environment:

  • DATABASE_URL = Neon pooled dev database URL.
  • DIRECT_URL = Neon direct dev database URL for Prisma migrations.
  • REDIS_URL = managed Redis protocol URL (redis:// or rediss://), not redis://localhost:6379 and not the Upstash REST HTTPS URL.
  • JWT_ACCESS_SECRET and JWT_REFRESH_SECRET, or the currently supported JWT fallback secret names.
  • PAYSTACK_SECRET_KEY, PAYSTACK_PUBLIC_KEY, and PAYSTACK_WEBHOOK_SECRET.
  • RESEND_API_KEY and email sender configuration.
  • CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, and CLOUDINARY_API_SECRET.
  • CORS_ORIGINS and FRONTEND_URL set to the generated Vercel dev URL.
  • Optional provider keys needed by the enabled dev flows, such as Google/Gemini AI, WhatsApp, Shipbubble, Prembly, Google Places, Africa's Talking, and admin bootstrap values.

Health check expectations:

  • Render uses /health for backend readiness.
  • /health checks both database and Redis availability.
  • The Render dev service will fail readiness if DATABASE_URL, DIRECT_URL, or managed Redis REDIS_URL is wrong or unreachable.
  • Keep /health as the dev Render health check unless the backend intentionally separates liveness from dependency readiness later.

Payment Rules

  • Every order is escrow-protected.
  • Paystack webhooks must be verified before order/payment state changes.
  • Store payouts happen only after shopper delivery confirmation or auto-confirmation.
  • Direct payment support is not part of the MVP.

Current Cleanup Status

The active MVP cleanup removed legacy supplier, RFQ, quote, trade-financing, waitlist, review, reorder, direct-payment, Sentry, Tier 3, and CAC flows from active source code. See TWIZRR_CLEANUP_REPORT.md for the detailed cleanup log.

Team

Built by codedDevs.

License

Proprietary. All rights reserved.