{"id":30856767,"url":"https://github.com/rafirabby13/parcel-delivery-system","last_synced_at":"2026-05-04T00:31:08.748Z","repository":{"id":306991859,"uuid":"1027922874","full_name":"rafirabby13/parcel-delivery-system","owner":"rafirabby13","description":"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.","archived":false,"fork":false,"pushed_at":"2025-12-22T06:03:20.000Z","size":509,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"development","last_synced_at":"2025-12-23T17:48:22.762Z","etag":null,"topics":["bcryptjs","cookie-parser","cors","dotenv","expressjs","nodejs","typescript","zod"],"latest_commit_sha":null,"homepage":"https://parcel-delivery-system-zeta.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rafirabby13.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-28T18:31:06.000Z","updated_at":"2025-12-22T06:03:24.000Z","dependencies_parsed_at":"2025-08-24T21:18:36.241Z","dependency_job_id":"541d62aa-001a-463f-ad1b-901d1d369262","html_url":"https://github.com/rafirabby13/parcel-delivery-system","commit_stats":null,"previous_names":["rafirabby13/parcel-delivery-system"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rafirabby13/parcel-delivery-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafirabby13%2Fparcel-delivery-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafirabby13%2Fparcel-delivery-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafirabby13%2Fparcel-delivery-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafirabby13%2Fparcel-delivery-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rafirabby13","download_url":"https://codeload.github.com/rafirabby13/parcel-delivery-system/tar.gz/refs/heads/development","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rafirabby13%2Fparcel-delivery-system/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32590088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bcryptjs","cookie-parser","cors","dotenv","expressjs","nodejs","typescript","zod"],"created_at":"2025-09-07T12:10:16.822Z","updated_at":"2026-05-04T00:31:08.736Z","avatar_url":"https://github.com/rafirabby13.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch2 align=\"left\"\u003eLive Site\u003c/h2\u003e\n\n###\n\n\u003ch4 align=\"left\"\u003ehttps://parcel-delivery-system-zeta.vercel.app/\u003c/h4\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003eParcel Delivery System\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003eThis 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.\u003c/p\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003eTechnologies Used\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003e- **Node.js** with **Express**\u003cbr\u003e- **MongoDB** + **Mongoose**\u003cbr\u003e- **JWT Authentication**\u003cbr\u003e- **Zod** for input validation\u003cbr\u003e- **bcrypt** for password hashing\u003cbr\u003e- **TypeScript**\u003cbr\u003e- **Role-based Access Control (RBAC)**\u003c/p\u003e\n\n###\n\n\u003cdiv align=\"left\"\u003e\n  \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/javascript/javascript-original.svg\" height=\"40\" alt=\"javascript logo\"  /\u003e\n  \u003cimg width=\"12\" /\u003e\n  \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/typescript/typescript-original.svg\" height=\"40\" alt=\"typescript logo\"  /\u003e\n  \u003cimg width=\"12\" /\u003e\n  \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/mongodb/mongodb-original.svg\" height=\"40\" alt=\"mongodb logo\"  /\u003e\n  \u003cimg width=\"12\" /\u003e\n  \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/express/express-original.svg\" height=\"40\" alt=\"express logo\"  /\u003e\n  \u003cimg width=\"12\" /\u003e\n  \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/eslint/eslint-original.svg\" height=\"40\" alt=\"eslint logo\"  /\u003e\n  \u003cimg width=\"12\" /\u003e\n  \u003cimg src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/nodejs/nodejs-original.svg\" height=\"40\" alt=\"nodejs logo\"  /\u003e\n\u003c/div\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003eFeatures\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003e✅ Sender:\u003cbr\u003e\u003cbr\u003e-Create a new parcel\u003cbr\u003e-Cancel (if not picked up)\u003cbr\u003e-View parcel history \u0026 status updates\u003cbr\u003e\u003cbr\u003e✅ Receiver:\u003cbr\u003e\u003cbr\u003e-Track incoming parcels\u003cbr\u003e-Confirm delivery\u003cbr\u003e-View delivery logs\u003cbr\u003e\u003cbr\u003e✅ Admin:\u003cbr\u003e\u003cbr\u003e-View/manage all users \u0026 parcels\u003cbr\u003e-Block/unblock users\u003cbr\u003e-Manually update parcel statuses\u003cbr\u003e-Assign delivery personnel (optional)\u003c/p\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003e📜 Validation \u0026 Business Rules\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003e*Senders can only cancel before dispatch.\u003cbr\u003e*Receivers can confirm delivery.\u003cbr\u003e*Blocked users are restricted.\u003cbr\u003e*Parcel cancellation disallowed after PICKED_UP.\u003cbr\u003e*Return requests allowed only in specific statuses (APPROVED, PICKED_UP, IN_TRANSIT).\u003cbr\u003e*COD parcels can't be returned after dispatch.\u003cbr\u003e*Admins override all roles and enforce status changes.\u003c/p\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003e🔍 API Highlights\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003e-Tracking ID Format: TRK-YYYYMMDD-XXXXXX\u003cbr\u003e-Status transitions enforced via Zod\u003cbr\u003e-Transactions used for payment cancel/refund \u0026 return logic\u003cbr\u003e-All errors handled centrally with meaningful messages\u003c/p\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003e🔐 Authentication \u0026 Authorization\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003e--JWT-based auth with access and refresh tokens.\u003cbr\u003e\u003cbr\u003e--Three roles:\u003cbr\u003e\u003cbr\u003e-SENDER – Can create, cancel, and track their parcels\u003cbr\u003e-RECEIVER – Can track, confirm delivery\u003cbr\u003e-ADMIN – Full control over parcels, users, and status updates\u003cbr\u003e\u003cbr\u003e--Passwords are hashed securely using bcrypt.\u003c/p\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003e🚚 Parcel Lifecycle \u0026 Business Logic\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003eREQUESTED → APPROVED → PICKED_UP → IN_TRANSIT → DELIVERED → RETURNED\u003c/p\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003e🧪 API Testing (via Postman)\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003e-JWT token handling\u003cbr\u003e-Role access checks\u003cbr\u003e-Parcel status changes\u003cbr\u003e-Return and refund logic\u003cbr\u003e-Blocked user edge cases\u003c/p\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003e🔐 Role-Based Route Access\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003e| Endpoint                    | Role Access     |\u003cbr\u003e| --------------------------- | --------------- |\u003cbr\u003e| POST /auth/register         | Public          |\u003cbr\u003e| POST /auth/login            | Public          |\u003cbr\u003e| GET /parcels/me             | Sender          |\u003cbr\u003e| POST /parcels               | Sender          |\u003cbr\u003e| PATCH /parcels/\\:id/cancel  | Sender          |\u003cbr\u003e| GET /parcels/\\:id           | Sender/Receiver |\u003cbr\u003e| PATCH /parcels/\\:id/confirm | Receiver        |\u003cbr\u003e| GET /admin/parcels          | Admin           |\u003cbr\u003e| PATCH /admin/users/\\:id     | Admin           |\u003cbr\u003e| PATCH /admin/parcels/\\:id   | Admin           |\u003c/p\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003e📦 Parcel Schema Sample\u003c/h2\u003e\n\n###\n\n\u003cp align=\"left\"\u003e{\u003cbr\u003e  trackingId: \"TRK-20250731-123456\",\u003cbr\u003e  senderId: ObjectId,\u003cbr\u003e  receiverId: ObjectId,\u003cbr\u003e  weight: Number,\u003cbr\u003e  status: 'IN_TRANSIT',\u003cbr\u003e  paymentMethod: 'COD' | 'PREPAID',\u003cbr\u003e  paymentStatus: 'PENDING' | 'PAID' | 'REFUNDED',\u003cbr\u003e  trackingEvents: [\u003cbr\u003e    {\u003cbr\u003e      status: 'PICKED_UP',\u003cbr\u003e      location: 'Banani',\u003cbr\u003e      note: 'Picked by rider',\u003cbr\u003e      updaterId: ObjectId,\u003cbr\u003e      timestamp: Date\u003cbr\u003e    }\u003cbr\u003e  ]\u003cbr\u003e}\u003c/p\u003e\n\n###\n\n\u003ch2 align=\"left\"\u003e⚙️ Getting Started\u003c/h2\u003e\n\n###\n\n\u003ch3 align=\"left\"\u003e🔄 Clone the Repo\u003c/h3\u003e\n\n###\n\n\u003cp align=\"left\"\u003egit clone this repo\u003cbr\u003ecd parcel-delivery-api\u003c/p\u003e\n\n###\n\n\u003ch3 align=\"left\"\u003e🧪 Run in Dev Mode\u003c/h3\u003e\n\n###\n\n\u003cp align=\"left\"\u003enpm run dev\u003c/p\u003e\n\n###\n\n\u003ch3 align=\"left\"\u003e🔨 Build \u0026 Start\u003c/h3\u003e\n\n###\n\n\u003cp align=\"left\"\u003enpm run build\u003cbr\u003enpm start\u003c/p\u003e\n\n###","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafirabby13%2Fparcel-delivery-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frafirabby13%2Fparcel-delivery-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frafirabby13%2Fparcel-delivery-system/lists"}