API Documentation

This page displays the repository README as basic documentation.

# Gwenge - Multi-Vendor E-Commerce & Rental Platform

Gwenge (formerly Paira) is a comprehensive multi-vendor e-commerce and rental platform built with Node.js, Express, PostgreSQL, and Prisma. It enables businesses to create online stores, list products for sale or rent, and manage orders, bookings, and payments seamlessly.

## Features

### 🛍️ E-Commerce Functionality
- **Multi-Vendor Stores**: Businesses can create and manage their own online stores with custom branding
- **Product Management**: Upload products with images, descriptions, pricing, and stock management
- **Order Processing**: Complete order lifecycle from pending to delivered with status tracking
- **Tiered Verification**: Vendors can purchase Monthly (60,000 UGX) or Yearly (750,000 UGX) verification badges granting different perks (Gallery Promotions, Vendor Card, Search Priority)
- **Product Categories**: Organize products into hierarchical categories for easy navigation
- **Search & Filtering**: Advanced search and filtering by category, price, and availability

### 🏠 Rental Marketplace
- **Rental Products**: List items for rent with daily pricing and minimum rental periods
- **Booking System**: Customers can book items for specific dates with automatic availability checks
- **Rental Calendar**: Track bookings and manage rental schedules

### 💳 Payments & Withdrawals
- **PawaPay Integration**: Integrated with PawaPay for seamless mobile money payments (MTN/Airtel) across Africa
- **Automated Payouts**: Businesses receive automated payouts for completed orders
- **Withdrawal Management**: Track withdrawal requests and transaction history

### 🔐 Authentication & Security
- **Better Auth Integration**: Secure, modern authentication using Better Auth
- **Social Login**: Google OAuth integration
- **Role-Based Access**: Differentiated access for customers, vendors, and admins
- **Email Communications**: Integrated with Resend for transactional emails

## Tech Stack

### Backend
- **Node.js** - JavaScript runtime for server-side development
- **Express.js** - Web framework for building APIs
- **PostgreSQL** - Relational database management system
- **Prisma** - ORM for database management and migrations
- **Better Auth** - Comprehensive authentication solution
- **Cloudinary** - Image and media storage
- **PawaPay** - Mobile money payment gateway integration
- **Resend** - Email service
- **TypeScript** - Strongly typed JavaScript

### Frontend (Separate Repository)
- **Next.js / React.js** - React framework for building user interfaces
- **Tailwind CSS** - Utility-first CSS framework
- **Framer Motion** - Animation library

## Getting Started

### Prerequisites
- **Node.js** (v22 or higher recommended)
- **PostgreSQL** (v17 or higher)
- **npm** or **yarn**

### Installation

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd gwenge-multivendor-ecommerce-rental-backend
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Configure environment variables**
   Create a `.env` file in the root directory with the following variables:

   ```env
   # Application URLs
   APP_URL="http://localhost:3000"
   BACKEND_URL="http://localhost:4000"
   FRONTEND_URL="http://localhost:3000"

   # Database
   DATABASE_URL="postgresql://user:password@localhost:5432/database_name"

   # Better Auth Configuration
   BETTER_AUTH_SECRET="your-better-auth-secret"
   BETTER_AUTH_URL="http://localhost:4000"

   # Cloudinary Configuration
   CLOUDINARY_CLOUD_NAME="your-cloud-name"
   CLOUDINARY_API_KEY="your-api-key"
   CLOUDINARY_API_SECRET="your-api-secret"

   # Resend / Email Configuration
   RESEND_API_KEY="your-resend-api-key"
   FROM_EMAIL="noreply@gwengeug.com"
   SECURITY_EMAIL="security@gwengeug.com"
   COMPANY_NAME="Gwenge"
   ADMIN_EMAIL="admin@gwengeug.com"
   LOGO_URL="https://your-logo-url"

   # OAuth Configuration
   GOOGLE_CLIENT_ID="your-google-client-id"
   GOOGLE_CLIENT_SECRET="your-google-client-secret"

   # PawaPay Configuration
   PAWAPAY_ENV="sandbox" # or "production"
   PAWAPAY_API_TOKEN="your-pawapay-api-token"
   ```

4. **Sync the database schema**
   ```bash
   npx prisma db push
   ```

5. **Start the development server**
   ```bash
   npm run dev
   ```
   The server will start at `http://localhost:4000` (or the PORT you specify).

## API Endpoints (Prefix: `/api/v1`)

### Authentication (`/api/auth/*` handled by Better Auth)
- Managed by Better Auth via `/api/auth/...` (login, register, session, etc.)
- Additional custom auth routes available at `/api/v1/auth/`

### Users (`/api/v1/user`)
- User profile management, updating roles, etc.

### Stores (`/api/v1/store`)
- Create, read, update, delete stores
- `PUT /api/v1/store/toggle-verification` - Toggle vendor verification status (Admin only, sets 1-year verification by default)

### Products (`/api/v1/product`)
- CRUD operations for standard e-commerce and rental products
- Search and filtering capabilities

### Payments (`/api/v1/payment`)
- `POST /api/v1/payment/checkout` - Initiate standard checkout
- `POST /api/v1/payment/checkout/verification` - Pay for vendor verification plan (Monthly or Yearly) via PawaPay
- `POST /api/v1/payment/pawapay/callback/deposit` - PawaPay deposit webhook
- `POST /api/v1/payment/pawapay/callback/payout` - PawaPay payout webhook

### Cart & Favorites (`/api/v1/cart`, `/api/v1/favorites`)
- Manage user shopping cart and saved favorite items

### Reviews & Support (`/api/v1/review`, `/api/v1/support`)
- Product reviews, ratings, and customer support ticket handling

### Content & Blog (`/api/v1/content`, `/api/v1/blog`)
- Manage platform dynamic content and blog posts

### Store Posts (`/api/v1/store-post`)
- Manage social/promotional posts made by vendors for their stores

### Withdrawals (`/api/v1/withdrawal`)
- Request and track vendor revenue withdrawals