🛒 TypeScript E-commerce Microservices

A production-ready TypeScript microservices architecture for e-commerce order and invoice management, built with Domain-Driven Design (DDD), Command Query Responsibility Segregation (CQRS), and Event-Driven Architecture.

🚀 Features

📦 Order Service

• Complete Order Lifecycle Management with status transitions:
  • CREATED → ACCEPTED → REJECTED → SHIPPING_IN_PROGRESS → SHIPPED
• RESTful API with full CRUD operations
• Role-based Access Control (SELLER/BUYER roles)
• Event-driven architecture with domain events
• Comprehensive validation and error handling

📄 Invoice Service

• PDF Invoice Upload and management
• Automatic invoice sending when orders are shipped
• File storage with MIME type validation
• Cross-service communication via message queues
• Order projection for invoice generation

🔄 Event-Driven Communication

• Asynchronous messaging via RabbitMQ
• Domain events for loose coupling
• Event sourcing patterns
• Message handlers for cross-service operations

🛠️ Technology Stack

Backend

• Node.js 22 - Runtime environment
• TypeScript 5.8 - Type-safe development
• NestJS 11 - Progressive Node.js framework
• MikroORM - TypeScript ORM for MongoDB
• RabbitMQ - Message broker for async communication
• Vitest - Fast unit testing framework
• Biome - Fast formatter and linter

Infrastructure

• Docker & Docker Compose - Containerization
• MongoDB 8.0 - NoSQL database
• RabbitMQ 3.12 - Message broker
• pnpm - Fast package manager

Architecture Patterns

• Domain-Driven Design (DDD) - Business logic organization
• Command Query Responsibility Segregation (CQRS) - Command/Query separation
• Event-Driven Architecture - Loose coupling via events
• Hexagonal Architecture - Clean architecture principles

📋 Prerequisites

• Docker & Docker Compose - For containerized services
• Node.js 22+ - For local development
• pnpm - Package manager (install with npm install -g pnpm)

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/sergioalmela/typescript-ecommerce-microservices.git
cd typescript-ecommerce-microservices

2. Set Up Environment Variables

# Root environment
cp .env.example .env

# Order service environment
cp ./order-service/.env.example ./order-service/.env

# Invoice service environment
cp ./invoice-service/.env.example ./invoice-service/.env

3. Start All Services

# Start with Docker Compose
pnpm dev

# Or start with build
pnpm dev:build

4. Access the Services

• Order Service API: http://localhost:4000/api
• Invoice Service API: http://localhost:4001/api
• RabbitMQ Management: http://localhost:15672 (admin/securepassword)

📚 API Documentation

Both services include Swagger UI for interactive API documentation:

Order Service Endpoints

Method	Endpoint	Description	Role Required
POST	/orders	Create a new order	BUYER
GET	/orders	List all orders	SELLER
GET	/orders/:id	Get order details	SELLER
PATCH	/orders/:id	Update order status	SELLER

Invoice Service Endpoints

Method	Endpoint	Description	Role Required
POST	/invoices/:orderId/invoices	Upload invoice PDF	SELLER

Authentication

All endpoints require authentication headers:

x-user-id: your-user-id
x-user-role: SELLER|BUYER

🔄 Event Subscribers

Order Service Events

• OrderCreatedEvent - Published when a new order is created
• OrderStatusUpdatedEvent - Published when order status changes
• OrderShippedEvent - Published when order is marked as shipped

Invoice Service Subscribers

• CreateOrderProjectionMessageHandler - Listens to OrderCreatedEvent
  • Creates order projection for invoice service
  • Queue: invoice-service-order-created-queue
• SendPdfToCustomerMessageHandler - Listens to OrderShippedEvent
  • Automatically sends invoice when order is shipped
  • Queue: invoice-service-order-shipped-queue

💡 Usage Examples

Create an Order

curl -X POST http://localhost:4000/orders \
  -H "Content-Type: application/json" \
  -H "x-user-id: buyer-123" \
  -H "x-user-role: BUYER" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "productId": "456e7890-e89b-12d3-a456-426614174000",
    "quantity": 2,
    "price": 29.99,
    "customerId": "789e0123-e89b-12d3-a456-426614174000",
    "sellerId": "012e3456-e89b-12d3-a456-426614174000"
  }'

Update Order Status

curl -X PATCH http://localhost:4000/orders/123e4567-e89b-12d3-a456-426614174000 \
  -H "Content-Type: application/json" \
  -H "x-user-id: seller-456" \
  -H "x-user-role: SELLER" \
  -d '{
    "status": "SHIPPED"
  }'

Upload Invoice

curl -X POST http://localhost:4001/invoices/123e4567-e89b-12d3-a456-426614174000/invoices \
  -H "x-user-id: seller-456" \
  -H "x-user-role: SELLER" \
  -F "[email protected]"

🧪 Testing

Run All Tests

pnpm test

Run Tests with Coverage

pnpm test:coverage

Run Tests in Watch Mode

pnpm test:watch

Test Individual Services

# Order service tests
cd order-service && pnpm test

# Invoice service tests
cd invoice-service && pnpm test

🏗️ Development

Project Structure

typescript-ecommerce-microservices/
├── order-service/                 # Order management microservice
│   ├── src/
│   │   ├── app/                  # Application layer
│   │   │   ├── controllers/      # REST API controllers
│   │   │   └── auth/            # Authentication & authorization
│   │   ├── application/          # Application layer (CQRS)
│   │   │   ├── command/         # Command handlers
│   │   │   └── query/           # Query handlers
│   │   ├── domain/              # Domain layer (DDD)
│   │   │   ├── order/           # Order domain logic
│   │   │   └── common/          # Shared domain concepts
│   │   └── infrastructure/      # Infrastructure layer
│   │       ├── persistence/     # Database adapters
│   │       ├── event/           # Event bus implementations
│   │       └── testing/         # Test doubles
│   └── package.json
├── invoice-service/              # Invoice management microservice
│   ├── src/
│   │   ├── app/                 # Application layer
│   │   │   ├── controllers/     # REST API controllers
│   │   │   ├── listeners/       # Message handlers
│   │   │   └── auth/           # Authentication & authorization
│   │   ├── application/         # Application layer (CQRS)
│   │   ├── domain/             # Domain layer (DDD)
│   │   └── infrastructure/     # Infrastructure layer
│   └── package.json
├── docker-compose.yml           # Multi-service orchestration
├── pnpm-workspace.yaml         # pnpm workspace configuration
└── README.md

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Maintain test coverage above 90%
• Use conventional commits
• Follow DDD principles
• Write clear documentation

---

⭐ Star this repository if you find it helpful!