Campor
Verified campus marketplace for Redeemer's University students with escrowed payments, settlement codes, and real-time chat between buyers and sellers.
Project Overview
A secure, RUN-only campus marketplace with escrow-like payments, settlement codes, real-time chat, and powerful search to make buying and selling on campus safe and seamless.
Key Features
- Email-gated authentication with @run.edu.ng verification and role-based access (customer, seller, admin)
- Seller catalogue management with branded slugs, inventory, analytics, and export to CSV/XLSX
- Product listings with categories, ratings, and wishlist support
- Shopping cart and checkout with escrowed Paystack payments plus webhook validation
- Unique settlement code flow for on-campus exchanges and order finalization
- Real-time chat between buyers and sellers using Socket.IO
- Algolia-powered instant search with autocomplete and advanced filters
- AI assistant for product recommendations and support (OpenAI/Groq-backed)
- Newsletter broadcasts, notifications, and background jobs for orders, refunds, and transfers
- Admin dashboard for users, orders, sellers, products, and analytics
- Image uploads and optimization via Cloudinary
Challenges & Solutions
- Designing an escrow + settlement-code flow tailored to in-person campus meetups while keeping the experience simple for students
- Ensuring inventory consistency across multiple concurrent carts and checkouts so that overselling never occurs
- Securing Paystack integration, including webhook verification, refunds, and edge cases around failed or pending payments
- Scaling Socket.IO-based real-time chat and notifications while offloading heavy work to BullMQ workers
- Keeping Algolia search indexes in sync with product and inventory changes without hurting performance
System Architecture
Architecture Overview
Campor uses a modular, service-oriented architecture that connects a React SPA frontend to a TypeScript/Express API and a PostgreSQL database, with Redis-backed background workers and third-party integrations for payments, search, and media. The system is designed around safety (verified students only), transactional integrity (escrow and settlement codes), and real-time collaboration (chat and notifications).
Frontend Architecture (React + Vite)
The frontend is a single-page application built with React and Vite, structured around feature-focused pages and shared layout components.
Layouts & Navigation
- Main marketplace layout with navbar, footer, and mobile-friendly navigation
- Seller dashboard layout with sidebar, metrics, and management views
- Dedicated layouts for auth flows, chat, and legal pages (privacy, terms)
Core Feature Modules
Marketplace & Products: Landing page, category pages, product detail views, inventory indicators, and seller catalogues
Cart & Checkout: Cart drawer/page, checkout forms, settlement code confirmation modals, and payment verification screens
Chat: Conversation list, message threads, and order-contextual chat views using Socket.IO client
Seller Dashboard: Product CRUD, orders, analytics, wallet, customers, and settings pages
Search: Algolia InstantSearch widgets (search box, filters, sort, pagination) and autocomplete search boxes
Shared Infrastructure
Context Providers: Auth, Cart, Wishlist, and Chat contexts managing global state
UI Components: Buttons, modals, loaders, pagination, sliders, icons, and skeleton loaders built with Tailwind CSS and Framer Motion
Service Layer: Axios-based services for auth, products, cart, orders, payments, wallet, chat, and search, encapsulating API calls and error handling
Real-time: Socket.IO client service that manages a single shared connection and event subscriptions across the app
Backend Architecture (Node.js + Express + TypeScript)
The backend is a modular Express API written in TypeScript, organized into domain modules with controllers, services, repositories, validation, and documentation.
Core Modules
Auth: Registration, login, email verification (restricted to @run.edu.ng), password reset, and JWT-based session management with roles
Users & Sellers: Student profiles, seller onboarding, bank verification, seller catalogue management, and profile images
Products & Categories: Product CRUD, categories, ratings, reviews, inventory fields, and Cloudinary-backed images
Cart & Orders: Cart operations, order creation, reservation windows, settlement code generation, and order lifecycle management (pending, reserved, completed, expired, refunded)
Payments: Paystack integration for initializing transactions, verifying callbacks, handling webhooks, and processing refunds/failed payments
Chat: Conversation creation keyed by buyer/seller/order, message storage, and real-time event emission via Socket.IO
Referral & Challenges: Referral codes, XP tracking, and gamified challenge system for engagement
Admin: CRUD and management endpoints for users, orders, sellers, products, and broadcast operations (e.g., newsletters)
Infrastructure & Integrations
Database: PostgreSQL accessed via Prisma ORM with relations for users, sellers, products, orders, settlements, chats, and wallets
Queue & Workers: BullMQ + Redis workers handle background email notifications, expired order cleanup, transfer success handling, and refunds
Scheduled Jobs: Cron jobs trigger reservation cleanup and message notifications at defined intervals
Search: Algolia integration for indexing products and powering instant search and autocomplete on the frontend
Media: Cloudinary for image uploads, transformations, and URL delivery
Email: Nodemailer-based transactional emails for verification, order updates, settlements, and newsletters
AI: OpenAI/Groq-backed AI assistant for recommendations and support (optional module)
Observability: Winston with daily-rotate-file for logging and Datadog (dd-trace) for performance and error monitoring
Real-Time & Transaction Flow
Authentication & Verification
Student signs up with an @run.edu.ng email → verification email sent via Nodemailer → once confirmed, JWT tokens issued and role assigned (customer/seller/admin).
Product Discovery & Search
Products are indexed in Algolia when created/updated → frontend uses InstantSearch and autocomplete to provide sub-second search and filtering.
Cart, Orders, and Escrow
User adds items to cart → backend validates stock and pricing → on checkout, an order is created and a Paystack transaction is initialized. Paystack callback/webhook confirms payment → order moves into reserved/escrow state and a settlement code is generated for buyer and seller. On successful in-person exchange, settlement code is confirmed → order is marked completed and seller wallet is credited.
Settlement Code Lifecycle
Codes are time-bound and tied to specific orders → background jobs clean up expired reservations and update order status accordingly.
Real-time Chat & Notifications
Socket.IO namespaces/rooms connect buyers and sellers per order → messages and status updates (order changes, payment status) are pushed in real time.
Security & Reliability
Access Control: Role-based checks for customer/seller/admin routes with JWT verification middleware.
Data Validation: Joi-based validators on all critical input paths (auth, products, orders, payments).
Payment Security: Paystack secret keys stored in environment variables; webhook signatures verified and idempotent order updates enforced.
Resilience: Background processing with BullMQ, retry strategies for jobs, and cron-based cleanup for expired reservations.
Monitoring & Logging: Centralized logging with Winston and distributed tracing/metrics via Datadog.
Deployment Architecture
Backend: Containerized Express server deployed to Azure App Service, connected to Azure PostgreSQL and a managed Redis instance.
Frontend: React + Vite bundle deployed to Vercel with environment-configured API base URLs and SEO-optimized meta tags.
Supporting Services: Paystack for payments, Cloudinary for images, Algolia for search, SMTP provider for emails, and optional Groq/OpenAI APIs for AI features.