A full-stack parcel delivery system with three role-based portals (Customer · Rider · Admin),
real Stripe payments, Firebase JWT auth, live tracking, and a 16-query parallel MongoDB
aggregation engine — covering all 64 districts of Bangladesh.

 

---

🔐 Try It Right Now — No Signup

Role	Email	Password	Suggested flow
👤 Customer	admin4@gmail.com	123456aA	Book parcel → pay → watch status update live
🛵 Rider	admin11@gmail.com	123456aA	Open task queue → confirm pickup → deliver → earnings update
🛡️ Admin	admin1@gmail.com	123456aA	Approve a rider → assign a delivery → explore the KPI dashboard

💳 Stripe test card

4242 4242 4242 4242   ·   Any future expiry   ·   Any CVC

Stripe test mode — no real charge, ever.

---

🎯 Why this isn't just another portfolio project

Most portfolio apps stop at a UI with mock data. This one doesn't.

What it does	Why it matters
Server-side pricing validation	Parcel cost is recalculated on the backend and compared to the client value. Mismatch → 400. Price tampering is impossible.
Firebase JWT on every route	firebase-admin decodes and verifies tokens server-side. Role is checked from MongoDB — not the token claim. A modified token does nothing.
16 parallel MongoDB aggregations	The admin overview fires all KPI queries inside a single Promise.all(). Zero sequential waterfalls, one round-trip.
Full Stripe PaymentIntents flow	Secret key never touches the client. Only the client_secret does. Webhook-ready payment recording.
Three purpose-built dashboards	Each role has a separate data model, API, and animated UI — not the same page with hidden tabs.

---

✨ What each role can do

👤 Customer Portal

Feature	Detail
Parcel Booking	Multi-step form — document vs non-document, weight tiers, same/inter-district auto-pricing
Stripe Payment	Full PaymentIntent flow — card UI → confirmation → DB write → parcel marked paid
Live Tracking	Public page — unique PCL-YYYYMMDD-XXXXX ID, full event log with location + timestamp
Dashboard	Single API: stats, active parcel progress stepper, monthly spend bar chart, status donut
Payment History	Transaction IDs, amounts, dates

🛵 Rider Portal

Feature	Detail
Task Queue	Live assigned + in-transit parcels, colour-coded by delivery type
Pickup / Delivery	One-tap confirmation → status update → tracking event written to DB
Earnings Wallet	Lifetime / weekly / monthly breakdown, settled vs pending cashout
Commission	80% same-district · 30% inter-district — shown inline, always visible
Dashboard	Profile card, active queue, route analysis chart, cashout nudge

🛡️ Admin Command Centre

Feature	Detail
KPI Overview	16 parallel queries — revenue today/7d/30d, parcel counts, top districts, 7-day sparkline
Rider Approval	Review NID, bike, region → approve or reject inline
Rider Assignment	Filter by district → assign → rider phone shown for coordination
User Management	All users + last login + roles → promote to admin in one click

---

🏗️ How it's built

  React 19 + Vite 7
  ┌────────────┬────────────┬────────────┐
  │  Customer  │   Rider    │   Admin    │
  └─────┬──────┴─────┬──────┴─────┬──────┘
        └────────────┼────────────┘
              TanStack Query v5
         (cache · stale-time · refetch)
                     │
           Axios + Firebase JWT
                     │
        Express 5  ──  verifyFBToken
                        → verifyAdmin
                        → verifyRider
                     │
        MongoDB Atlas  ──  $match · $group
                    Promise.all([...16])
                     │
     users · parcels · riders · payments · tracking

---

🛠️ Tech Stack

	Tech	Version	Role
Frontend	React, Vite, React Router	19 · 7 · 7	UI, routing, layouts
State	TanStack Query, React Hook Form	5 · 7	Server cache, forms
Styling	Tailwind CSS, DaisyUI	4 · 5	Utility-first, light/dark
Motion	Framer Motion, Recharts	12 · 3	Animations, charts
Payments	Stripe.js + Stripe Node	8 · 20	PaymentIntents, PCI
Auth	Firebase SDK + Admin SDK	12 · 13	Client auth + server JWT
Backend	Express, MongoDB Atlas	5 · 7	REST API, aggregations
Maps	React Leaflet	5	Coverage visualisation

---

💰 Pricing logic

Document        Same district ৳60  ·  Inter district ৳80

Non-Document    Base ≤ 3 kg:  ৳110 same  /  ৳150 inter
                Extra weight: +৳40 per kg above 3 kg
                Inter surcharge: +৳40

Rider cut       Same district 80%  ·  Inter district 30%

Calculated client-side for UX, recalculated server-side for trust.

---

🔒 Security model

• Firebase Admin SDK verifies JWT on every protected route — forged tokens rejected
• Role stored in MongoDB — changing the token claim does nothing
• Email ownership enforced server-side — users can't read each other's data
• Rider role explicitly blocked from the role-promotion endpoint
• Stripe secret key is server-only — client only receives client_secret

---

🚀 Run locally

git clone https://github.com/Hridoykhan4/masakkali-client
git clone https://github.com/Hridoykhan4/masakkali-server

server/.env

PORT=5000
DB_USER=
DB_PASS=
Stripe_KEY=sk_test_...
FB_SERVICE_KEY=base64_firebase_service_account

client/.env.local

VITE_API_URL=http://localhost:5000
VITE_FIREBASE_API_KEY=
VITE_FIREBASE_AUTH_DOMAIN=
VITE_FIREBASE_PROJECT_ID=
VITE_FIREBASE_STORAGE_BUCKET=
VITE_FIREBASE_MESSAGING_SENDER_ID=
VITE_FIREBASE_APP_ID=
VITE_STRIPE_PK=pk_test_...

cd masakkali-server && npm i && npm run dev
cd masakkali-client && npm i && npm run dev

---

Built by Md. Toyob Uddin Hridoy

 

_{Full-stack · Production-grade · Bangladesh 🇧🇩 · 2026}