Multi-Vendor E-Commerce Platform (BACKEND System)
A scalable multi-vendor marketplace featuring 15 microservices, escrow-based payment protection, tenant isolation, and admin governance system with dual-approval workflows.
microservices
nestjs
typescript
postgresql
multi-tenant
e-commerce
escrow
payment-gateway
docker
keycloak
oauth2
row-level-security
redis
nginx
dispute-resolution
compliance
audit-logging
saas
marketplace
api-gateway
Note: Some repositories are private to protect proprietary logic. Full source code access can be shared with recruiters on request.
Technical Documentation
🛒 Multi-Vendor E-Commerce Platform
Enterprise-Grade, Escrow-Protected Multi-Tenant Marketplace
A production-ready multi-tenant e-commerce platform built with modern microservices architecture. Features complete buyer protection through escrow, dispute resolution, and compliance workflows.
🎯 What This Platform Solves
| Problem | Solution |
|---|---|
| Buyer doesn't trust unknown sellers | Escrow holds payment until delivery confirmed |
| Sellers fear chargebacks | Dispute resolution with evidence-based decisions |
| Platform liability | Complete audit trail + legal hold support |
| Multi-vendor complexity | Tenant isolation at database level (RLS) |
| Payment fraud | Gateway abstraction with webhook verification |
🏗️ Architecture Overview
┌─────────────────────────────────────────────────────────────────────────┐
│ NGINX GATEWAY │
│ (Rate Limiting, Load Balancing, SSL) │
└───────────────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ IDENTITY │ │ COMMERCE │ │ FINANCIAL │
│ │ │ │ │ │
│ • Tenant Svc │ │ • Product Svc │ │ • Payment Svc │
│ • User Svc │ │ • Cart Svc │ │ • Escrow Svc │
│ • Admin Svc │ │ • Order Svc │ │ • Payout Svc │
│ • Keycloak │ │ • Inventory │ │ • Compliance │
└───────────────┘ └───────────────┘ └───────────────┘
│ │ │
└───────────────────────────┼───────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│PostgreSQL │ │ Redis │ │ Keycloak │
│ (RLS) │ │ (Cache) │ │ (OAuth) │
└───────────┘ └───────────┘ └───────────┘
🔄 Data Flow
Product Discovery Flow
User Request
│
▼
┌─────────────────┐
│ NGINX Gateway │ ── Rate limit check
└────────┬────────┘
│
▼
┌─────────────────┐
│ Product Service │ ── Check Redis cache
└────────┬────────┘
│
┌────┴────┐
│ │
▼ ▼
CACHE DATABASE
HIT MISS
│ │
│ ┌────▼────┐
│ │PostgreSQL│ ── RLS applies tenant filter
│ │ Query │
│ └────┬────┘
│ │
│ ┌────▼────┐
│ │ Cache │ ── Store in Redis
│ │ Update │
│ └────┬────┘
│ │
└────┬────┘
│
▼
JSON Response
to Client
Order Creation Flow
┌─────────────────┐
│ Cart Service │
│ (Validate Cart)│
└────────┬────────┘
│
▼
┌─────────────────┐
│Inventory Service│
│ (Reserve Stock) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Order Service │
│ (Create Order) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Pricing Service │
│(Calculate Final)│
└────────┬────────┘
│
▼
Order Created (Status: PENDING)
👤 User Flows
Buyer Journey
┌──────────────────────────────────────────────────────────────────────┐
│ BUYER FLOW │
└──────────────────────────────────────────────────────────────────────┘
Browse Add to Checkout Payment Receive Review
Products Cart Order (Escrow) Delivery Product
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
│ GET │ │ ADD │ │CREATE│ │ PAY │ │CONFIRM│ │ POST │
│/prod│ │/cart│ │/order│ │ │ │DELIVERY│ │/review│
└─────┘ └─────┘ └─────┘ └──┬──┘ └───┬───┘ └─────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ ESCROW │ │ ESCROW │
│ CREDIT │ │ RELEASE │
│ (Frozen) │ │ (Payout) │
└──────────┘ └──────────┘
DISPUTE PATH (if issue):
Receive Issue → Open Dispute → Submit Evidence → Admin Review → Resolution
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌────────┐
│ Problem │ │ ESCROW │ │ Evidence │ │ Admin │ │ Refund │
│Detected │ │ FROZEN │ │ Upload │ │ Decides │ │ OR │
│ │ │ │ │ │ │ │ │Release │
└─────────┘ └──────────┘ └──────────┘ └─────────┘ └────────┘
Seller (Tenant) Journey
┌──────────────────────────────────────────────────────────────────────┐
│ SELLER FLOW │
└──────────────────────────────────────────────────────────────────────┘
Onboard Setup List Receive Ship Get
Tenant Store Products Order Order Paid
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐
│REGIS│ │CONFIG│ │ ADD │ │ VIEW │ │CREATE│ │PAYOUT│
│TER │ │STORE │ │PRODS│ │ORDERS│ │SHIPMT│ │ │
└─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └──┬──┘
│
┌──────────┴──────────┐
│ │
▼ ▼
┌────────────┐ ┌────────────┐
│ ELIGIBLE │ │ BLOCKED │
│ │ │ │
│ • Delivered│ │ • Dispute │
│ • 14 days │ │ • Legal │
│ • No dispute│ │ • Penalty │
└────────────┘ └────────────┘
Admin Journey
┌──────────────────────────────────────────────────────────────────────┐
│ ADMIN FLOW │
└──────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────┐
│ ADMIN DASHBOARD │
└─────────────┬───────────────┘
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ TRUST │ │ FINANCE │ │COMPLIANCE │
│ ADMIN │ │ ADMIN │ │ ADMIN │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
▼ ▼ ▼
• Tenant Management • Payout Approval • Legal Holds
• Suspend/Warn • Escrow Review • Data Exports
• Support Escalation • Refund Override • Audit Review
│ │ │
└────────────────────────┼────────────────────────┘
│
▼
┌─────────────────────────────┐
│ DUAL APPROVAL SYSTEM │
│ │
│ Sensitive actions require │
│ approval from 2 admins │
└─────────────────────────────┘
💳 Payment Flow
Complete Payment Lifecycle
┌─────────────────────────────────────────────────────────────────────────────┐
│ PAYMENT FLOW │
└─────────────────────────────────────────────────────────────────────────────┘
PHASE 1: CHECKOUT
═══════════════════════════════════════════════════════════════════════════════
Buyer Platform Gateway
│ │ │
│ ──── Checkout ────► │ │
│ │ ── Create Payment ──► │
│ │ ◄── Payment URL ──── │
│ ◄── Redirect ───── │ │
│ │ │
│ ───────────────────── Complete Payment ──────────►│
│ │ │
PHASE 2: ESCROW CREDIT
═══════════════════════════════════════════════════════════════════════════════
Gateway Platform Escrow
│ │ │
│ ── Webhook: PAID ──► │ │
│ │ │
│ │ ── Credit Escrow ───► │
│ │ (Tenant's Account) │
│ │ │
│ │ ◄── Balance Updated ─ │
│ │ (HELD, not available)│
PHASE 3: FULFILLMENT
═══════════════════════════════════════════════════════════════════════════════
Seller Platform Buyer
│ │ │
│ ── Create Shipment ─► │ │
│ │ ── Tracking Update ──► │
│ │ │
│ ── Mark Delivered ──► │ │
│ │ ── Delivery Confirm ──► │
│ │ │
│ │ ◄── Confirm Receipt ─ │
│ │ (or auto after 14d) │
PHASE 4: PAYOUT (HAPPY PATH)
═══════════════════════════════════════════════════════════════════════════════
Time Passes Platform Seller
│ │ │
│ ── 14 day window ──► │ │
│ │ │
│ ┌──────┴──────┐ │
│ │ CHECK: │ │
│ │ • Delivered │ │
│ │ • No dispute│ │
│ │ • No hold │ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────┴──────┐ │
│ │ RELEASE │ ── Platform Fee ──► (5%)
│ │ ESCROW │ ── Seller Share ──► (95%)
│ └─────────────┘ │
PHASE 4: PAYOUT (DISPUTE PATH)
═══════════════════════════════════════════════════════════════════════════════
Buyer Platform Seller
│ │ │
│ ── Open Dispute ──► │ │
│ │ │
│ ┌──────┴──────┐ │
│ │ ESCROW │ │
│ │ FROZEN │ │
│ └──────┬──────┘ │
│ │ │
│ ── Evidence ───────► │ ◄───── Evidence ───── │
│ │ │
│ ┌──────┴──────┐ │
│ │ ADMIN │ │
│ │ REVIEW │ │
│ └──────┬──────┘ │
│ │ │
│ ┌──────────┴──────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ │
│ │BUYER WINS │ │SELLER WINS│ │
│ │ │ │ │ │
│ │ Refund to │ │ Release │ │
│ │ Buyer │ │ to Seller │ │
│ └───────────┘ └───────────┘ │
Payment States
┌─────────┐
│ PENDING │
└────┬────┘
│
┌─────────┴─────────┐
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ PAID │ │ FAILED │
└────┬─────┘ └──────────┘
│
▼
┌──────────┐
│ IN ESCROW│ ◄──── Funds held
└────┬─────┘
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ RELEASED │ │ FROZEN │ │ REFUNDED │
│ │ │(Dispute) │ │ │
│ To Seller│ └────┬─────┘ │ To Buyer │
└──────────┘ │ └──────────┘
│
┌───────┴───────┐
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ RELEASED │ │ REFUNDED │
│(Seller Won) │(Buyer Won)│
└──────────┘ └──────────┘
🔧 Technology Choices & Rationale
Core Stack
| Technology | Purpose | Why This Choice |
|---|---|---|
| Node.js + NestJS | Microservices | TypeScript support, dependency injection, modular architecture, excellent for APIs |
| PostgreSQL | Primary Database | ACID compliance for financial data, Row-Level Security (RLS) for tenant isolation, JSON support |
| Redis | Cache + Sessions | Sub-millisecond latency, pub/sub for real-time updates, session storage |
| Keycloak | Identity Provider | Enterprise-grade OAuth2/OIDC, multi-realm for tenant isolation, battle-tested security |
| NGINX | API Gateway | Rate limiting, load balancing, SSL termination, request routing |
| Docker | Containerization | Consistent environments, easy scaling, microservices deployment |
Why PostgreSQL with RLS?
-- Every query automatically filters by tenant
CREATE POLICY tenant_isolation ON products
USING (tenant_id = current_setting('app.tenant_id')::uuid);
-- Result: Tenant A can NEVER see Tenant B's data
-- No application-level bugs can leak data across tenants
Why Escrow Pattern?
| Traditional Payment | Escrow Pattern |
|---|---|
| Money goes directly to seller | Money held by platform |
| Buyer has no protection | Buyer protected until delivery |
| Disputes are messy | Clear dispute resolution |
| Chargebacks hurt seller | Platform absorbs chargeback risk |
Why Microservices?
MONOLITH PROBLEMS MICROSERVICES SOLUTION
───────────────── ──────────────────────
Single point of failure → Fault isolation
Hard to scale specific parts → Scale only what's needed
Tightly coupled changes → Independent deployments
One language/framework → Best tool for each job
✨ Features
🏪 Multi-Tenant Commerce
| Feature | Description |
|---|---|
| Tenant Isolation | Database-level isolation using PostgreSQL RLS |
| Custom Branding | Each tenant can customize their storefront |
| Flexible Pricing | Tenant-specific pricing rules, discounts, promotions |
| Inventory Management | Stock tracking with reservation system |
| Category Management | Hierarchical categories per tenant |
💰 Financial Safety
| Feature | Description |
|---|---|
| Escrow Protection | All payments held until delivery confirmed |
| Platform Fee | Configurable platform commission (default 5%) |
| Payout Eligibility | Automated checks before fund release |
| Dispute Resolution | Evidence-based, admin-mediated disputes |
| Legal Holds | Freeze funds for legal/compliance needs |
🔒 Security & Compliance
| Feature | Description |
|---|---|
| OAuth2/OIDC | Keycloak for enterprise authentication |
| Role-Based Access | 5 distinct admin roles with separated duties |
| Dual Approval | Sensitive actions require 2 admins |
| Immutable Audit | Tamper-proof audit logs with checksums |
| Data Export | GDPR-compliant data export with watermarking |
📦 Order Management
| Feature | Description |
|---|---|
| Cart System | Persistent carts with guest support |
| Order Lifecycle | Complete state machine from checkout to delivery |
| Shipping Integration | Tracking, webhooks, delivery confirmation |
| Returns Management | Return requests, approval workflow, restocking |
| Notifications | Email/SMS notifications at each stage |
🛡️ Dispute System
| Feature | Description |
|---|---|
| Dispute Types | Non-delivery, damaged, fraud, chargeback |
| Evidence Upload | Both parties can submit evidence |
| Auto-Resolution | Automatic buyer win for non-delivery |
| Abuse Prevention | Buyer flagging, tenant penalties |
| Partial Refunds | Support for partial resolutions |
📊 Service Map
┌────────────────────────────────────────────────────────────────────────────┐
│ SERVICE ARCHITECTURE │
└────────────────────────────────────────────────────────────────────────────┘
PORT SERVICE RESPONSIBILITY
──── ─────── ──────────────
3001 tenant-service Tenant registration, configuration, branding
3002 user-service User accounts, profiles, authentication
3003 admin-service Platform administration, tenant management
3004 product-service Product catalog, categories, search
3005 review-service Product reviews, ratings, moderation
3006 cart-service Shopping cart, wishlist, guest carts
3007 inventory-service Stock management, reservations
3008 pricing-service Pricing rules, discounts, promotions
3009 order-service Order creation, lifecycle, status
3010 payment-service Payment gateway integration, webhooks
3011 escrow-service Escrow accounts, transactions, payouts
3012 shipping-service Shipment tracking, delivery confirmation
3013 return-service Returns workflow, refunds, restocking
3014 dispute-service Dispute resolution, escrow freezing
3015 compliance-service Legal holds, exports, dual approval, audit
INFRASTRUCTURE
──────────────
5432 PostgreSQL Primary database with RLS
6379 Redis Caching, sessions, pub/sub
8080 NGINX API gateway, load balancer
8081 Keycloak OAuth2/OIDC identity provider
🗄️ Database Design
Multi-Tenant Isolation Strategy
┌─────────────────────────────────────────────────────────────────┐
│ TENANT ISOLATION LAYERS │
└─────────────────────────────────────────────────────────────────┘
LAYER 1: APPLICATION
┌───────────────────────────────────────┐
│ JWT token contains tenant_id │
│ Middleware extracts and validates │
└───────────────────────────────────────┘
LAYER 2: DATABASE CONNECTION
┌───────────────────────────────────────┐
│ SET app.tenant_id = 'uuid' │
│ Applied at connection level │
└───────────────────────────────────────┘
LAYER 3: ROW-LEVEL SECURITY
┌───────────────────────────────────────┐
│ POLICY: WHERE tenant_id = current_setting('app.tenant_id')
│ Applied automatically to every query │
└───────────────────────────────────────┘
RESULT: Even SQL injection cannot access other tenant's data
Core Tables
IDENTITY COMMERCE FINANCIAL
──────── ──────── ─────────
tenants products escrow_accounts
users categories escrow_transactions
admin_users product_variants payouts
cart_items payment_records
orders
order_items COMPLIANCE
shipments ────────────
returns legal_holds
disputes approval_requests
reviews unified_audit_log
risk_signals
🔐 Security Model
Authentication Flow
┌─────────────────────────────────────────────────────────────────┐
│ AUTHENTICATION FLOW │
└─────────────────────────────────────────────────────────────────┘
Client Platform Keycloak
│ │ │
│ ── Login Request ──► │ │
│ │ ── OAuth2 Auth ──────► │
│ │ ◄── Access Token ───── │
│ ◄── JWT Token ────── │ │
│ │ │
│ ── API Request ─────► │ │
│ (with JWT) │ │
│ │ ── Validate Token ───► │
│ │ ◄── Token Valid ────── │
│ │ │
│ ◄── Response ─────── │ │
Authorization Matrix
┌──────────────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
│ ACTION │ SUPER │ TRUST │ FINANCE │ SUPPORT │COMPLIANCE│
├──────────────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
│ Terminate Tenant │ ✓ Init │ ✓ Init │ ✗ │ ✗ │ ✓ Approve│
│ Approve Payout │ ✓ Both │ ✗ │ ✓ Init │ ✗ │ ✓ Approve│
│ Resolve Dispute │ ✓ │ ✗ │ ✗ │ ✓ │ ✗ │
│ Place Legal Hold │ ✓ │ ✗ │ ✗ │ ✗ │ ✓ │
│ Export Data │ ✓ Approve│ ✗ │ ✗ │ ✗ │ ✓ Init │
│ Change Admin Role│ ✓ Both │ ✗ │ ✗ │ ✗ │ ✗ │
└──────────────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
Init = Can initiate action
Approve = Can approve action
Both = Can do either
📁 Project Structure
ecomm-platform/
├── services/
│ ├── tenant-service/ # Tenant management
│ ├── user-service/ # User accounts
│ ├── admin-service/ # Platform administration
│ ├── product-service/ # Product catalog
│ ├── review-service/ # Reviews & ratings
│ ├── cart-service/ # Shopping cart
│ ├── inventory-service/ # Stock management
│ ├── pricing-service/ # Pricing rules
│ ├── order-service/ # Order management
│ ├── payment-service/ # Payment processing
│ ├── escrow-service/ # Escrow management
│ ├── shipping-service/ # Shipment tracking
│ ├── return-service/ # Returns workflow
│ ├── dispute-service/ # Dispute resolution
│ └── compliance-service/ # Governance & compliance
│
├── docker/
│ ├── postgres/
│ │ ├── init.sql # Base schema
│ │ ├── phase4-inventory.sql # Commerce schema
│ │ ├── phase5-orders-payments.sql
│ │ ├── phase6-shipping-returns.sql
│ │ └── phase7-admin-governance.sql
│ ├── nginx/
│ │ └── nginx.conf # Gateway configuration
│ └── keycloak/
│
├── docs/
│ ├── PHASE4-CART-INVENTORY-PRICING.md
│ ├── PHASE5-ORDERS-PAYMENTS-ESCROW.md
│ ├── PHASE6-SHIPPING-RETURNS-DISPUTES.md
│ ├── PHASE7-ADMIN-GOVERNANCE.md
│ └── DISPUTE-RESOLUTION-RULES.md
│
├── docker-compose.yml
└── README.md
🎯 Key Design Decisions
1. Database-Level Tenant Isolation
Decision: Use PostgreSQL Row-Level Security instead of separate databases.
Rationale:
- Single database is easier to maintain and backup
- RLS provides guaranteed isolation even against SQL injection
- Scales better than multi-database approach
- Cross-tenant reporting possible for platform admins
2. Escrow-First Payment Model
Decision: Never let payment go directly to seller.
Rationale:
- Buyer protection is non-negotiable for marketplace trust
- Platform has leverage for dispute resolution
- Reduces chargeback impact on sellers
- Legal clarity on fund ownership
3. Immutable Audit Logs
Decision: Audit logs cannot be modified or deleted, even by admins.
Rationale:
- Legal defensibility in disputes
- Regulatory compliance (especially for financial data)
- Internal fraud prevention
- Database triggers enforce immutability
4. Dual Approval for Sensitive Actions
Decision: High-risk admin actions require approval from a second admin.
Rationale:
- Prevents single-point fraud
- Reduces impact of compromised accounts
- Creates accountability trail
- Industry standard for financial platforms
5. Microservices with Clear Boundaries
Decision: One service per domain, not per entity.
Rationale:
- Reduces inter-service chatter
- Clear ownership and deployment
- Can scale independently
- Easier to reason about
📈 Scalability Considerations
Current Architecture Scales To:
| Metric | Capacity |
|---|---|
| Concurrent Users | 10,000+ |
| Products per Tenant | 1,000,000+ |
| Orders per Day | 100,000+ |
| Tenants | 10,000+ |
Scaling Strategies Built-In:
┌─────────────────────────────────────────────────────────────────┐
│ HORIZONTAL SCALING │
└─────────────────────────────────────────────────────────────────┘
STATELESS SERVICES
└── Any service can be replicated behind NGINX load balancer
DATABASE SCALING
└── Read replicas for heavy-read services (Product, Cart)
└── Connection pooling via PgBouncer
CACHE STRATEGY
└── Redis cluster for session and cache distribution
└── Cache-aside pattern with TTL
MESSAGE QUEUE (FUTURE)
└── RabbitMQ/Kafka for async processing
└── Event-driven architecture ready
🏆 Quality Attributes
| Attribute | Implementation |
|---|---|
| Reliability | Health checks, graceful degradation, retry logic |
| Security | OAuth2, RLS, rate limiting, audit logging |
| Scalability | Microservices, stateless design, caching |
| Maintainability | TypeScript, modular structure, documentation |
| Observability | Correlation IDs, structured logging, health endpoints |
| Compliance | GDPR exports, legal holds, immutable audit |
📚 Additional Documentation
| Document | Description |
|---|---|
| Phase 4: Cart, Inventory & Pricing | Commerce layer details |
| Phase 5: Orders, Payments & Escrow | Financial layer details |
| Phase 6: Shipping, Returns & Disputes | Fulfillment layer details |
| Phase 7: Admin Governance | Compliance layer details |
| Dispute Resolution Rules | Dispute handling policies |
👤 Author
Kunal
This platform demonstrates expertise in:
- Enterprise microservices architecture
- Financial system design (escrow, payouts)
- Multi-tenant SaaS architecture
- Security & compliance systems
- Modern DevOps practices
Built with ❤️ for the modern marketplace economy