https://github.com/rafirabby13/parcel-delivery-system

This is a role-based, secure, modular backend API for a Parcel Delivery Management System inspired by services like **Pathao Courier** or **Sundarban**. It allows users to register as **senders** or **receivers**, create parcel requests, track deliveries, and manage parcel statuses. Admins can manage users and parcels, enforce policies.
https://github.com/rafirabby13/parcel-delivery-system

bcryptjs cookie-parser cors dotenv expressjs nodejs typescript zod

Last synced: about 2 months ago
JSON representation

This is a role-based, secure, modular backend API for a Parcel Delivery Management System inspired by services like **Pathao Courier** or **Sundarban**. It allows users to register as **senders** or **receivers**, create parcel requests, track deliveries, and manage parcel statuses. Admins can manage users and parcels, enforce policies.

• Host: GitHub
• URL: https://github.com/rafirabby13/parcel-delivery-system
• Owner: rafirabby13
• Created: 2025-07-28T18:31:06.000Z (11 months ago)
• Default Branch: development
• Last Pushed: 2025-12-22T06:03:20.000Z (6 months ago)
• Last Synced: 2025-12-23T17:48:22.762Z (6 months ago)
• Topics: bcryptjs, cookie-parser, cors, dotenv, expressjs, nodejs, typescript, zod
• Language: TypeScript
• Homepage: https://parcel-delivery-system-zeta.vercel.app/
• Size: 497 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
Live Site


###

https://parcel-delivery-system-zeta.vercel.app/


###

Parcel Delivery System


###

This is a role-based, secure, modular backend API for a Parcel Delivery Management System inspired by services like **Pathao Courier** or **Sundarban**. It allows users to register as **senders** or **receivers**, create parcel requests, track deliveries, and manage parcel statuses. Admins can manage users and parcels, enforce policies, and oversee delivery operations.


###

Technologies Used


###

- **Node.js** with **Express**
- **MongoDB** + **Mongoose**
- **JWT Authentication**
- **Zod** for input validation
- **bcrypt** for password hashing
- **TypeScript**
- **Role-based Access Control (RBAC)**


###



  

  

  

  

  

  

  

  

  

  

  



###

Features


###

✅ Sender:

-Create a new parcel
-Cancel (if not picked up)
-View parcel history & status updates

✅ Receiver:

-Track incoming parcels
-Confirm delivery
-View delivery logs

✅ Admin:

-View/manage all users & parcels
-Block/unblock users
-Manually update parcel statuses
-Assign delivery personnel (optional)


###

📜 Validation & Business Rules


###

*Senders can only cancel before dispatch.
*Receivers can confirm delivery.
*Blocked users are restricted.
*Parcel cancellation disallowed after PICKED_UP.
*Return requests allowed only in specific statuses (APPROVED, PICKED_UP, IN_TRANSIT).
*COD parcels can't be returned after dispatch.
*Admins override all roles and enforce status changes.


###

🔍 API Highlights


###

-Tracking ID Format: TRK-YYYYMMDD-XXXXXX
-Status transitions enforced via Zod
-Transactions used for payment cancel/refund & return logic
-All errors handled centrally with meaningful messages


###

🔐 Authentication & Authorization


###

--JWT-based auth with access and refresh tokens.

--Three roles:

-SENDER – Can create, cancel, and track their parcels
-RECEIVER – Can track, confirm delivery
-ADMIN – Full control over parcels, users, and status updates

--Passwords are hashed securely using bcrypt.


###

🚚 Parcel Lifecycle & Business Logic


###

REQUESTED → APPROVED → PICKED_UP → IN_TRANSIT → DELIVERED → RETURNED


###

🧪 API Testing (via Postman)


###

-JWT token handling
-Role access checks
-Parcel status changes
-Return and refund logic
-Blocked user edge cases


###

🔐 Role-Based Route Access


###

| Endpoint                    | Role Access     |
| --------------------------- | --------------- |
| POST /auth/register         | Public          |
| POST /auth/login            | Public          |
| GET /parcels/me             | Sender          |
| POST /parcels               | Sender          |
| PATCH /parcels/\:id/cancel  | Sender          |
| GET /parcels/\:id           | Sender/Receiver |
| PATCH /parcels/\:id/confirm | Receiver        |
| GET /admin/parcels          | Admin           |
| PATCH /admin/users/\:id     | Admin           |
| PATCH /admin/parcels/\:id   | Admin           |


###

📦 Parcel Schema Sample


###

{
  trackingId: "TRK-20250731-123456",
  senderId: ObjectId,
  receiverId: ObjectId,
  weight: Number,
  status: 'IN_TRANSIT',
  paymentMethod: 'COD' | 'PREPAID',
  paymentStatus: 'PENDING' | 'PAID' | 'REFUNDED',
  trackingEvents: [
    {
      status: 'PICKED_UP',
      location: 'Banani',
      note: 'Picked by rider',
      updaterId: ObjectId,
      timestamp: Date
    }
  ]
}


###

⚙️ Getting Started


###

🔄 Clone the Repo


###

git clone this repo
cd parcel-delivery-api


###

🧪 Run in Dev Mode


###

npm run dev


###

🔨 Build & Start


###

npm run build
npm start


###