v-property (Vhembe Listings MVP)

Next.js App Router + TypeScript + Tailwind + Prisma.

Environment

Create .env.local (never commit secrets):

DATABASE_URL="file:./dev.db"
ADMIN_PASSWORD="your-dev-admin-password"
AGENT_COOKIE_SIGNING_KEY="change-me-for-dev"
SEED_AGENT_EMAIL=""
SEED_AGENT_PASSWORD=""
GUIDE_AGENT_EMAIL=""
GUIDE_AGENT_PASSWORD=""
EMAIL_MODE="log"
EMAIL_FROM="no-reply@v-property.co.za"
RESEND_API_KEY=""
EMAIL_ADMIN_TO=""
STRIPE_SECRET_KEY=""
STRIPE_WEBHOOK_SECRET=""
STRIPE_PRICE_ID_BASIC=""

SEED_AGENT_EMAIL and SEED_AGENT_PASSWORD are optional. If both are set, npm run prisma:seed creates one demo agent portal user linked to the first seeded agent.

AGENT_COOKIE_SIGNING_KEY is required in production for agent session signing. The development fallback key is for local/dev/test use only.

Email notifications

• Set EMAIL_MODE="log" in local/dev to log outbound emails to the server console.
• Set EMAIL_MODE="resend" in production to deliver via Resend API.
• Required in production (EMAIL_MODE="resend"):
  • EMAIL_FROM
  • RESEND_API_KEY
• EMAIL_ADMIN_TO is used for general enquiries (no listingId).
• Public enquiries are always stored in the Lead table, and admins can review the latest submissions at /admin/leads.
• For controlled private beta, use /admin/leads as the fallback operational inbox whenever EMAIL_MODE="log" is active or a notification email fails.
• The lead inbox now shows lightweight operator counts and uses the audit log to track when listing enquiries are actioned and when general support enquiries are resolved.
• Ownership visibility in /admin/leads is derived from the latest admin handling event, so operators can see the current handler together with the latest recorded lead action and timestamp.
• /admin/leads now also shows age since received, age since last action, and a lightweight stale highlight for unresolved items that have had no activity for 24 hours or more.

Stripe subscriptions

• Set STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, and STRIPE_PRICE_ID_BASIC in .env.local.
• STRIPE_PRICE_ID_BASIC should match your Stripe recurring price for the BASIC plan.
• If STRIPE_PRICE_ID_BASIC is not set, seeding uses price_placeholder_basic so billing checkout is disabled until configured.

Optional local webhook forwarding with Stripe CLI:

stripe listen --forward-to localhost:3000/api/webhooks/stripe

Local dev database (SQLite)

• Default: DATABASE_URL="file:./dev.db"
• Prisma commands:
  • npm run prisma:generate
  • npm run prisma:migrate
  • npm run prisma:seed

Optional Postgres

Use a Postgres connection string in DATABASE_URL:

DATABASE_URL="postgresql://USER:PASSWORD@HOST:5432/DB_NAME?schema=public"

Then run:

npm run prisma:generate
npm run prisma:migrate

Local run

npm install
npm run prisma:generate
npm run prisma:migrate
npm run prisma:seed
npm run dev

Seller's Guide screenshots

For screenshot automation, set these in .env.local:

• GUIDE_AGENT_EMAIL
• GUIDE_AGENT_PASSWORD
• ADMIN_PASSWORD (optional; not used by the current capture script)

Run in two terminals:

# terminal 1
npm run dev

# terminal 2
npm run screenshots:guide

Screenshots are written to docs/guide-images/YYYY-MM-DD/.

Generate Seller's Guide PDF

npm run sellers-guide:pdf

• Output: docs/SELLERS_GUIDE.pdf
• If reportlab is missing, install it with:

pip install reportlab

• On Windows, the PDF script runs via py.

Admin (dev-only)

• URL: /admin/login
• Password: ADMIN_PASSWORD from .env.local
• This is a temporary dev-only gate and must be replaced by real auth before production.
• Live verification: npm run verify:admin-leads
• The admin leads verification writes disposable screenshot/trace artifacts under coverage/playwright/admin-leads-live/.

Vercel deployment notes

Set these environment variables in Vercel Project Settings:

• DATABASE_URL
• ADMIN_PASSWORD
• EMAIL_MODE
• EMAIL_FROM
• RESEND_API_KEY
• EMAIL_ADMIN_TO
• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET
• STRIPE_PRICE_ID_BASIC

Prisma migration strategy

Choose one approach:

1. Manual migration (recommended for control)

• Run npx prisma migrate deploy from CI or a release job before traffic switch.
• Keep Vercel build command focused on app build.

2. Build-time migration (small projects)

• Run migration before next build in your build command.
• Example: npx prisma migrate deploy && npm run build

Use npm run prisma:generate during build if your pipeline does not run postinstall.

Public beta checks

• Health endpoint: /api/health
• Sitemap: /sitemap.xml
• Robots: /robots.txt
• Rate limiting is currently in-memory (lib/rate-limit.ts) and best-effort for single-instance use; use a shared store in production.