🛍️ AmarShop — Multi-Vendor E-Commerce Marketplace

A full‑featured, enterprise‑grade multi‑vendor marketplace platform built for the Bangladeshi e‑commerce ecosystem.
Admin dashboard · Seller center · Buyer experience · Real‑time operations · Production‑ready

---

📋 Table of Contents

• Overview
• Who Is This For
• Key Features
• Tech Stack
• Architecture
• Screenshots
• Getting Started
• Project Structure
• API Overview
• Security
• Deployment
• License

---

🌟 Overview

AmarShop (আমারশপ — "My Shop" in Bengali) is a complete multi‑vendor e‑commerce marketplace powering both buyers and sellers with a seamless, secure, and scalable platform. Built with modern web technologies, it supports the full lifecycle of an online transaction — from product discovery through checkout, payment, fulfillment, and post‑purchase support.

Whether you are launching a new marketplace in Bangladesh or modernising an existing one, AmarShop provides the foundation out of the box.

---

🎯 Who Is This For

Role	What They Get
🏪 Marketplace Owner	Full admin control, commission management, analytics, compliance tools
🛒 Buyers	Product search, cart, checkout (COD / bKash / Nagad / cards), order tracking, wishlist
📦 Sellers	Dedicated storefront, inventory management, order fulfillment, earnings dashboard
🔧 Developers	Clean REST API, real‑time WebSocket events, PostgreSQL with Prisma ORM, full Docker setup

---

✨ Key Features

👑 Admin Panel (/admin)

Module	Description
Dashboard	Real‑time revenue, orders, users, low‑stock alerts with trend charts
Products	Full CRUD, approval workflow, inventory tracking, category management
Orders	Lifecycle management, status updates, notes, filters
Users & Sellers	Role management (CUSTOMER / SELLER / ADMIN), KYC verification, store toggle
Payments	Transaction log, settlement reconciliation, method distribution
Marketing	Flash sales, coupons, banners — create, schedule, and track
CMS	Static pages, announcements, publishing workflow
Support	Ticket system with threaded replies, priority/status management
Finance	Revenue overview, settlement processing, tax reports, invoices
BI & Analytics	Executive metrics, RFM customer segmentation, cohort retention analysis
Roles & Permissions	Server‑side RBAC via @Roles() decorator
Real‑Time	Live activity feed, orders/min, system health

🧑‍💼 Seller Center (/seller)

• Dedicated store profile with branding
• Product management (add / edit / bulk upload)
• Order management and fulfillment
• Earnings and settlement tracking
• Inventory and stock alerts

🛍️ Buyer Experience

• Product browsing with category tree and search
• Shopping cart and checkout
• Multiple payment methods (COD, bKash, Nagad, SSLCommerz)
• Order history and tracking
• Address management and wishlist
• Product reviews and ratings

⚙️ Platform‑Wide

• JWT Authentication with access + refresh token rotation
• Role‑Based Access Control (CUSTOMER → SELLER → ADMIN → SUPER_ADMIN)
• Rate Limiting and request validation
• Redis Caching for high‑traffic endpoints
• WebSocket / SSE for real‑time features
• Audit Logging for admin actions
• Coupon engine with percentage / fixed / free‑shipping types

---

🛠️ Tech Stack

┌─────────────────────────────────────────────────────────┐
│                    FRONTEND (Next.js 16)                 │
│  React 19 · TypeScript · Tailwind CSS · Zustand         │
│  Material Symbols · next/navigation · Turbopack         │
├─────────────────────────────────────────────────────────┤
│                    BACKEND (NestJS 11)                   │
│  TypeScript · Prisma ORM · Passport JWT · class-validator│
│  WebSocket Gateway · Bull Queue · OpenTelemetry         │
├─────────────────────────────────────────────────────────┤
│                     DATABASE & CACHE                    │
│  PostgreSQL 16 · Redis 7 · Prisma Migrate               │
├─────────────────────────────────────────────────────────┤
│                    INFRASTRUCTURE                        │
│  Docker Compose · Nginx · S3 (CloudFront) · Sentry      │
│  Prometheus · Grafana · Loki · Jaeger                   │
└─────────────────────────────────────────────────────────┘

Category	Technology
Framework	Next.js 16 (App Router, Turbopack) + NestJS 11
Language	TypeScript (strict mode)
Database	PostgreSQL 16 with Prisma ORM
Cache	Redis 7
Auth	JWT (access 15m + refresh 7d with rotation)
Payments	bKash, Nagad, SSLCommerz, COD
Storage	AWS S3 + CloudFront CDN
Monitoring	OpenTelemetry, Sentry, Prometheus, Grafana
Container	Docker & Docker Compose
CI/CD	GitHub Actions ready

---

🏗️ Architecture

                         ┌──────────────┐
                         │   Browser     │
                         └──────┬───────┘
                                │ HTTPS
                         ┌──────▼───────┐
                         │   Next.js     │  SSR + Client Components
                         │   (Port 3000) │
                         └──────┬───────┘
                                │ API calls (/api/v1/*)
                         ┌──────▼───────┐
                         │   NestJS      │  REST + WebSocket
                         │  (Port 4000)  │
                         └──────┬───────┘
                    ┌───────────┼───────────┐
                    │           │           │
              ┌─────▼────┐ ┌───▼───┐ ┌────▼────┐
              │PostgreSQL│ │ Redis │ │   S3    │
              │  (5433)  │ │(6379) │ │ Storage │
              └──────────┘ └───────┘ └─────────┘

Key Design Decisions

• Backend global prefix: /api/v1 — all API routes are namespaced
• Client‑side route guards: Admin/Seller protection uses AuthGuard components (not middleware), because middleware can't read Zustand's localStorage‑persisted state
• Refresh token rotation: Each refresh issues a new token pair and invalidates the old one — limits window for token theft
• Separate JWT secrets: Access tokens and refresh tokens use different secrets with different expiry windows
• Sticky sidebar layout: Admin sidebar uses position: sticky with internal scroll — never disturbs the main content flow

---

📸 Screenshots

81 screenshots covering every page of the platform — admin panel, seller center, user experience, and more. All images are JPEG at 85% quality.

🏠 Home & Auth (4)

Page	Screenshot
Homepage
Login
Register

📦 Products & Categories (3)

Page	Screenshot
Categories
Category (Electronics)
Product Detail

🛒 Cart, Checkout & Orders (3)

Page	Screenshot
Shopping Cart
Checkout
Orders

👤 Account & Profile (4)

Page	Screenshot
Account Overview
Addresses
Wishlist
Settings

🛠️ Admin Dashboard & CRUD (14)

Page	Screenshot
Dashboard
Products
Orders
Users
Sellers
Categories
Payments
Coupons
Reviews
Banners
Flash Sales
CMS Pages
Affiliates
Creators

📊 Admin BI & Analytics (4)

Page	Screenshot
BI Dashboard
RFM Analysis
Cohort Analysis
Reports

💰 Admin Finance (4)

Page	Screenshot
Finance Dashboard
Settlements
Tax Reports
Invoices

🏭 Admin Warehouse (4)

Page	Screenshot
Warehouse Dashboard
Inbound Orders
Inventory
Pick Lists

📦 Admin Fulfillment (4)

Page	Screenshot
Fulfillment Dashboard
Courier Management
Pickup Management
Tracking

⚙️ Admin Settings & Misc (6)

Page	Screenshot
Real-Time Monitor
Reports
Roles & Permissions
Settings
Support Tickets
Compliance

🏪 Seller Center (13)

Page	Screenshot
Dashboard
Products
Add Product
Orders
Inventory
Finance
Analytics
Store Profile
Settings
Campaigns
Chat
AI Campaign Generator
AI Description Generator

🔗 Affiliate Portal (5)

Page	Screenshot
Dashboard
Analytics
Earnings
Tracking Links
Products

💻 Developer Portal (6)

Page	Screenshot
Dashboard
API Keys
Documentation
API Playground
Usage Analytics
Webhooks

🔔 Other Pages (8)

Page	Screenshot
Flash Sale
Notifications
Messages
Wallet
Help Center
Support Tickets
Live Chat
AI Assistant

---

🚀 Getting Started

Prerequisites

• Node.js ≥ 20
• pnpm (recommended) or npm
• Docker Desktop (for PostgreSQL + Redis)
• Git

1. Clone & Install

git clone https://github.com/your-org/amarshop.git
cd amarshop

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../src  # or root
npm install

2. Environment Variables

Copy the template file to .env in both the root and backend/ directories:

# Root (frontend)
cp .env.example .env

# Backend
cp .env.example backend/.env

Then edit each .env with your real values. See .env.example for all available variables.

Key variables to configure:

Variable	Default	Description
DATABASE_URL	postgresql://postgres:...	PostgreSQL connection string
JWT_SECRET	(required)	JWT signing secret — generate a strong random value
JWT_REFRESH_SECRET	(required)	JWT refresh secret — different from JWT_SECRET
NEXT_PUBLIC_API_URL	http://localhost:3001/api/v1	Backend API base URL (client‑safe)

3. Start Infrastructure

docker compose up -d postgres redis

4. Run Database Migrations

cd backend
npx prisma migrate dev
npx prisma generate

5. Seed Data (Optional)

cd backend
npx ts-node prisma/seed.ts
# or for products only:
npx ts-node prisma/seed-products.ts

6. Start Development

# Terminal 1 — Backend
cd backend
npm run start:dev

# Terminal 2 — Frontend
cd ..  # root
npx next dev --turbopack

7. Login Credentials

Role	Email	Password
Admin	admin@amarshop.com	admin123
Seller	seller@amarshop.com	seller123
Customer	customer@amarshop.com	customer123

---

📁 Project Structure

amarshop/
├── backend/                    # NestJS API server
│   ├── prisma/                 # Schema, migrations, seeds
│   │   ├── schema.prisma       # 97 tables
│   │   ├── seed.ts
│   │   └── seed-products.ts
│   └── src/
│       ├── modules/
│       │   ├── admin/          # Admin panel endpoints
│       │   ├── auth/           # JWT auth, roles guard
│       │   ├── bi/             # RFM, cohorts, analytics
│       │   ├── fulfillment/    # Shipments, couriers
│       │   ├── wms/            # Warehouse management
│       │   ├── finance/        # Settlements, invoices, tax
│       │   ├── compliance/     # KYC, disputes
│       │   └── realtime/       # WebSocket gateway
│       └── common/             # Guards, decorators, interceptors
│
├── src/                        # Next.js frontend
│   ├── app/
│   │   ├── admin/              # 30+ admin page routes
│   │   ├── seller/             # Seller dashboard routes
│   │   ├── account/            # User account pages
│   │   ├── auth/               # Login, register
│   │   ├── orders/             # Order tracking
│   │   ├── cart/               # Shopping cart
│   │   ├── checkout/           # Checkout flow
│   │   └── products/           # Product listing/detail
│   ├── components/             # Shared React components
│   │   ├── auth/               # AuthGuard, providers
│   │   └── layout/             # Header, footer, sidebar
│   ├── lib/
│   │   └── api/                # API client + admin helpers
│   ├── stores/                 # Zustand stores (auth, cart)
│   └── services/               # HTTP client, API wrapper
│
├── docker-compose.yml          # PostgreSQL, Redis, etc.
├── AGENTS.md                   # AI assistant instructions
└── README.md

---

📡 API Overview

All API routes are prefixed with /api/v1.

Auth

Method	Path	Description
POST	/auth/login	Email or phone + password
POST	/auth/register	Create account
POST	/auth/refresh	Rotate refresh token
POST	/auth/logout	Revoke refresh token
GET	/auth/profile	Current user

Admin (/admin/*)

Method	Path	Description
GET	/admin/dashboard	Stats + revenue chart
GET	/admin/products	Paginated product list
GET	/admin/orders	Orders with filters
GET	/admin/users	User management
GET	/admin/sellers	Seller + KYC status
GET	/admin/payments	Transaction log
GET	/admin/reviews	Review moderation
PUT	/admin/reviews/:id	Approve / hide / delete
GET	/admin/finance/dashboard	Revenue + settlements
GET	/admin/coupons	Coupon management
GET	/admin/banners	Banner management
GET	/admin/flash-sales	Flash sale campaigns
GET	/admin/support-tickets	Ticket list + detail
GET	/admin/analytics	BI analytics data
GET	/admin/reports/:type	Custom reports
GET	/admin/compliance	KYC + disputes overview
GET	/wms/dashboard/:id	Warehouse metrics
GET	/wms/stock-alerts/:id	Low‑stock alerts
GET	/bi/rfm-segments	RFM customer segments
GET	/bi/cohorts	Cohort retention data
GET	/fulfillment/courier-performance	Courier stats

---

🔒 Security

• JWT with refresh rotation — Access tokens expire in 15 minutes; refresh tokens (7 days) are rotated on each use and invalidated server‑side
• Role‑based guards — @Roles('ADMIN') decorator + RolesGuard on every protected route
• Rate limiting — Built‑in throttling to prevent abuse
• Input validation — class-validator + class-transformer on all DTOs
• Audit logging — Interceptor logs admin mutations
• API key scoping — Developer module supports scoped API keys
• HTTPS — Enforced in production via Nginx reverse proxy

⚠️ Secrets in Git History

WARNING: If you previously cloned or forked this repository before the secret-safety pass (July 2026), the following secrets may exist in your local git history and must be rotated immediately:

Secret	Previous Value	Files Affected
Database password	shawon12	backend/prisma/seed.ts, backend/prisma/seed-products.ts, backend/prisma/demo-seed.ts, backend/prisma.config.ts, backend/test/global-setup.ts, backend/src/common/prisma.service.ts
JWT fallback secret	your-secret-key-change-in-production	src/lib/auth/jwt.ts

Action required:

1. Rotate these secrets in production — the old values are compromised
2. Run git filter-branch or BFG Repo-Cleaner to purge them from your git history if this is a public repository
3. Any forks or clones should be re-cloned from the cleaned repository

See .env.example for all required environment variables.

---

🐳 Deployment

Docker Compose (Production)

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

This spins up:

• PostgreSQL 16 on port 5433
• Redis 7 on port 6379
• NestJS backend (compiled)
• Next.js frontend (standalone output)
• Nginx reverse proxy (optional)

Manual Deployment

# Build backend
cd backend
npm run build

# Build frontend
cd ..
npx next build

# Run with PM2 or systemd
pm2 start backend/dist/main.js --name amarshop-api
pm2 start node_modules/.bin/next --name amarshop-web -- start -p 3000

Environment Variables Required in Production

DATABASE_URL, REDIS_URL, JWT_ACCESS_SECRET, JWT_REFRESH_SECRET,
NEXT_PUBLIC_API_URL, S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY,
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS,
SSLCOMMERZ_STORE_ID, SSLCOMMERZ_STORE_PASSWORD,
BKASH_MERCHANT_NUMBER, BKASH_API_KEY,
NAGAD_MERCHANT_NUMBER, NAGAD_API_KEY,
SENTRY_DSN, OTEL_EXPORTER_OTLP_ENDPOINT

---

⚠️ Security: Secret Rotation Required

If you cloned or forked this repository, any secrets that were previously hardcoded still exist in git history, even if they've been moved to environment variables in the latest commit.

Immediately rotate the following if you've used this codebase:

• Database password (shawon12 was previously hardcoded)
• JWT signing secrets (amarshop-jwt-secret-2026-prod and amarshop-refresh-secret-2026-prod were previously hardcoded)
• Encryption key (amarshop-encryption-key-2026 was previously the fallback)

To purge secrets from git history, use BFG Repo-Cleaner or git filter-branch.

---

📄 License

MIT — See LICENSE for details.

---

AmarShop — Built with ❤️ for the Bangladeshi e‑commerce ecosystem.
Questions? Reach out via GitHub Issues.