marketplace/docs/architecture.md

Architecture

High-Level Overview

┌──────────────────────────────────────────────────────────────┐
│                        Client (React)                        │
│                  http://localhost:5173 (Vite)                 │
│                                                              │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  ┌────────────┐  │
│  │  Pages   │  │Components│  │  Context   │  │  API Layer │  │
│  └──────────┘  └──────────┘  └───────────┘  └─────┬──────┘  │
│                                                    │         │
└────────────────────────────────────────────────────┼─────────┘
                   REST API (HTTP)  │    WebSocket   │
                                   │   (Socket.io)  │
┌──────────────────────────────────┼─────────────────┼─────────┐
│                       Server (Express)             │         │
│                   http://localhost:3000             │         │
│                                                    │         │
│  ┌───────────┐  ┌────────────┐  ┌──────────────┐  │         │
│  │ Middleware │  │   Routes   │  │  Socket.io   │◄─┘         │
│  │ (auth,    │  │ (REST API) │  │  (real-time) │            │
│  │  upload,  │  └─────┬──────┘  └──────┬───────┘            │
│  │  validate)│        │                │                     │
│  └───────────┘        │                │                     │
│                  ┌────┴────────────────┴──────┐              │
│                  │       Prisma ORM           │              │
│                  └────────────┬───────────────┘              │
│                               │                              │
└───────────────────────────────┼──────────────────────────────┘
                                │
┌───────────────────────────────┼──────────────────────────────┐
│                    PostgreSQL 17 (Docker)                     │
│              marketplace-postgres container                   │
│              Volume: marketplace-pgdata                       │
└──────────────────────────────────────────────────────────────┘

External Services:
  ┌─────────┐    ┌──────────────┐
  │  Stripe │    │ Google Maps  │
  │ (pay)   │    │ (location)   │
  └─────────┘    └──────────────┘

Client-Server Communication

REST API

The client communicates with the server via a JSON REST API. All endpoints are prefixed with /api/.

Prefix	Purpose
/api/auth	Registration, login, token refresh, logout
/api/users	User profiles, settings, privacy
/api/listings	CRUD for buy/sell listings, search, favorites
/api/offers	Create, counter, accept, decline offers
/api/chat	Conversations and message history
/api/notifications	Fetch and mark notifications as read
/api/payments	Stripe payment intents, webhooks
/api/location	Google Maps autocomplete proxy
/api/reports	Content/user reporting
/api/subscriptions	Seller subscription management
/api/promotions	Listing promotion/boost
/api/admin	Admin dashboard, user/listing management
/api/rentals	Rental listing CRUD and search
/api/bookings	Booking lifecycle management
/api/rental-payments	Rental payment processing and webhooks
/api/payouts	Landlord payout management
/api/rental-reviews	Tenant/landlord reviews
/api/health	Health check endpoint

Socket.io (WebSocket)

Socket.io provides the real-time communication layer. The server creates a Socket.io instance attached to the same HTTP server as Express.

Events flow:

• The client connects with an auth token after login
• The server authenticates the socket connection and associates it with a user
• Real-time events are emitted for: new messages, notifications (offers, bookings, moderation), typing indicators, and online status

Database Layer

Prisma ORM

The database schema is defined in server/prisma/schema.prisma. Prisma generates a type-safe client used throughout the server routes.

Key models:

Model	Purpose
User	Accounts with roles, privacy settings, landlord status
Session	JWT refresh token sessions
Listing	Buy/sell items with category, condition, price
ListingImage	Image attachments for listings
Offer	Price negotiation between buyer and seller
Conversation	Chat threads between two users
Message	Individual chat messages
Favorite	User bookmarks on listings
Notification	In-app notifications (19 distinct types)
Payment	Payment records (8 payment types)
Report	Content/user reports for moderation
Subscription	Seller tier subscriptions
PromotedListing	Boosted listing placements
ModerationLog	Audit trail for moderation actions
BlockedUser	User blocking relationships
RentalListing	Rental items (apartments, cars, bikes, etc.)
Booking	Rental booking with status lifecycle
RentalReview	Reviews for completed rentals
Payout	Landlord payout tracking

Enums

The schema uses PostgreSQL enums extensively for type safety:

• User roles: USER, MODERATOR, ADMIN, SUPER_ADMIN
• Listing categories: ELECTRONICS, FURNITURE, CLOTHING, HOME_GARDEN, SPORTS, BOOKS, GAMES, VEHICLES, OTHER
• Rental categories: APARTMENT, HOUSE, CAR, MOTORCYCLE, BICYCLE, EBIKE
• Booking status: PENDING -> CONFIRMED -> ACTIVE -> COMPLETED (or CANCELLED_* / REJECTED / EXPIRED)
• Cancellation policy: FLEXIBLE, MODERATE, STRICT

Authentication Flow

The application uses JWT-based authentication with access and refresh tokens.

┌────────┐                              ┌────────┐
│ Client │                              │ Server │
└───┬────┘                              └───┬────┘
    │  POST /api/auth/login                 │
    │  { email, password }                  │
    ├──────────────────────────────────────►│
    │                                       │ Verify password (bcryptjs)
    │                                       │ Generate access token (short-lived)
    │                                       │ Generate refresh token (long-lived)
    │                                       │ Store session in DB
    │  { accessToken, user }                │
    │  Set-Cookie: refreshToken (httpOnly)  │
    │◄──────────────────────────────────────┤
    │                                       │
    │  GET /api/listings                    │
    │  Authorization: Bearer <accessToken>  │
    ├──────────────────────────────────────►│
    │                                       │ auth middleware verifies JWT
    │                                       │ checkBanned middleware
    │  { listings: [...] }                  │
    │◄──────────────────────────────────────┤
    │                                       │
    │  POST /api/auth/refresh               │
    │  Cookie: refreshToken                 │
    ├──────────────────────────────────────►│
    │                                       │ Validate refresh token
    │                                       │ Issue new access token
    │  { accessToken }                      │
    │◄──────────────────────────────────────┤

Middleware Chain

Requests pass through several middleware layers:

1. helmet -- Security headers
2. cors -- Restricts origins to CLIENT_URL
3. cookieParser -- Parses refresh token cookies
4. express-rate-limit -- Rate limits auth endpoints (20 requests / 15 min)
5. auth -- Verifies JWT access token, attaches user to request
6. checkBanned -- Blocks banned users
7. requireRole -- Role-based access control (e.g., admin-only routes)
8. upload -- Multer file upload handling
9. validate -- Zod schema validation for request bodies

Payment Flow

Marketplace Payments (Listings)

Stripe PaymentIntents are used for buy/sell transactions:

┌────────┐       ┌────────┐       ┌────────┐
│ Buyer  │       │ Server │       │ Stripe │
└───┬────┘       └───┬────┘       └───┬────┘
    │  Create PI     │                │
    ├───────────────►│ POST /api/     │
    │                │ payments       │
    │                ├───────────────►│ stripe.paymentIntents.create()
    │                │  clientSecret  │
    │                │◄───────────────┤
    │  clientSecret  │                │
    │◄───────────────┤                │
    │                │                │
    │  Confirm (Stripe.js)           │
    ├────────────────────────────────►│
    │                │                │
    │                │  Webhook event │
    │                │◄───────────────┤ payment_intent.succeeded
    │                │  Update DB     │
    │                │  Notify seller │
    │                │                │

Rental Payments

Rental bookings follow a similar flow with additional handling for:

• Security deposits -- Held and refunded after completion
• Landlord payouts -- Via Stripe Connect (stripeAccountId on User model)
• Commissions -- Platform fee deducted from rental payments
• Separate webhook endpoint -- /api/rental-payments/webhook

Payment Types

The system tracks eight distinct payment types:

Type	Description
LISTING_FEE	Fee to publish a listing
COMMISSION	Platform commission on sales
PROMOTION	Listing boost/promotion fee
SUBSCRIPTION	Seller subscription payment
RENTAL_BOOKING	Tenant rental payment
RENTAL_COMMISSION	Platform fee on rentals
RENTAL_DEPOSIT	Security deposit hold
RENTAL_DEPOSIT_REFUND	Deposit refund after completion
RENTAL_PAYOUT	Payment to landlord via Connect

File Uploads

File uploads are handled by Multer with local disk storage.

• Configuration: server/src/middleware/upload.ts
• Storage directory: Configurable via UPLOAD_DIR env var (default: ./uploads)
• Serving: Static files served at /uploads/* via express.static
• Usage: Listing images, rental listing photos, user avatars

Files are stored on the local filesystem. In production, this should be replaced with cloud storage (e.g., S3, Cloudflare R2).

Real-Time Communication

Socket.io is configured in server/src/socket/index.ts and attached to the HTTP server alongside Express.

Connection Flow

1. Client establishes WebSocket connection after successful login
2. Server authenticates the connection using the JWT token
3. User is registered as "online" and associated with their socket ID

Event Types

Category	Events
Chat	New message, typing indicator, read receipts
Notifications	New offer, offer response, booking updates, payout status, moderation actions
Presence	User online/offline status

Architecture

Client A ──WebSocket──┐
                      ├──► Socket.io Server ──► Emit to Client B
Client B ──WebSocket──┘         │
                                │
                          ┌─────┴─────┐
                          │  Express   │
                          │  routes    │
                          │  can emit  │
                          │  via io    │
                          └───────────┘

Express routes access the Socket.io instance via app.get('io') to emit events from REST handlers (e.g., sending a notification when an offer is created via the REST API).

Security

Concern	Implementation
HTTP headers	Helmet (XSS, clickjacking, MIME sniffing)
CORS	Restricted to CLIENT_URL
Rate limiting	20 req/15 min on /api/auth/login and /register
Input validation	Zod schemas on all mutation endpoints
Password hashing	bcryptjs
Token storage	Refresh token in httpOnly cookie
Role-based access	requireRole middleware for admin/mod routes
User banning	checkBanned middleware on protected routes
Webhook verification	Stripe webhook signature verification

Deployment Considerations

Database

• Use a managed PostgreSQL service (e.g., AWS RDS, Supabase, Neon) in production
• Run npx prisma migrate deploy to apply migrations
• The Docker setup is intended for local development only

File Storage

• Replace local Multer storage with S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
• Update the upload middleware and static file serving accordingly

Environment

• Set strong, unique values for JWT_SECRET and JWT_REFRESH_SECRET
• Use production Stripe keys and configure webhook endpoints
• Set CLIENT_URL to the deployed frontend URL

Scaling

• Horizontal scaling: Socket.io requires a Redis adapter (@socket.io/redis-adapter) for multi-instance deployments
• Static assets: Serve the built React app via a CDN or reverse proxy (Nginx, Cloudflare)
• API: The Express server is stateless (JWT-based auth) and can be scaled horizontally behind a load balancer

Recommended Production Stack

                    ┌───────────┐
                    │   CDN /   │
                    │  Nginx    │
                    └─────┬─────┘
                          │
              ┌───────────┴───────────┐
              │                       │
     ┌────────▼─────┐      ┌─────────▼────────┐
     │ React Static │      │  Express API x N  │
     │   (built)    │      │  (load balanced)  │
     └──────────────┘      └────────┬──────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    │               │               │
             ┌──────▼──┐    ┌──────▼──┐    ┌───────▼──┐
             │PostgreSQL│    │  Redis  │    │ S3 / R2  │
             │(managed) │    │(sockets)│    │ (files)  │
             └──────────┘    └─────────┘    └──────────┘