A modern, scalable e-commerce platform built with microservices architecture using Turborepo for monorepo management. This project demonstrates best practices for building distributed systems with separate concerns for products, orders, payments, and administration.
This monorepo consists of multiple services and applications, each handling specific business domains:
- Client (
apps/client): Customer-facing Next.js application for browsing products, managing cart, and checkout - Admin (
apps/admin): Administrative dashboard for managing products, categories, and orders
- Product Service (
apps/product-service): REST API for product and category management using Express.js - Order Service (
apps/order-service): Order processing service using Fastify - Payment Service (
apps/payment-service): Stripe payment processing with webhooks using Hono
- Types (
packages/types): Shared TypeScript interfaces and schemas - BullMQ (
packages/bullmq): Background job processing for Stripe operations - Product DB (
packages/product-db): Prisma ORM for PostgreSQL product database - Order DB (
packages/order-db): Mongoose ODM for MongoDB order database - ESLint Config (
packages/eslint-config): Shared linting configuration - TypeScript Config (
packages/typescript-config): Shared TypeScript configuration
- Product catalog with categories, sizes, colors, and images
- Shopping cart with persistent state
- Secure checkout with Stripe integration
- User authentication via Clerk
- Order history and tracking
- Responsive design with Tailwind CSS
- Product management (CRUD operations)
- Category management
- Order overview and management
- Dashboard with analytics
- Image upload and management
- Real-time data updates
- Asynchronous job processing with BullMQ
- Stripe webhook handling for payment confirmations
- Database migrations with Prisma
- Type-safe APIs with Zod validation
- Background job queues for Stripe product sync
- Monorepo tooling with Turborepo
- Comprehensive backend testing with Vitest
- Next.js 15 - React framework with App Router
- React 19 - UI library
- TypeScript - Type safety
- Tailwind CSS - Styling
- Zustand - State management
- React Hook Form - Form handling
- Clerk - Authentication
- Stripe Elements - Payment UI
- Express.js - REST API framework
- Fastify - High-performance web framework
- Hono - Lightweight web framework for payments
- Prisma - Database ORM
- Mongoose - MongoDB ODM
- BullMQ - Job queue system
- Vitest - Fast unit and integration testing
- Supertest - API endpoint testing
- Mocked dependencies - Isolated testing for databases, auth, and external services
- PostgreSQL - Primary database for products
- MongoDB - Document database for orders
- Redis - Queue storage
- Stripe - Payment processing
- Turborepo - Monorepo build system
- Node.js >= 18
- pnpm package manager
- PostgreSQL database
- MongoDB database
- Redis instance
- Stripe account
-
Clone the repository
git clone https://github.com/Devdad-Main/Ecommerce-Microservices.git cd Ecommerce-Microservices/ -
Install dependencies
pnpm install
-
Set up environment variables
Copy the example environment files and configure:
- Database URLs (PostgreSQL, MongoDB)
- Redis connection
- Stripe API keys
- Clerk authentication keys
-
Set up databases
# Generate Prisma client and run migrations pnpm run db:generate pnpm run db:migrate -
Start development servers
pnpm run dev
This will start all services concurrently:
- Client: http://localhost:3002
- Admin: http://localhost:3003
- Product Service: http://localhost:8000
- BullMQ Board: http://localhost:8000/admin/queues
- Order Service: http://localhost:8001
- Payment Service: http://localhost:8002
The project includes comprehensive backend testing:
- Unit tests for controllers, middleware, and utilities
- Integration tests for API endpoints
- Mocked dependencies for databases, authentication, and external services
- Run
pnpm testin individual service directories to execute tests - Current test coverage includes product-service auth middleware and category controllers
ecommerce-microservices/
├── apps/
│ ├── admin/ # Admin dashboard (Next.js)
│ ├── client/ # Customer frontend (Next.js)
│ ├── order-service/ # Order processing (Fastify)
│ ├── payment-service/# Payment processing (Hono)
│ └── product-service/# Product management (Express)
├── packages/
│ ├── bullmq/ # Job queue system
│ ├── eslint-config/ # Shared ESLint config
│ ├── order-db/ # Order database models
│ ├── product-db/ # Product database schema
│ ├── types/ # Shared TypeScript types
│ └── typescript-config/ # Shared TS config
├── package.json
├── turbo.json
└── pnpm-workspace.yaml
pnpm run dev- Start all services in development modepnpm run build- Build all applications and packagespnpm run lint- Run ESLint across the monorepopnpm run check-types- Run TypeScript type checkingpnpm run db:generate- Generate Prisma clientpnpm run db:migrate- Run database migrationspnpm run test- Run tests across all servicespnpm run test:watch- Run tests in watch mode
The application uses Clerk for authentication with role-based access:
- Customers: Can browse products, manage cart, place orders
- Admins: Full access to product and order management
Stripe handles all payment processing with:
- Secure checkout sessions
- Webhook handling for payment confirmations
- Asynchronous order creation via job queues
- Support for multiple currencies
BullMQ manages asynchronous operations:
- Stripe product creation/deletion
- Order processing after successful payments
- Image processing and optimization
- Products with variants (sizes, colors)
- Categories with slug-based routing
- Image storage with color-specific images
- Order history with user association
- Product snapshots at time of purchase
- Payment status tracking
- Follow the existing code style and conventions
- Use TypeScript for all new code
- Add tests for new features
- Update documentation as needed
- Use conventional commits
This project is licensed under the ISC License.
- Built with modern web technologies and best practices
- Inspired by scalable e-commerce architectures
- Uses open-source tools and frameworks