marketplace/docs/README.md

Marketplace

A full-stack online marketplace and rental platform where users can buy, sell, and rent items ranging from electronics and furniture to apartments, cars, and bicycles. The platform includes real-time chat, an offer/negotiation system, Stripe-powered payments, and a multi-role admin panel with content moderation.

Tech Stack

Layer	Technology
Client	React 19, TypeScript, Tailwind CSS 4, Vite 6
Routing	React Router 7
Server	Express 4, TypeScript, tsx (dev runner)
Database	PostgreSQL 17 (Docker), Prisma ORM 6
Auth	JWT (access + refresh tokens), bcryptjs
Payments	Stripe (PaymentIntents, Connect, Webhooks)
Real-time	Socket.io 4 (notifications, chat)
File Upload	Multer (local storage)
Validation	Zod
Charts	Recharts 3 (admin dashboard)
Icons	Lucide React

Features

• Listings -- Create, browse, search, and filter buy/sell listings across categories (Electronics, Furniture, Clothing, Vehicles, etc.)
• Offers & Negotiation -- Make offers, counter, accept, or decline with real-time notifications
• Rentals -- Full rental system for apartments, houses, cars, motorcycles, bicycles, and e-bikes with daily/monthly pricing, booking management, deposits, and cancellation policies
• Chat -- Real-time messaging between buyers/sellers and tenants/landlords via Socket.io
• Payments -- Stripe integration for listing fees, commissions, rental bookings, deposits, and landlord payouts via Stripe Connect
• Subscriptions & Promotions -- Tiered seller subscriptions (Basic, Pro, Business) and listing promotion/boosting
• Notifications -- Real-time in-app notifications for offers, messages, bookings, payouts, and moderation actions
• Moderation -- Content reporting, review queue, user banning, and moderation logs
• Admin Panel -- Dashboard with analytics, user management, listing management, and moderation tools
• Auth & Roles -- JWT authentication with four roles: USER, MODERATOR, ADMIN, SUPER_ADMIN
• Location -- Google Maps autocomplete for listing and rental locations

Prerequisites

• Node.js >= 18
• npm >= 9 (uses npm workspaces)
• Docker (for PostgreSQL)

Getting Started

1. Start the Database

If the Docker container already exists:

docker start marketplace-postgres

If you need to create it from scratch:

docker run -d \
  --name marketplace-postgres \
  -e POSTGRES_USER=marketplace \
  -e POSTGRES_PASSWORD=marketplace_dev \
  -e POSTGRES_DB=marketplace \
  -p 5432:5432 \
  -v marketplace-pgdata:/var/lib/postgresql/data \
  --restart unless-stopped \
  postgres:17-alpine

Verify it is running:

docker ps -f name=marketplace-postgres

2. Install Dependencies

From the project root:

npm install

This installs dependencies for both the client and server workspaces.

3. Configure Environment Variables

Create server/.env:

DATABASE_URL=postgresql://marketplace:marketplace_dev@localhost:5432/marketplace
JWT_SECRET=your-secret-key
JWT_REFRESH_SECRET=your-refresh-secret-key
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
GOOGLE_MAPS_API_KEY=your-google-maps-key
CLIENT_URL=http://localhost:5173
UPLOAD_DIR=./uploads
PORT=3000

For local development, only DATABASE_URL is strictly required. Stripe keys are optional (payment features will be disabled). The server provides sensible defaults for all other values.

4. Set Up the Database Schema

cd server
npx prisma db push

Or use migrations:

cd server
npx prisma migrate dev

5. Seed the Database (Optional)

cd server
npx tsx prisma/seed.ts

6. Run the Application

Start both client and server simultaneously:

npm run dev

Or run them separately:

npm run dev:server   # Express API on http://localhost:3000
npm run dev:client   # React app on http://localhost:5173

Seed Data

After seeding, the following test users are available (all use password password123):

Email	Name
alice.chen@example.com	Alice Chen
bob.smith@example.com	Bob Smith
carol.jones@example.com	Carol Jones
david.wilson@example.com	David Wilson
eva.martinez@example.com	Eva Martinez

Project Structure

marketplace/
├── package.json              # Root workspace config
├── CLAUDE.md                 # Dev notes (DB setup, commands)
├── docs/                     # Documentation
│   ├── README.md             # This file
│   └── architecture.md       # Architecture overview
├── client/                   # React frontend
│   ├── package.json
│   └── src/
│       ├── api/              # API client functions
│       ├── components/       # Reusable UI components
│       ├── context/          # React context providers
│       ├── pages/            # Route page components
│       ├── router.tsx        # Route definitions
│       ├── types/            # TypeScript type definitions
│       ├── utils/            # Utility functions
│       ├── App.tsx           # App root component
│       └── main.tsx          # Entry point
└── server/                   # Express backend
    ├── package.json
    ├── prisma/
    │   ├── schema.prisma     # Database schema
    │   └── seed.ts           # Seed script
    └── src/
        ├── config/           # Environment config
        ├── middleware/        # Auth, upload, validation, error handling
        ├── routes/           # API route handlers
        │   └── admin/        # Admin-specific routes
        ├── socket/           # Socket.io setup and handlers
        ├── utils/            # Shared utilities
        ├── validators/       # Zod validation schemas
        └── index.ts          # Server entry point

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_URL	Yes	localhost connection string	PostgreSQL connection URL
PORT	No	3000	Server port
JWT_SECRET	No*	Dev fallback	Access token signing secret
JWT_REFRESH_SECRET	No*	Dev fallback	Refresh token signing secret
CLIENT_URL	No	http://localhost:5173	CORS allowed origin
UPLOAD_DIR	No	./uploads	File upload directory
STRIPE_SECRET_KEY	No	Empty (payments disabled)	Stripe secret key
STRIPE_PUBLISHABLE_KEY	No	Empty (payments disabled)	Stripe publishable key
STRIPE_WEBHOOK_SECRET	No	Empty	Stripe webhook signing secret
GOOGLE_MAPS_API_KEY	No	Dev key	Google Maps API key

*Must be set to secure values in production.

Useful Commands

Command	Description
npm run dev	Start client + server concurrently
npm run dev:client	Start React dev server (port 5173)
npm run dev:server	Start Express dev server (port 3000)
npm run build	Build client and server for production
npm run lint	Lint client code
npx prisma studio	Open Prisma Studio (DB browser)
npx prisma db push	Push schema changes to database
npx prisma migrate dev	Create and apply a migration
npx tsx prisma/seed.ts	Seed the database