twizrr

twizrr is a Nigerian social commerce marketplace for shoppers and store owners. Stores publish products and posts, shoppers discover items through the web app and WhatsApp, and every checkout is protected by twizrr Buyer Protection.

This repository is a pnpm/Turborepo monorepo with:

• apps/backend - NestJS API for auth, stores, products, orders, payments, delivery, notifications, WhatsApp, and admin operations.
• apps/web - Next.js App Router web app for the public landing site, shopper app, store workspace, and admin surfaces.
• packages/shared - shared TypeScript types, DTOs, and enums.

Requirements

• Node.js 20+
• pnpm
• PostgreSQL 16 with pgvector enabled
• Redis using a Redis protocol URL, redis:// or rediss://
• Provider accounts for the integrations you enable locally

Do not use npm or yarn for this repo.

Local Setup

Install dependencies from the repo root:

pnpm install

Start local infrastructure if you want Docker-managed services:

docker compose up -d postgres redis

Docker is optional for local development. You can also point local env files at managed PostgreSQL and Redis services.

Copy env examples and fill only local/dev values:

Copy-Item apps/backend/.env.example apps/backend/.env.local
Copy-Item apps/web/.env.example apps/web/.env.local

Do not commit .env.local or real secrets.

Environment Notes

Backend:

• DATABASE_URL is the pooled app connection string.
• DIRECT_URL is the direct database connection string for Prisma migrations.
• REDIS_URL must be redis://... or rediss://....
• Do not use Upstash REST https://... URLs as REDIS_URL.

Web:

• NEXT_PUBLIC_API_URL points to the backend API base URL.
• NEXT_PUBLIC_WEB_URL is the product-app web origin.
• NEXT_PUBLIC_MARKETING_URL is the public marketing origin.
• NEXT_PUBLIC_MARKETPLACE_ENABLED=false keeps unfinished app/marketplace routes gated on public pre-launch environments.

Use apps/backend/.env.example and apps/web/.env.example as the source for supported env names.

Database

Validate the schema:

cd apps/backend
pnpm exec prisma validate --schema=prisma/schema.prisma

Generate Prisma client:

cd apps/backend
pnpm exec prisma generate --schema=prisma/schema.prisma

Apply migrations to a shared/dev/staging/production database:

cd apps/backend
pnpm exec prisma migrate deploy --schema=prisma/schema.prisma

Use migrate dev only for local migration authoring. Never use db push for shared Twizrr environments.

Run Locally

Backend:

cd apps/backend
pnpm run dev

Web:

cd apps/web
pnpm run dev

Default local URLs:

• Web: http://localhost:3000
• Backend: http://localhost:4000
• Backend health: http://localhost:4000/health

Build

Build the full workspace from the repo root:

pnpm run build

Build only the backend and its workspace dependencies:

pnpm exec turbo run build --filter=@twizrr/backend...

Build only the web app and its workspace dependencies:

pnpm exec turbo run build --filter=@twizrr/web...

Using Turbo for filtered builds matters because shared packages must be compiled before dependent apps.

Deployment Model

Twizrr should stay deployment-provider-neutral. The codebase should not depend on one host-specific configuration file or one provider-specific runtime path.

Backend

Deploy apps/backend as a Node.js 20+ service that can run the NestJS API and the BullMQ processors required by the app.

Recommended generic backend lifecycle:

pnpm install --frozen-lockfile
pnpm exec turbo run build --filter=@twizrr/backend...
cd apps/backend
pnpm exec prisma migrate deploy --schema=prisma/schema.prisma
pnpm run start:prod

Backend host requirements:

• Runs Node.js 20+.
• Provides persistent process execution for the API.
• Provides environment variables securely.
• Connects to managed PostgreSQL and managed Redis.
• Exposes /health for readiness checks.
• Does not assume Redis is available at localhost in deployed environments.

If an HTTP serverless platform is used for the API, BullMQ workers still need a separate long-running worker process. Background queues should not rely on a short-lived serverless request lifecycle.

Frontend

Deploy apps/web as a Next.js 14 app.

Recommended generic web lifecycle:

pnpm install --frozen-lockfile
pnpm exec turbo run build --filter=@twizrr/web...

The same apps/web app can serve both public marketing and product-app domains by changing env values. Do not create a separate marketing repo or a separate marketing app unless the architecture changes explicitly.

Domains

• twizrr.com is the public marketing/information site.
• app.twizrr.com is the product app.
• api.twizrr.com points to the active backend API host.

The domain names are stable product boundaries; the infrastructure provider behind each domain can change.

Deployment Checklist

Before promoting a shared environment:

1. Confirm required env vars are present for backend and web.
2. Run Prisma migrations with migrate deploy.
3. Build with Turbo so workspace dependencies compile first.
4. Confirm backend /health is reachable.
5. Confirm Redis uses redis:// or rediss://.
6. Confirm CORS origins match the web domains for that environment.
7. Confirm no .env.local, real secrets, private prompt values, or private invite links are committed.

Validation

Common local checks:

pnpm run lint
pnpm run build
git diff --check

For backend-specific changes, also run:

cd apps/backend
pnpm run typecheck
pnpm exec prisma validate --schema=prisma/schema.prisma
pnpm exec prisma generate --schema=prisma/schema.prisma

For web-specific changes, also run:

cd apps/web
pnpm run typecheck
pnpm run build

Safety Rules

• Money is stored in kobo, never floating-point Naira values.
• Paystack webhooks must be verified before changing payment/order state.
• Delivery fees are not store revenue.
• Product and store uploads must follow the Cloudinary folder policy.
• WhatsApp is shopper-facing only; store management belongs in the web app.
• No real secrets, .env.local values, private prompt values, or private WhatsApp invite links should be committed.