Live Link: Production Deployment
API Documentation (Swagger): Swagger UI
(Note: Deployed under the domain shazan-ad-marketplace-project for hosting, serving as the core API server for the Finn application).
A comprehensive, enterprise-ready marketplace and auction platform backend built with NestJS, Prisma, PostgreSQL, Stripe, and Socket.io. Finn enables dual listing models (fixed-price and time-based bidding), real-time user messaging, Stripe Connect seller integration, automatic platform fee splitting, and seller subscription memberships.
- Secure Authentication: JWT-based authentication with OTP verification using Gmail SMTP (Nodemailer).
- Dual Price Model: Set fixed prices or activate time-bound auctions (with support for start, end, base, and release pricing).
- Real-time Messaging: Socket.io-driven bi-directional messaging with conversation blocking, attachment handling, and unread counts.
- Stripe Connect Integration: Links sellers' Stripe accounts to process purchases with automatic 10% platform fee settlements and 90% payouts.
- Subscribers & Boosts: Subscription plans governing listings limits and premium packages (e.g. Gold Boost) to promote items.
- Structured Feedback: Threaded user reviews and comment branches on marketplace listings.
- Geo-Tagging: Geospatial coordinate tracking (latitude & longitude) for location-based listing searches.
- API Exploration: Interactive API documentation generated dynamically via Swagger.
- Framework: NestJS (TypeScript)
- Database: PostgreSQL
- ORM: Prisma ORM
- Payments: Stripe SDK
- Websockets: Socket.io (Real-time gateway/polling)
- Image Management: Cloudinary API (Multer Storage Integration)
- Emailing: Nodemailer
├── src/
│ ├── auth/ # JWT & Register/Login authentication module
│ ├── users/ # User profiles and access security
│ ├── sellers/ # Seller profiles, onboarding, and Stripe linking
│ ├── ads/ # Listing management (Fixed/Auction models)
│ ├── bids/ # Bids and highest-bid resolver for auctions
│ ├── payments/ # Stripe checkout, webhook handler, and fee math
│ ├── messages/ # Conversations and Message history
│ ├── comments/ # Listing reviews and nested comment threads
│ ├── categories/ # Categories & sub-categories (with custom specification schemas)
│ ├── mail/ # Mail services (Nodemailer wrappers)
│ └── common/ # Shared guards, decorators, exceptions, and utilities
├── prisma/
│ ├── schema.prisma # Main database schema file
│ └── migrations/ # Automatic SQL migration history files
├── docs.md/ # Detailed documentation guides
└── package.json # Modules, build scripts, and engine parameters
Verify that you have these installed:
- Node.js (v16.0.0 or higher)
- PostgreSQL database server running
- npm
npm installCopy the example file and configure it with your credentials:
cp .env.example .env
# Edit .env with your system configurations.(Reference the Environment Variables Guide for details on setting up Stripe, Cloudinary, and Nodemailer secrets).
Initialize tables in your PostgreSQL database instance:
npx prisma migrate dev --name initStart the server in Development mode with hot-reloading:
npm run start:devThe server will start, checking endpoints on http://localhost:3000.
Additional backend development manuals are available in docs.md:
- 📄 Setup Guide: Detailed step-by-step local preparation guide.
- 📄 Database Relationships: Prisma schema overview, database rules, and Entity-Relationship models.
- 📄 Environment Variables: Details of all required keys (Stripe, Cloudinary, Nodemailer, etc.).
- 📄 API Reference Documentation: Exhaustive JSON request/payload references for all REST routes.
- 📄 Contributing Guidelines: Git conventions, branch naming structure, linting rules, and tests.
Proprietary - All rights reserved. Registered by Shariyer Shazan.