💊 MediStore Frontend

A production-grade, multi-role pharmacy e-commerce web application built with Next.js 16, React 19, and a unified light pharmacy design system — featuring real-time order tracking, multi-warehouse fulfillment dashboards, and role-based navigation.

📋 Table of Contents

Overview
Tech Stack
Design System
Application Architecture
User Roles & Dashboard Routes
System Workflow
Page Reference
Getting Started
Environment Variables
Project Structure
API Integration

Overview

MediStore Frontend is a Next.js 15 App Router application that serves four distinct user roles — Customer, Seller, Admin, and Warehouse Manager — each with a fully isolated, role-specific dashboard. The app features a public-facing pharmacy storefront, AI chatbot, real-time order tracking, multi-seller cart checkout, and a complete warehouse operations suite.

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
UI Library	React 19
Language	TypeScript
Styling	Vanilla CSS (custom design system via `globals.css`)
Animations	Framer Motion
Icons	React Icons (Font Awesome 6 set)
Notifications	Sonner (toast notifications)
Auth	Better Auth (session cookies, `credentials: include`)
Maps/Geo	GPS coordinate picker (custom)
Charts	Recharts
PDF Viewer	PDF.js / Cloudinary proxy
HTTP	Native `fetch` with `credentials: include`

Design System

All pages share a unified Light Pharmacy Theme defined in globals.css.

Color Palette

Token	Hex	Usage
Navy	`#1B3A5C`	Primary headings, key data
Amber	`#C2703A`	CTAs, prices, highlights
Steel Blue	`#3A6EA5`	Info states, links
Cream	`#F5EDE3`	Page backgrounds, soft containers
Warm Tan	`#8A6650`	Secondary text, labels
Border	`#DDD0C4`	Card borders, dividers
Green	`#2E7D32`	Success, delivered, credits
Sky Blue	`#0EA5E9`	Dispatch, active states
Purple	`#7C3AED`	In-transit, packing states

Core CSS Classes

.medi-page   /* Page wrapper — cream background, max-width, padding */
.medi-card   /* White card — rounded-2xl, border, subtle shadow      */

Component Patterns

Stat Grid — 2×4 metric cards at top of every dashboard page
Filter Pill Tabs — Rounded pill buttons with live counts
Status Badges — Color-coded px-3 py-1 rounded-full pills
Gradient Card Headers — linear-gradient(90deg, {color}10, #FFF)
Status Hint Bar — Thin colored bar below card header
Expandable Rows — Framer Motion height: 0 → auto animations
Action Footer — Sticky bottom row with CTA buttons

Application Architecture

┌─────────────────────────────────────────────────────────────┐
│                    MediStore Frontend                        │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  Public Routes                       │   │
│  │  / (home) · /medicines · /blogs · /about · /auth     │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Role-Based Dashboard                    │   │
│  │                                                      │   │
│  │  /dashboard/customer/*   → Customer portal          │   │
│  │  /dashboard/seller/*     → Seller portal            │   │
│  │  /dashboard/admin/*      → Admin control panel      │   │
│  │  /dashboard/warehouse/*  → WMS operations           │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Next.js API Routes (/api/*)              │   │
│  │          Proxy → Backend (localhost:4000)             │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

User Roles & Dashboard Routes

🛒 Customer (`/dashboard/customer/`)

Page	Route	Purpose
Overview	`/customer` (index)	Stats: orders, wallet, wishlist
Orders	`/customer/orders`	Order history list
Tracking	`/customer/tracking`	Real-time multi-seller journey tracker
Cart	`/customer/cart`	Cart management
Checkout	`/customer/checkout`	Address, coupon, payment
Wallet	`/customer/wallet`	Balance, transactions
Prescriptions	`/customer/prescription`	Upload & track prescriptions
Wishlist	`/customer/wishlist`	Saved medicines
Returns	`/customer/returns`	Return request form & history
Coupons	`/customer/coupons`	Available discount codes
Search	`/customer/search`	Medicine search with filters
Notifications	`/customer/notifications`	In-app alerts
Subscription	`/customer/subscription`	Premium plan management
Support	`/customer/support`	Contact form
Profile	`/customer/profile`	Account settings

🏪 Seller (`/dashboard/seller/`)

Page	Route	Purpose
Overview	`/seller` (index)	Revenue, orders, stock KPIs
Medicines	`/seller/medicines`	Medicine listing management
Add Medicine	`/seller/addMedicine`	Upload new medicine with image
Edit Medicine	`/seller/updateMedicine`	Edit existing listing
Catalog	`/seller/catalog`	Full product catalog view
Orders	`/seller/orders`	Incoming order management
Batches	`/seller/batches`	Lot/batch tracking with expiry
Stock Alerts	`/seller/stock-alerts`	Low-stock notifications
Flash Sales	`/seller/flash-sale`	Time-limited discount campaigns
Coupons	`/seller/coupons`	Seller-specific coupon codes
Wallet	`/seller/wallet`	Earnings, withdrawal requests
Returns	`/seller/returns`	Return requests management
License	`/seller/license`	Pharmacy license upload & status
Subscription	`/seller/subscription`	Seller plan management
Analytics	`/seller/analytics`	Sales trends, revenue charts
Notifications	`/seller/notifications`	Alerts from admin/system
Profile	`/seller/profile`	Seller account settings

🔧 Admin (`/dashboard/admin/`)

Page	Route	Purpose
Overview	`/admin` (index)	Platform-wide KPIs
Users	`/admin/users`	User management, role assignment
Orders	`/admin/orders`	All orders across platform
Medicines	`/admin/featured-products`	Featured product curation
Categories	`/admin/categories`	Medicine category management
License	`/admin/license`	Seller license review & approval
Prescription	`/admin/prescription`	Prescription verification queue
Flash Sales	`/admin/flash-sale`	Flash sale approval
Coupons	`/admin/coupons`	Platform-wide coupon management
Banners	`/admin/banners`	Homepage banner CMS
Blogs	`/admin/blogs`	Health article CMS
Testimonials	`/admin/testimonials`	Customer testimonial management
Platform Features	`/admin/platform-features`	Feature highlight cards CMS
Warehouses	`/admin/warehouses`	Warehouse creation & manager assignment
Returns	`/admin/returns`	Return request approvals
Payouts	`/admin/payouts`	Seller withdrawal approvals
Wallet	`/admin/wallet`	Wallet oversight
Newsletter	`/admin/newsletter`	Subscriber management
Messages	`/admin/messages`	Contact form inbox
Support	`/admin/support`	Support ticket management
Fraud Flags	`/admin/fraud-flags`	Suspicious activity review
Audit Logs	`/admin/audit-logs`	System audit trail
Settings	`/admin/platform-settings`	Global platform configuration
Profile	`/admin/profile`	Admin account settings

🏭 Warehouse (`/dashboard/warehouse/`)

Page	Route	Purpose
Overview	`/warehouse/overview`	Warehouse KPIs — pending, packed, dispatched counts
Orders	`/warehouse/orders`	Incoming order queue with status breakdown
Routing	`/warehouse/routing`	Shipment leg management — receive from sellers, route legs
Packing	`/warehouse/packing`	Pick & pack — stage per-seller packages, create packing slip
Dispatch	`/warehouse/dispatch`	Dispatch packed orders, confirm customer delivery
Fulfillment	`/warehouse/fulfillment`	Delivery history archive with seller credit timeline
Inventory	`/warehouse/inventory`	Stock levels, search, medicine tracking
Locations	`/warehouse/locations`	Warehouse location/zone management
Bins	`/warehouse/bins`	Storage bin allocation
Analytics	`/warehouse/analytics`	Operational performance charts
Expiry	`/warehouse/expiry`	Expiry date monitoring & alerts
Temperature	`/warehouse/temperature`	Cold chain temperature logging
Profile	`/warehouse/profile`	Warehouse manager account

System Workflow

1. Customer Order Journey

[Public Storefront]
  Browse Medicines → Add to Cart → Apply Coupon
      ↓
[Checkout]
  Enter Address (GPS picker) → Select Payment Method
  SSLCommerz / Wallet → Order Placed
      ↓
[Customer Tracking: /customer/tracking]
  Per-seller journey visualization:
  ┌─────────────────────────────────────────────────────┐
  │  Order Placed → Seller Processing → Seller Shipped  │
  │  → At Origin WH → In Transit → At Dest WH          │
  │  → Packing → Out for Delivery → Delivered ✓         │
  └─────────────────────────────────────────────────────┘
  Animated progress bar + per-milestone timestamps

2. Warehouse Operations Workflow

[/warehouse/routing]
┌──────────────────────────────────────────────────────────┐
│                                                          │
│  SELLER_PREPARING                                        │
│       │                                                  │
│  AWAITING_ORIGIN_WH ──────────────────────────────┐     │
│       │                                           │     │
│  [Same WH?] ──Yes──► AT_DEST_WH (skip transit)   │     │
│       │No                                         │     │
│  [Receive from Seller]                            │     │
│       │                                           │     │
│  AT_ORIGIN_WH                                     │     │
│       │                                           │     │
│  [Dispatch to Dest WH]                            │     │
│       │                                           │     │
│  IN_TRANSIT                                       │     │
│       │                                           │     │
│  [Confirm Arrival]                                │     │
│       │                                           │     │
│  AT_DEST_WH ◄─────────────────────────────────────┘     │
└──────────────────────────────────────────────────────────┘
       ↓
[/warehouse/packing]
  FulfillmentTask: PENDING → CONSOLIDATING
  Worker clicks "Mark Received" per seller package
  All packages received? → "Create Packing Slip" → PICKED
       ↓
[/warehouse/dispatch]
  PACKED → "Dispatch to Customer" → DISPATCHED
  "Mark Customer Received" → DELIVERED
  → Auto-credit seller wallets ✓
       ↓
[/warehouse/fulfillment]
  Read-only history — seller credits shown per order

3. Same-Warehouse Fast Path (Visual)

Routing Page Card (sameWH = true):
  ┌─────────────────────────────────────────────────┐
  │  🏬 Same Warehouse — No Transit                  │
  │  Dhaka WH · Seller ships → Receive → Pick & Pack│
  │                                                  │
  │  [🟠 Receive from Seller → Pick & Pack]          │
  └─────────────────────────────────────────────────┘
        ↓ (one click)
  Packing page shows the order immediately

Page Reference

Customer Tracking Page (`/customer/tracking`)

Fetches GET /api/orders/my including subOrders, shipmentLeg, fulfillmentTask
Per-seller deriveJourney() maps live status into 9 visual timeline steps
Animated progress bar with % milestones (3% → 100%)
Expandable per-seller panels with warehouse route summary
Delivered orders show green "🎉 All sellers paid" banner

Warehouse Routing Page (`/warehouse/routing`)

Fetches GET /api/shipment-legs/mine for warehouse manager's legs
Detects sameWH = originWarehouseId === destWarehouseId
Same-WH: Single action — "Receive from Seller → Pick & Pack" (amber)
Multi-WH: Origin actions: Confirm Receipt → Dispatch; Dest actions: Confirm Arrival
Tab filters: All / Incoming / Ready to Dispatch / In Transit / Arrived

Warehouse Packing Page (`/warehouse/packing`)

Fetches fulfillment tasks with status CONSOLIDATING or PICKED
Per-seller staging rows with individual "📥 Mark Received" buttons
Progress bar shows received / total legs
"📦 Create Packing Slip" button unlocks when all legs are AT_DEST_WH

Warehouse Dispatch Page (`/warehouse/dispatch`)

Fetches tasks with status PACKED or DISPATCHED
Filter pills: All / Ready / Dispatched
"Dispatch to Customer" (sky blue) → "Mark Customer Received" (green)
Shows all seller credits on delivery confirmation

Warehouse Fulfillment History (`/warehouse/fulfillment`)

Read-only archive of DELIVERED tasks (newest first)
Stat grid: delivered count, total revenue, sellers paid, warehouses
Expandable order tracking timeline with dot connector

Getting Started

Prerequisites

Node.js ≥ 18
MediStore Backend running on http://localhost:4000

Installation

# Clone the repository
git clone <repo-url>
cd mediStore_frontend

# Install dependencies
npm install

# Start development server
npm run dev

The app runs on http://localhost:3000

Development Scripts

npm run dev      # Start Next.js dev server with hot reload
npm run build    # Production build (TypeScript checked)
npm run start    # Serve production build
npm run lint     # ESLint check

Environment Variables

Create a .env.local file in the project root:

# Backend API base URL
NEXT_PUBLIC_API_URL=http://localhost:4000

# Better Auth
BETTER_AUTH_SECRET="same-secret-as-backend"
BETTER_AUTH_URL="http://localhost:3000"

# Next.js
NEXTAUTH_URL=http://localhost:3000

Note: All API calls use relative /api/* paths — Next.js rewrites proxy to the backend. No NEXT_PUBLIC_API_URL needed for browser-side calls.

Project Structure

mediStore_frontend/
├── src/
│   ├── app/
│   │   ├── (public)/                  # Public storefront pages
│   │   │   ├── page.tsx               # Homepage (banners, flash sales, medicines)
│   │   │   ├── medicines/             # Browse all medicines
│   │   │   ├── blogs/                 # Health articles
│   │   │   ├── about/                 # About page
│   │   │   └── auth/                  # Login / Register
│   │   │
│   │   ├── dashboard/
│   │   │   ├── page.tsx               # Dashboard landing / role redirect
│   │   │   ├── layout.tsx             # Sidebar + header shell
│   │   │   │
│   │   │   ├── (commonRoute)/         # Shared across roles
│   │   │   │   └── notifications/
│   │   │   │
│   │   │   └── (roleBasedRoute)/
│   │   │       ├── customer/          # 14 customer pages
│   │   │       │   ├── tracking/      # ← Real-time order journey
│   │   │       │   ├── cart/
│   │   │       │   ├── checkout/
│   │   │       │   └── ...
│   │   │       │
│   │   │       ├── seller/            # 17 seller pages
│   │   │       │   ├── addMedicine/
│   │   │       │   ├── flash-sale/
│   │   │       │   └── ...
│   │   │       │
│   │   │       ├── admin/             # 23 admin pages
│   │   │       │   ├── license/       # ← PDF viewer with Cloudinary proxy
│   │   │       │   ├── warehouses/
│   │   │       │   └── ...
│   │   │       │
│   │   │       └── warehouse/         # 13 warehouse pages
│   │   │           ├── routing/       # ← Shipment leg management
│   │   │           ├── packing/       # ← Pick & pack workflow
│   │   │           ├── dispatch/      # ← Dispatch & deliver
│   │   │           ├── fulfillment/   # ← Delivery history
│   │   │           └── ...
│   │   │
│   │   ├── api/                       # Next.js API route handlers
│   │   ├── globals.css                # Design system tokens + medi-page/medi-card
│   │   ├── layout.tsx                 # Root layout (Sonner, fonts)
│   │   └── not-found.tsx              # Custom 404
│   │
│   └── components/                    # Shared UI components
│       ├── Sidebar/
│       ├── Header/
│       └── ...
│
├── public/                            # Static assets
└── package.json

API Integration

All data fetching uses the browser's native fetch API with credentials: include to pass session cookies:

// Standard pattern used across all warehouse/customer pages
const res = await fetch("/api/fulfillment/my-queue", {
  credentials: "include",
});
const data = await res.json();

Route → API Mapping

Frontend Page	API Endpoint
Customer tracking	`GET /api/orders/my`
Warehouse routing	`GET /api/shipment-legs/mine`
Warehouse packing	`GET /api/fulfillment/my-queue`
Warehouse dispatch	`GET /api/fulfillment/my-queue`
Fulfillment history	`GET /api/fulfillment/my-queue`
Confirm receipt (seller)	`PATCH /api/shipment-legs/:id/receive-at-origin`
Dispatch inter-WH	`PATCH /api/shipment-legs/:id/dispatch`
Confirm dest arrival	`PATCH /api/shipment-legs/:id/receive-at-dest`
Mark item received	`PATCH /api/fulfillment/:id/receive-item`
Create packing slip	`PATCH /api/fulfillment/:id/pack`
Dispatch to customer	`PATCH /api/fulfillment/:id/dispatch`
Mark delivered	`PATCH /api/fulfillment/:id/deliver`

Key Design Decisions

Why Vanilla CSS over Tailwind?

The project uses a custom CSS design system (medi-page, medi-card) via globals.css to maintain full control over the pharmacy-themed aesthetics including warm cream backgrounds, navy headings, and amber CTAs — without the overhead of purging or configuration.

Why Framer Motion?

All card expansions, page transitions, and status animations use Framer Motion for smooth height: 0 → auto animations that maintain layout stability without JavaScript hacks.

Session-based Auth

Better Auth sessions are stored in HTTP-only cookies. All API calls use credentials: include to send these cookies. No JWT tokens are stored in localStorage.

Same-Warehouse Detection

The frontend detects originWarehouseId === destWarehouseId per shipment leg and renders a simplified "one-click receive" UI, bypassing the multi-step routing flow entirely.

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
public		public
src		src
.gitignore		.gitignore
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

💊 MediStore Frontend

📋 Table of Contents

Overview

Tech Stack

Design System

Color Palette

Core CSS Classes

Component Patterns

Application Architecture

User Roles & Dashboard Routes

🛒 Customer (/dashboard/customer/)

🏪 Seller (/dashboard/seller/)

🔧 Admin (/dashboard/admin/)

🏭 Warehouse (/dashboard/warehouse/)

System Workflow

1. Customer Order Journey

2. Warehouse Operations Workflow

3. Same-Warehouse Fast Path (Visual)

Page Reference

Customer Tracking Page (/customer/tracking)

Warehouse Routing Page (/warehouse/routing)

Warehouse Packing Page (/warehouse/packing)

Warehouse Dispatch Page (/warehouse/dispatch)

Warehouse Fulfillment History (/warehouse/fulfillment)

Getting Started

Prerequisites

Installation

Development Scripts

Environment Variables

Project Structure

API Integration

Route → API Mapping

Key Design Decisions

Why Vanilla CSS over Tailwind?

Why Framer Motion?

Session-based Auth

Same-Warehouse Detection

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

🛒 Customer (`/dashboard/customer/`)

🏪 Seller (`/dashboard/seller/`)

🔧 Admin (`/dashboard/admin/`)

🏭 Warehouse (`/dashboard/warehouse/`)

Customer Tracking Page (`/customer/tracking`)

Warehouse Routing Page (`/warehouse/routing`)

Warehouse Packing Page (`/warehouse/packing`)

Warehouse Dispatch Page (`/warehouse/dispatch`)

Warehouse Fulfillment History (`/warehouse/fulfillment`)

Packages