ParcelKoy
A web-based courier logistics platform managing the complete parcel delivery lifecycle — from merchant pickup requests to COD settlement.
Lifecycle
Pickup → COD
Roles
4 actor types
Security
JWT + RBAC + OTP
Stack
Next.js + Express
Project Overview
Built to simplify courier operations end to end
ParcelKoy streamlines parcel delivery operations, provides real-time tracking, reduces manual logistics errors, and scales with multi-role courier workflows.
What the platform covers
Parcel pickup requests
Rider assignment
Hub processing and routing
Real-time parcel tracking
Delivery confirmation
Cash on Delivery (COD) settlement
Improves handoff reliability across delivery stages
Supports scalable courier services across multiple roles
Keeps merchants, riders, and admins aligned on parcel state
Technical Architecture
A clean front-to-back structure built for scale
ParcelKoy keeps responsibilities separated so the frontend stays predictable while the backend remains modular and easy to extend.
Frontend — Next.js
Service Layer → Server Actions → Client Data Flow
Service layer owns API calls and network concerns.
Server actions wrap services with a centralized action wrapper.
Client components consume server actions and keep the UI focused.
Backend — Modular Express
route.ts handles API routing for each domain.
controllers.ts manages request flow and validation orchestration.
services.ts stores business logic and reusable operations.
validators.ts keeps Zod schemas and inferred types together.
Security & Validation
Strict controls across auth, access, and data integrity
The platform combines better-auth, JWT, RBAC, and Zod so the route layer, business logic, and forms all stay aligned on trust boundaries.
Authentication
better-auth and JWT with login, register, password reset, OTP validation, and token rotation.
Access Control
RBAC gates critical flows including block/delete user controls and role-specific logistics actions.
Validation
Zod keeps backend APIs and frontend forms type-safe and consistent from request to response.
User Roles & Access Control
Four roles, clearly separated responsibilities
RBAC controls permissions from platform administration to parcel delivery execution.
Super Admin
Owns platform-wide configuration and oversight.
- Manage user roles and permissions
- Configure system settings
- Review audit logs
- Control platform-level rules
Admin
Operates hubs, riders, and logistics flow.
- Manage hubs and hub locations
- Assign pickup and delivery riders
- Track parcel movement through hubs
- Handle COD collection and settlement
Merchant
Creates and monitors parcel delivery requests.
- Create regular pickup or pick-and-drop requests
- Provide weight, delivery type, and COD details
- Track parcel status and cancel before pickup
- Review delivery history and financial reports
Rider
Executes pickup and delivery assignments.
- Accept or reject assigned tasks
- Confirm pickup and update parcel status
- Verify delivery with OTP
- Add delivery notes when needed
Core Workflow
A strictly ordered delivery pipeline
Every parcel moves through a transparent logistics pipeline so merchants and receivers can follow each step with confidence.
Requested
Pickup Assigned
Picked Up
Received at Origin Hub
In Transit
Received at Destination Hub
Out for Delivery
Delivery Verification (OTP)
Delivered
FinalDelivery Services & Pricing
Flexible delivery options with dynamic pricing
Different delivery experiences with pricing adaptable to weight and delivery zone.
Home Delivery
Delivered directly to the receiver's address.
Pickup Point Delivery
Receiver collects the parcel from a designated hub or location.
Express Delivery
Available within Dhaka city with delivery within 24 hours.
Standard Delivery
Available nationwide with delivery within 48 to 72 hours.
Pricing factors
Weight
Measured per parcel
Zone
Based on delivery region
Tier
Aligned to speed level
Database Design
Structured around domain tables
Each domain is isolated into its own management module, keeping the codebase maintainable and scalable without collapsing into a single large service file.
Core domain tables
ERD diagram — postresql tables and relationships
View Full ERDModule structure per domain
route.ts
API routing
controllers.ts
Request orchestration
services.ts
Business logic
validators.ts
Zod schemas
Next Step
Explore the live product or review the codebase.
The links below connect you to the deployed frontend and the GitHub repositories that power ParcelKoy.