Parcel Tracking Microservices Platform

A distributed backend system that simulates a modern logistics tracking platform similar to DHL, UPS, or FedEx.

This project demonstrates how to design and build a scalable microservices architecture using NestJS, RabbitMQ, and gRPC. The system allows users to create shipments, track delivery status in real-time, and receive notifications when shipment events occur.

---

Architecture Overview

The platform follows an event-driven microservices architecture where services communicate asynchronously using RabbitMQ and synchronously using gRPC.

                API Gateway
                     |
    ---------------------------------------
    |         |           |               |
 Auth      User      Shipment        Tracking
    |         |           |               |
    ----------- RabbitMQ Event Bus --------
                     |
              Notification Service
                     |
                Firebase FCM

---

Microservices

Auth Service

Handles authentication and authorization.

Features:

• User registration
• Login with JWT
• Token validation
• Role management

---

User Service

Manages user accounts.

Features:

• User profile management
• Address management
• Account preferences

---

Shipment Service

Responsible for creating and managing shipments.

Features:

• Create shipment
• Assign tracking number
• Update shipment information
• Shipment status management

Example statuses:

• CREATED
• PICKED_UP
• IN_TRANSIT
• ARRIVED_AT_WAREHOUSE
• OUT_FOR_DELIVERY
• DELIVERED

---

Tracking Service

Maintains the shipment tracking timeline.

Features:

• Track shipment history
• Record location updates
• Store shipment event timeline

Example tracking event:

{
  "trackingNumber": "PKG123456",
  "status": "IN_TRANSIT",
  "location": "Algiers Sorting Center",
  "timestamp": "2026-04-06T12:00:00Z"
}

---

Notification Service

Sends real-time notifications when shipment status changes.

Supports:

• Push notifications via Firebase Cloud Messaging
• Email notifications
• SMS notifications (future extension)

Example notifications:

📦 Your package has been picked up
🚚 Your package is out for delivery
✅ Your package has been delivered

---

Event-Driven Communication

RabbitMQ is used as the message broker for inter-service communication.

Example events:

shipment.created
shipment.picked_up
shipment.in_transit
shipment.out_for_delivery
shipment.delivered

Example flow:

1. User creates shipment
2. Shipment Service publishes shipment.created
3. Tracking Service records the event
4. Notification Service sends push notification

---

Technology Stack

Backend

• NestJS
• TypeScript
• RabbitMQ
• gRPC
• PostgreSQL / MongoDB

Messaging

• RabbitMQ

Notifications

• Firebase Cloud Messaging (FCM)

Containerization

• Docker
• Docker Compose

---

Example Use Case

1. User creates a shipment.
2. A unique tracking number is generated.
3. Each delivery step produces a tracking event.
4. Events are published to RabbitMQ.
5. Tracking and Notification services consume events.
6. Users receive real-time updates on shipment status.

---

Goals of This Project

• Demonstrate event-driven microservices architecture
• Implement asynchronous communication with RabbitMQ
• Explore scalable backend design patterns
• Simulate real-world logistics infrastructure
• Practice NestJS microservice development

---

Future Improvements

• Real-time map tracking
• Delivery driver mobile app integration
• Warehouse management module
• Analytics dashboard
• Rate calculation and billing
• Multi-region deployment

---

Learning Outcomes

By building this project you will gain practical experience with:

• Distributed systems architecture
• Message-driven communication
• Microservices orchestration
• Scalable backend design
• Event-driven patterns
• Notification infrastructure