https://github.com/paulkabzz/multivendor-ecommerce

A full-stack multivendor e-commerce platform built with React, TypeScript, PostgreSQL, and Azure Functions. Will support vendor registration, product management, and secure checkout.
https://github.com/paulkabzz/multivendor-ecommerce

ecommerce postgresql serverless typescript

Last synced: about 1 month ago
JSON representation

A full-stack multivendor e-commerce platform built with React, TypeScript, PostgreSQL, and Azure Functions. Will support vendor registration, product management, and secure checkout.

• Host: GitHub
• URL: https://github.com/paulkabzz/multivendor-ecommerce
• Owner: paulkabzz
• License: mit
• Created: 2025-05-17T21:54:55.000Z (about 1 year ago)
• Default Branch: main
• Last Pushed: 2025-11-21T08:33:24.000Z (7 months ago)
• Last Synced: 2026-02-05T21:35:51.799Z (5 months ago)
• Topics: ecommerce, postgresql, serverless, typescript
• Language: TypeScript
• Homepage:
• Size: 45.3 MB
• Stars: 6
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Multivendor Ecommerce Store

A full-stack multivendor ecommerce platform built with modern technologies for scalability and performance.

## Tech Stack

**Frontend:**

- React.js with TypeScript

- Vite for development and build tooling

**Backend:**

- Azure Functions

- Node.js with TypeScript

- Prisma ORM

**Database:**

- PostgreSQL

- Docker containerisation

- Flyway for database migrations

## Prerequisites

Before running the application, ensure you have these installed:

- [Docker Desktop](https://www.docker.com/products/docker-desktop/)

- [Node.js](https://nodejs.org/en/download) (v16 or higher recommended)

- Git

## Getting Started

### 1. Clone the Repository

```bash

git clone https://github.com/paulkabzz/multivendor-ecommerce.git .

```

### 2. Database Setup

#### Create Environment File

Create `.env` in the `docker/` directory with the following content:

```env

POSTGRES_USER=ecommerce_user

POSTGRES_PASSWORD=your_secure_password_here

POSTGRES_DB=ecommerce

```

**⚠️ Important:** Replace `your_secure_password_here` with a strong password of your choice.

#### Start the PostgreSQL Container

```bash

make psql

```

This command starts the PostgreSQL container with your specified configuration.

#### Verify Container is Running

```bash

docker ps

```

Look for your PostgreSQL container in the output and note the container name.

### 3. Database Configuration

#### Connect to PostgreSQL

```bash

docker exec -it  psql -U ecommerce_user -d ecommerce

```

**Note:** Replace `` with the actual container name from the previous step.

#### Set Default Schema

Once connected to PostgreSQL, run:

```sql

ALTER ROLE ecommerce_user SET search_path TO ecommerce;

```

Exit PostgreSQL:

```sql

\q

```

### 4. Database Migration Setup

#### Create Flyway Password File

In the `database` directory, create a file named `priv`:

```bash

cd database

echo "export FLYWAY_PASSWORD=your_secure_password_here" > priv

```

**Note:** Use the same password from your Docker `.env` file.

#### Run Database Migrations

**⚠️ Note:** When using `make` commands, make sure you are in the same directory as the `Makefile`

```bash

make migrate

```

#### Generate Prisma Schema

```bash

make prisma

```

### 5. Verify Database Setup

Connect to the database again:

```bash

docker exec -it  psql -U ecommerce_user -d ecommerce

```

List all tables to verify setup:

```sql

\dt

```

You should see the ecommerce tables listed. Exit when done:

```sql

\q

```

## API Setup

### 1. Navigate to API Directory

```bash

cd api

```

### 2. Install Dependencies

```bash

npm install

```

### 3. Configure Environment Variables

Create a `.env` file in the `api` directory:

```env

DATABASE_URL="postgresql://ecommerce_user:your_secure_password_here@localhost:5433/ecommerce?schema=ecommerce"

JWT_SECRET=your_jwt_secret_here

GMAIL_USER=your_gmail@gmail.com

GMAIL_APP_PASSWORD=your_gmail_app_password

```

#### Generate JWT Secret

```bash

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

```

Copy the generated string and use it as your `JWT_SECRET`.

#### Gmail Setup (for email notifications)

- Enable 2-factor authentication on your Gmail account

- Generate an App Password in your Google Account settings

- Use your Gmail address for `GMAIL_USER`

- Use the generated App Password for `GMAIL_APP_PASSWORD`

### 4.  Appwrite Cloud Setup

If you’re a student, you can get the **\$15/month Appwrite Cloud tier for free** using the [GitHub Student Developer Pack](https://education.github.com/pack):

#### Claiming the Free Student Tier

1. Go to [education.github.com/pack](https://education.github.com/pack).

2. Click **“Get Student Benefits”** and log in or create a GitHub account.

3. Verify your student status using your university email or student ID.

4. Once approved:

   * Search for the **Appwrite** offer under the benefits.

   * Click to redeem the offer (you’ll either receive a promo code or an automatic upgrade).

   * Alternatively, just sign in to [Appwrite Cloud](https://cloud.appwrite.io/) with your GitHub account that is linked to the student pack.

### 🗂 Creating Buckets in Appwrite Cloud

After setting up your account and project:

1. **Go to the [Appwrite Console](https://cloud.appwrite.io/console)**.

2. Select your existing project or create a new one (under GitHub Student Organization if you're using the free tier as a student).

3. From the left sidebar, go to **Storage → Buckets**.

4. Click **“Create Bucket”** and create these buckets:

   * `products`

   * `departments`

   * `user_avatar`

   * `store_avatar`

5. After creating each bucket:

   * Click the bucket name to open its settings.

   * Under **Permissions**, click **“Add Role”**, select **Any**, and check the **Read** permission (this enables public read access).

   * Scroll down to **Allowed File Extensions** and add:

     * `jpg`, `png`, `svg`

     * *(Optional, but recommended)*: `jpeg`, `webp`, `gif`, etc.

### 🔑 Setting Up Environment Variables

Once your buckets are created, gather the following details from the Appwrite Console and add them to your `.env` file inside the `api` directory:

```env

APPWRITE_ENDPOINT=

APPWRITE_PROJECT_ID=

APPWRITE_API_KEY=

APPWRITE_USER_AVATAR_BUCKET_ID=

APPWRITE_VENDOR_AVATAR_BUCKET_ID=

APPWRITE_PRODUCTS_BUCKET_ID=

APPWRITE_DEPARTMENT_BUCKET_ID=

```

#### Where to Find Each Variable:

| Variable               | How to Find It                                                                                       |

| ---------------------- | ---------------------------------------------------------------------------------------------------- |

| `APPWRITE_ENDPOINT`    | Go to **Project → Settings → API credentials → API Endpoint**                                                          |

| `APPWRITE_PROJECT_ID`  | Go to **Project → Settings → API credentials → Project ID**                                                  |

| `APPWRITE_API_KEY`     | Go to **Project → Overview → API Keys → Create API Key** with required permissions (e.g. Storage: Read + Write) |

| `APPWRITE_*_BUCKET_ID` | Go to **Storage → Buckets**, click a bucket, and copy the **Bucket ID** from the top of the page     |

### 5. Start the Azure App.

```bash

npm run start

```

## Frontend Setup

### 1. Open New Terminal

Keep the API server running and open a new terminal window.

### 2. Navigate to Client Directory

```bash

cd client

```

### 3. Install Dependencies

```bash

npm install

```

### 5. Start Development Server

```bash

npm run dev

```

You should see output similar to:

```

➜  client git:(develop) npm run dev

> client@0.0.0 dev

> vite

  VITE v6.3.5  ready in 214 ms

  ➜  Local:   http://localhost:5173/

  ➜  Network: use --host to expose

  ➜  press h + enter to show help

```

### 5. Access the Application

Open your browser and navigate to `http://localhost:5173/`

## 📝 Writing SQL and Migrations

When making changes to the database schema, follow these steps:

### 1. Create Migration File

Create a new file in the `migrations` folder following Flyway's naming convention:

```

V__description_of_changes.sql

```

**Example:** `V7__create_blog_table.sql`

- Version: 7

- Description: Creating a blog table

### 2. Write Your SQL

Add your SQL commands to the migration file:

```sql

-- V7__create_blog_table.sql

CREATE TABLE IF NOT EXISTS Blog (

    blog_id UUID UNIQUE NOT NULL PRIMARY KEY DEFAULT uuid_generate_v4(),

    title VARCHAR(255) NOT NULL,

    content TEXT,

    user_id UUID,

    FOREIGN KEY(user_id) REFERENCES Users(user_id),

    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,

    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP

);

```

### 3. Apply Migration

Run the migration to update your database:

```bash

make migrate

```

This command will:

- Execute your new migration

- Update the database schema

- Create the new version in Flyway's schema history

### 4. Update Prisma Schema

After applying the migration, regenerate the Prisma schema:

```bash

make prisma

```

This ensures your Prisma client stays in sync with the database schema.

### Migration Best Practices

- Always test migrations on a development database first

- Use descriptive names for your migration files

- Include rollback instructions in comments when applicable

- Never modify existing migration files once they're applied

## Database Management Tools

### Command Line (psql)

```bash

docker exec -it  psql -U ecommerce_user -d ecommerce

```

### GUI Options

#### DBeaver

Click the **Create New Database Connection** button, choose **PostgreSQL** and connect using the following:

- **Host:** localhost

- **Port:** 5433

- **Database:** ecommerce

- **Username:** ecommerce_user

- **Password:** [your password from `.env`]

#### Prisma Studio

From the `/api` directory:

```bash

npx prisma studio

```

## Docker Container Management

### View Running Containers

```bash

docker ps

```

### Stop Container

```bash

docker stop 

```

### Start Existing Container

```bash

docker start 

```

### Remove Container (⚠️ This deletes all data)

```bash

docker rm 

```

### View Container Logs

```bash

docker logs 

```

## 🔍 Troubleshooting

### Common Issues

#### Port Already in Use

If port 5433 is already in use:

```bash

# Find process using the port

lsof -i :5433

# Kill the process

kill -9 

```

#### Container Won't Start

```bash

# Check Docker logs

docker logs 

# Remove and recreate container

docker rm 

make psql

```

#### Database Connection Issues

1. Verify container is running: `docker ps`

2. Check environment variables in both `.env` files

3. Ensure passwords match between Docker and API configurations

#### Prisma Issues

```bash

# Reset Prisma client

cd api

npx prisma generate

# Reset database (⚠️ destroys data)

npx prisma db push --force-reset

```

## Development Notes

- The database runs on port `5433` to avoid conflicts with local PostgreSQL installations

- Both frontend and backend support hot reloading during development

- Database schema changes should be managed through Flyway migrations

- Always use the `ecommerce` schema for database operations

## Support

If you encounter any issues or need help getting the application running, please:

1. Check the troubleshooting section above

2. Search existing issues in the repository

3. Create a new issue with detailed information about the problem

4. Contact the me via email

---