A scalable microservices-based RESTful API built with NestJS for powering a modern e-commerce platform. This backend service provides authentication, product management, shopping cart functionality, checkout processing, and order management through a distributed architecture that ensures high availability, scalability, and maintainability.
Note: This project is currently not deployed online as my AWS free tier has ended. However, everything works perfectly locally. You can follow the instructions in the Running Locally section to set up and run the project on your machine.
- REEN Backend API
- Clerk Integration - Primary authentication method using Clerk for modern user management
- JWT Authentication - Alternative authentication method with JWT tokens for traditional auth flows
- User Registration & Login - Secure user authentication supporting both Clerk and JWT-based authentication
- Refresh Tokens - Automatic token refresh for seamless sessions
- User Roles - Support for Admin, Non-Admin, and Anonymous user roles
- Account Management - User profile updates and account deletion
- Cookie-Based Authentication - Secure HTTP-only cookies for token storage
- Product CRUD Operations - Create, read, update, and delete products
- Product Search & Filtering - Advanced filtering by name, price range, and quantity
- Pagination Support - Efficient pagination for large product catalogs
- Product Images - Support for multiple image URLs per product
- Inventory Management - Track and update product quantities
- Admin Product Management - Admins can create and manage their own products
- Bulk Operations - Support for bulk product updates and deletions
- Cart Item Management - Add, update, and remove items from shopping cart
- User-Specific Carts - Each user has their own isolated shopping cart
- Quantity Management - Update item quantities in the cart
- Cart Retrieval - Efficient cart data retrieval with product information
- Stripe Integration - Secure payment processing through Stripe Checkout
- Checkout Session Creation - Generate secure checkout sessions for cart items
- Payment Webhooks - Handle Stripe webhook events for payment completion
- Order Processing - Automatic order creation upon successful payment
- Inventory Updates - Automatic product quantity updates after purchase
- Financial Tracking - Updates user and admin financial information (balance, sales count, purchases count, amount gained, and amount spent) after transactions
- Order Creation - Automatic order creation from completed checkout sessions
- Order History - Users can view their order history
- Order Details - Detailed order information with product details
- Order Status Tracking - Track order status and completion
- Admin Order Management - Admins can view orders for their products
- Asynchronous Event Processing - Event-driven architecture using RabbitMQ
- Saga Pattern Implementation - Distributed transaction management for checkout flow
- Event Retry Logic - Automatic retry mechanism for failed events
- Webhook Handling - Process webhooks from external services (Stripe, Clerk)
- Email Notifications - Send email notifications for order confirmations and updates
- RESTful API Design - Clean, consistent API endpoints
- API Gateway Pattern - Single entry point for all client requests
- Load Balancing - Multiple API gateway instances with Nginx load balancing
- Input Validation - Comprehensive request validation using class-validator and DTOs
- Error Handling - Structured error responses with proper HTTP status codes
- Request Logging - Comprehensive logging middleware for debugging and monitoring
- CORS Support - Configurable CORS for frontend integration
- Swagger Documentation - Interactive API documentation
- Response Caching - Redis-based caching for improved performance
- Idempotency Support - Prevents duplicate operations through idempotency records
- Microservices Architecture - Distributed services for scalability and maintainability
For screenshots, please visit the REEN Frontend repository.
- NestJS - Progressive Node.js framework for building efficient server-side applications
- TypeScript - Type-safe development
- Monorepo Architecture - NestJS monorepo for managing multiple services
- MongoDB - NoSQL database for flexible data storage
- Prisma - Modern database toolkit and ORM
- Database Per Service - Each microservice has its own database instance
- Clerk - Primary authentication and user management service (recommended)
- JWT - Alternative authentication method using JSON Web Tokens for stateless authentication
- Passport.js - Authentication middleware for JWT-based authentication
- bcryptjs - Password hashing for JWT-based authentication flows
- Stripe - Payment processing and checkout session management
- Webhook Verification - Secure webhook signature verification
- gRPC - High-performance RPC framework for synchronous inter-service communication
- Protocol Buffers - Language-neutral data serialization for service contracts
- Service Discovery - Service-to-service communication through gRPC clients
- RabbitMQ - Message broker for asynchronous event processing
- AMQP - Advanced Message Queuing Protocol for reliable message delivery
- Event-Driven Patterns - Decoupled service communication through events
- Redis - In-memory data store for caching and session management
- @nestjs/cache-manager - Caching module for NestJS
- Cache Invalidation - Strategic cache invalidation for data consistency
- Swagger/OpenAPI - Interactive API documentation
- Nodemailer - Email sending functionality for notifications
- ESLint - Code linting
- Prettier - Code formatting
- Docker - Containerization for development and deployment
- Docker Compose - Multi-container application orchestration
- Nginx - Reverse proxy and load balancer
- Jest - Unit and integration testing framework
- Supertest - HTTP assertion library for API testing
This backend follows a microservices architecture pattern with the following services:
- API Gateway - Single entry point that routes requests to appropriate services, handles authentication, and provides API documentation
- Auth Service - User authentication, authorization, and user management (gRPC)
- Products Service - Product catalog management and inventory tracking (gRPC)
- Cart Items Service - Shopping cart management (gRPC)
- Checkout Service - Payment session creation and checkout processing (gRPC)
- Orders Service - Order management and order history (gRPC)
- Events Handler Service - Asynchronous event processing for webhooks and business logic (RabbitMQ)
Services communicate through:
- gRPC for synchronous requests
- RabbitMQ for asynchronous event processing
- Redis for caching and session management
- Node.js (v22 or higher)
- MongoDB database instances (one per service)
- Redis server
- RabbitMQ server
- Clerk account (for authentication)
- Stripe account (for payment processing)
- Docker and Docker Compose (recommended for local development)
- npm or yarn package manager
Create a .env file in the root directory with the following variables:
# Frontend Configuration
FRONTEND_BASE_URL="http://localhost:3001"
# Database URLs (one per service)
AUTH_DATABASE_URL="mongodb://user:password@localhost:27017/reen-auth?authSource=admin"
PRODUCTS_DATABASE_URL="mongodb://user:password@localhost:27017/reen-products?authSource=admin"
CART-ITEMS_DATABASE_URL="mongodb://user:password@localhost:27017/reen-cart-items?authSource=admin"
ORDERS_DATABASE_URL="mongodb://user:password@localhost:27017/reen-orders?authSource=admin"
# Redis Configuration
REDIS_SERVICE_URL="redis://localhost:6379"
# RabbitMQ Configuration
MESSAGE_BROKER_URL="amqp://guest:guest@localhost:5672"
# Service URLs (gRPC endpoints)
AUTH_SERVICE_URL="localhost:5001"
PRODUCTS_SERVICE_URL="localhost:5002"
CART-ITEMS_SERVICE_URL="localhost:5003"
CHECKOUT_SERVICE_URL="localhost:5004"
ORDERS_SERVICE_URL="localhost:5005"
# Clerk Configuration
CLERK_SECRET_KEY="your-clerk-secret-key"
CLERK_PUBLISHABLE_KEY="your-clerk-publishable-key"
# Stripe Configuration
STRIPE_SECRET_KEY="your-stripe-secret-key"
STRIPE_WEBHOOK_SIGNING_SECRET="your-stripe-webhook-signing-secret"
# Email Configuration (Optional)
EMAIL_SERVICE_API_KEY="your-email-service-api-key"
# Server Configuration
PORT=3000
NODE_ENV=development-
Clone the repository
git clone https://github.com/gideonadeti/reen-backend.git cd reen-backend -
Install dependencies
npm install
-
Set up the databases
# Push schema to each service's database and generate Prisma Client npx prisma db push --schema=apps/auth/prisma/schema.prisma npx prisma db push --schema=apps/products/prisma/schema.prisma npx prisma db push --schema=apps/cart-items/prisma/schema.prisma npx prisma db push --schema=apps/orders/prisma/schema.prismaThis command will push your Prisma schema to each MongoDB database and automatically generate the Prisma Client for each service.
-
Start Redis server
# Using Docker docker run -d -p 6379:6379 redis:8.0.2 # Or using your system's package manager # Ubuntu/Debian: sudo apt-get install redis-server # macOS: brew install redis
-
Start RabbitMQ server
# Using Docker docker run -d -p 5672:5672 -p 15672:15672 rabbitmq:3-management # Or using your system's package manager # Ubuntu/Debian: sudo apt-get install rabbitmq-server # macOS: brew install rabbitmq
-
Start all services
# Start all services concurrently npm run start:dev:all # Or start services individually npm run start:dev # API Gateway npm run start:dev auth # Auth Service npm run start:dev products # Products Service npm run start:dev cart-items # Cart Items Service npm run start:dev checkout # Checkout Service npm run start:dev orders # Orders Service npm run start:dev events-handler # Events Handler Service
-
Access the API
- API Base URL:
http://localhost:3000 - Swagger Documentation:
http://localhost:3000/api-gateway/documentation
- API Base URL:
For easier local development, you can use Docker Compose:
-
Adjust Service URLs for Docker Compose
When using Docker Compose, services communicate through Docker's internal network. Update your
.envfile to use Docker service names instead oflocalhostfor service URLs:# Service URLs (gRPC endpoints) - Use Docker service names AUTH_SERVICE_URL="auth:5001" PRODUCTS_SERVICE_URL="products:5002" CART-ITEMS_SERVICE_URL="cart-items:5003" CHECKOUT_SERVICE_URL="checkout:5004" ORDERS_SERVICE_URL="orders:5005" # Redis Configuration - Use Docker service name REDIS_SERVICE_URL="redis://redis:6379" # RabbitMQ Configuration - Use Docker service name (if running in Docker) MESSAGE_BROKER_URL="amqp://guest:guest@rabbitmq:5672"
Note: If you're running MongoDB and RabbitMQ outside of Docker Compose, keep using
localhostfor those URLs. -
Start all services with Docker Compose
docker compose -f compose.yaml -f compose.dev.yaml up
This will start all services, Redis, and set up the necessary networking.
-
Access the API
- API Base URL:
http://localhost:3000 - Swagger Documentation:
http://localhost:3000/api-gateway/documentation
- API Base URL:
This project is designed to be deployed using Docker Compose with images stored in GitHub Container Registry (GHCR). The production setup includes:
-
Build Docker Images
docker compose -f compose.yaml -f compose.build.yaml build
-
Push Images to GitHub Container Registry (GHCR)
After building, tag and push each service image to GHCR:
# Tag and push each service (example for auth service) docker tag reen-backend-auth:latest ghcr.io/gideonadeti/reen-backend-auth:latest docker push ghcr.io/gideonadeti/reen-backend-auth:latest # Repeat for other services: products, cart-items, checkout, orders, events-handler, api-gateway
-
Deploy on Cloud Server (e.g., AWS EC2)
On your cloud server (EC2 instance):
a. Clone or pull the repository
git clone https://github.com/gideonadeti/reen-backend.git cd reen-backendb. Set up environment variables
Create a
.envfile in the root directory with all required production environment variables:- Database URLs pointing to production MongoDB instances
- Production Redis and RabbitMQ URLs
- Production Clerk and Stripe credentials
FRONTEND_BASE_URLset to your frontend URL- Service URLs configured for Docker Compose (use service names, not localhost)
c. Deploy with Docker Compose
docker compose -f compose.yaml -f compose.prod.yaml up -d
The production setup includes:
- Multiple API Gateway instances for load balancing
- Nginx reverse proxy and load balancer
- All microservices running in containers
- Redis for caching
- SSL/TLS support through Nginx
-
Expose the Service (Without Domain - Using ngrok)
If you don't have a domain yet, you can use ngrok to expose your service:
a. Install ngrok (if not already installed)
# Download and install ngrok # Visit https://ngrok.com/download for installation instructions
b. Run ngrok in a detached tmux session
# Create a new tmux session tmux new -s ngrok # Run ngrok to tunnel to nginx on port 443 ngrok http --domain=your-ngrok-domain.ngrok-free.app 443 # Detach from tmux: Press Ctrl+B, then D
Network Flow: Client → ngrok → Nginx (port 443) → API Gateways
c. Configure Frontend
Update your frontend's API base URL to point to your ngrok domain:
https://your-ngrok-domain.ngrok-free.app -
SSL/TLS Configuration (For Production with Domain)
When you have a domain:
- Place your SSL certificate as
cert.crtin the root directory - Place your SSL private key as
key.keyin the root directory - Nginx will automatically configure HTTPS on port 443
- Update your DNS to point to your server's IP address
- Configure
FRONTEND_BASE_URLto use your domain
- Place your SSL certificate as
Note: Make sure the .env file is in the root directory where you run the docker compose command, as all services mount this file for their configuration.
The following features are planned for future implementation:
- Prometheus - Metrics collection and monitoring for all microservices
- Grafana - Visualization and dashboards for system metrics and performance monitoring
- ELK Stack (Elasticsearch, Logstash, Kibana) - Centralized logging aggregation and log analysis across all microservices
- GitHub Actions or Jenkins - Automated build, test, and deployment pipeline for each microservice
- Automated testing integration
- Container image building and pushing to registry
- Automated deployment to staging and production environments
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow the existing code style
- Update documentation as needed
- Ensure all tests pass before submitting
- Follow microservices best practices
- Maintain service boundaries and contracts
- Update protocol buffer definitions when adding new gRPC methods
If you find this project helpful or interesting, consider supporting me:
This project is inspired by the roadmap.sh Scalable E-Commerce Platform project challenge. The implementation follows the project specifications, including core microservices (User Service, Product Catalog Service, Shopping Cart Service, Order Service, Payment Service), API Gateway pattern, Docker containerization, and service communication using REST APIs and gRPC. Additionally, event-driven architecture using RabbitMQ, distributed transaction management using the Saga pattern, and notification services have been added as extensions to enhance the platform's capabilities.
This project demonstrates a production-ready microservices architecture for e-commerce applications. The implementation follows best practices including:
- Service-oriented architecture with clear boundaries
- Event-driven patterns for asynchronous processing
- Distributed transaction management using the Saga pattern
- High availability through load balancing and multiple instances
- Comprehensive error handling and retry mechanisms
- Caching strategies for improved performance
Thanks to these technologies: