# 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)  │
             └──────────┘    └─────────┘    └──────────┘
```
