homehunt-ng

HomeHunt NG — Nigerian property marketplace

A full-stack property listing platform for Nigeria: search and filter listings, view them on a map, request and pay for inspections (Paystack), with separate dashboards for landlords/agents, property seekers, and admins. “HomeHunt NG” and the logo are placeholders — change the name in components/Header.jsx, components/Footer.jsx, app/layout.js (and the contact details in Admin → Settings).

Stack: Next.js 14 (App Router) · Tailwind CSS · SQLite via better-sqlite3 (real relational schema) · JWT cookie sessions + bcrypt · Leaflet/OpenStreetMap · Paystack.

Quick start

npm install
cp .env.example .env.local      # then set AUTH_SECRET (openssl rand -base64 48)
npm run seed                    # creates tables + DEMO data (safe to re-run)
npm run dev                     # http://localhost:3000

Production: npm run build && npm start (Node 18+; a C/C++ toolchain is needed the first time for better-sqlite3).

Demo logins (password Password123!) — created by npm run seed

| Role | Email | |—|—| | Admin | admin@demo.homehunt.ng | | Property owner | owner@demo.homehunt.ng | | Agent | agent@demo.homehunt.ng | | Seeker | seeker@demo.homehunt.ng |

Demo properties are flagged is_demo = 1, show a Demo badge, and are never marked verified. Remove them with npm run seed:clear. Delete the demo accounts before going live.

Environment variables (.env.example)

| Variable | Purpose | |—|—| | AUTH_SECRET | Required in production. Signs session tokens. | | DATABASE_FILE | SQLite file path (use a persistent disk in production). | | PAYSTACK_SECRET_KEY / PAYSTACK_PUBLIC_KEY | Live payments. Server-side only. With no valid key the app runs a demo checkout so the flow can be tested. | | RESEND_API_KEY, EMAIL_FROM | Email provider (not yet wired — see below). | | TERMII_API_KEY | SMS/OTP provider (not yet wired). | | MAP_PROVIDER, NEXT_PUBLIC_MAPBOX_TOKEN | Map provider (OpenStreetMap works with no key). | | NEXT_PUBLIC_APP_URL | Public URL (payment callbacks, sitemap, SEO). |

Paystack: set your keys in the environment, and in the Paystack dashboard set the webhook URL to https://YOUR-DOMAIN/api/payments/webhook. Webhook signatures (HMAC-SHA512) are verified; confirmation is idempotent.

What’s implemented

• Auth: register (5 account types), login/logout, password reset, change password, bcrypt, httpOnly session cookie, email/phone OTP flow, role-based access enforced server-side in every route and page.
• Listings: 6-step form (basic → location with draggable map pin → amenities → photos → verification documents → preview), drafts, edit, delete; drag-and-drop photos, reorder, cover, client-side compression; video; location privacy (exact / approximate / hidden).
• Status workflow: Draft → Pending Review → Under Verification → Published / Rejected / Suspended / Expired. The Verified badge is admin-only and is cleared automatically if an owner edits a listing.
• Search: all 36 states + FCT, filters (type, purpose, price, beds, baths, parking, furnishing, amenities, verified-only), sorting, pagination, list/map view, natural-language queries (“3 bedroom flat in port harcourt under 3 million”), alias/spelling normalisation, mobile bottom-sheet filters, SEO location pages (/properties/lagos) only for places that have listings, sitemap + robots.
• Inspections & payments: admin-configurable fees, fee breakdown before payment, Paystack init/verify/webhook, unique references, notifications to both parties, reschedule flow, full status set.
• Privacy: landlord phone/email are never exposed; in-app messaging instead.
• Dashboards: responsive HomeHunt NG member dashboard for owners, agents, managers, developers, and seekers, plus an admin console (users, properties, inspections, payments + refunds, verification queue, reports/disputes, settings, stats, most-searched, most-viewed). Members can permanently delete their account after typing DELETE; admin actions are audit-logged.
• Safety: report listing, admin suspend, rate limiting (login/register/reset/OTP/upload), upload validation (MIME + magic bytes + size; extension derived from MIME), security headers, in-app notifications.
• Database: 19 tables with foreign keys and indexes on location, price, type, purpose, bedrooms, status, created date (lib/db.js).

Tested (manual API checks against the running app + production build)

Registration (validation, duplicates), login/logout, favourites persisting across logout/login, listing create → submit → admin approve → verify, edit-triggers-re-review, ownership protection (403), seeker blocked from admin/landlord APIs and pages, upload validation (bad type, disguised HTML, unauthenticated), rate limiting (429), search and natural-language query, inspection request → payment init → verify → replayed webhook (idempotent) → confirmed → reschedule notification, admin stats, reports, next build, production server responses, SEO metadata. Not tested: live Paystack, real email/SMS, real-device mobile layouts (built responsive, not device-tested), load/performance.

Not finished / needs your action before launch

• Email & SMS delivery are not wired. Notifications are in-app; password-reset links and OTP codes are shown/logged in demo mode. Implement sending in lib/notify.js, app/api/auth/forgot-password, app/api/account/verify.
• Live Paystack was not tested (no keys/network in the build environment). Test with Paystack test keys first. Refunds currently only update our records — call Paystack’s refund API in app/api/admin/payments/[id].
• Flutterwave / Mapbox / Google Maps appear as admin settings but only Paystack + OpenStreetMap are implemented.
• Uploads go to local disk (public/uploads). For multi-server hosting, move to S3/Cloudinary (app/api/upload/route.js). No server-side resizing (compression is in the browser).
• SQLite suits a single server with a persistent disk. Serverless hosts (e.g. Vercel) won’t persist it — use a VPS/Render/Railway, or port lib/db.js to Postgres.
• Rate limiting is in-memory (per instance) — use Redis for multiple instances.
• Search is SQL LIKE with aliases: fine for thousands of listings; add Meilisearch/Typesense at larger scale.
• Not built: featured/listing-fee checkout (settings and is_featured exist), subscriptions, radius search, geocoding of typed addresses, admin per-listing detail page, saved-property alerts, document malware scanning, automated test suite.
• Legal pages are templates. Have a Nigerian lawyer review Terms, Privacy (NDPA 2023), Refund and Listing Rules, and confirm tax/CAC/consumer-protection obligations. Nothing here is legal advice.