🚚 Centralized Delivery Network

A comprehensive delivery management platform connecting partners, agents, and administrators

Features • Installation • Documentation • API Reference • Deployment

📋 Table of Contents

Overview
Features
Tech Stack
Project Structure
Prerequisites
Quick Start
Installation
Configuration
Running the Application
API Documentation
Deployment
Development
Contributing
License

🎯 Overview

Centralized Delivery Network is a full-stack delivery management platform that enables seamless coordination between delivery partners, agents, and administrators. The platform provides real-time tracking, order management, analytics, and comprehensive administrative tools.

Key Capabilities

🔄 Real-time Order Management - Live order tracking and status updates
📍 Location Tracking - Real-time agent location monitoring
🔌 REST API Integration - Partner API for seamless integrations
📊 Analytics Dashboard - Comprehensive metrics and insights
🔐 Multi-role Authentication - Secure role-based access control
📱 Mobile-Optimized - Responsive design for all devices

✨ Features

👥 For Partners

✅ REST API for order creation and management
✅ Webhook support for real-time order updates
✅ Comprehensive dashboard with analytics
✅ API key management and rotation
✅ Order tracking and status monitoring
✅ Performance metrics and reporting

🚴 For Agents

✅ Real-time order notifications
✅ Accept/reject order offers
✅ Live location tracking
✅ Order status updates (Pickup, Delivery, etc.)
✅ Profile and document management
✅ KYC verification system
✅ Earnings and performance tracking
✅ Mobile-optimized interface with collapsible sidebar

👨‍💼 For Administrators

✅ Live map view of all agents and orders
✅ Agent approval and management
✅ Partner account management
✅ Order oversight and reassignment
✅ KYC document verification
✅ System-wide analytics dashboard
✅ Support ticket management
✅ Real-time system monitoring

🛠️ Tech Stack

Backend

Technology	Purpose
Node.js 18+	Runtime environment
Express.js	Web framework
TypeScript	Type-safe development
PostgreSQL	Primary database
Prisma	ORM and database toolkit
Redis	Caching and real-time data
Socket.io	WebSocket for real-time updates
JWT	Authentication
Multer	File upload handling
Firebase Admin	Push notifications

Frontend

Technology	Purpose
Next.js 16	React framework with App Router
TypeScript	Type-safe development
Tailwind CSS 4	Utility-first CSS framework
Axios	HTTP client
Socket.io Client	WebSocket client
Mapbox GL	Interactive maps
Recharts	Data visualization
NextAuth.js	Authentication
Zod	Schema validation

📁 Project Structure

NextJS/
├── backend/                    # Express.js API Server
│   ├── src/
│   │   ├── controllers/        # Request handlers
│   │   ├── routes/            # API route definitions
│   │   ├── services/          # Business logic layer
│   │   ├── middleware/        # Auth, validation, error handling
│   │   ├── lib/               # External library configs
│   │   │   ├── prisma.ts      # Prisma client
│   │   │   ├── redis.ts       # Redis client
│   │   │   ├── websocket.ts   # Socket.io server
│   │   │   └── webhook.ts     # Webhook utilities
│   │   └── utils/             # Utility functions
│   ├── prisma/
│   │   ├── schema.prisma      # Database schema
│   │   └── migrations/        # Database migrations
│   └── uploads/               # File uploads directory
│
├── next-app/                  # Next.js Frontend Application
│   ├── app/                   # Next.js App Router
│   │   ├── (admin)/          # Admin route group
│   │   ├── (agent)/          # Agent route group
│   │   ├── (partner)/        # Partner route group
│   │   └── (auth)/           # Authentication routes
│   ├── components/            # React components
│   │   ├── layout/           # Layout components
│   │   ├── maps/             # Map components
│   │   ├── orders/           # Order components
│   │   └── ui/               # Reusable UI components
│   ├── lib/                   # Utilities and helpers
│   │   ├── api/              # API client functions
│   │   └── utils/            # Helper functions
│   └── public/                # Static assets
│
└── docs/                      # Project documentation
    ├── API_DOCUMENTATION.md
    ├── DEPLOYMENT.md
    ├── PARTNER_INTEGRATION_GUIDE.md
    └── ...

📦 Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+ (Download)
npm or yarn package manager
PostgreSQL 12+ (Download)
Redis (Optional, for caching and real-time features)
Git (Download)

Additional Services

Mapbox Account - For map features (Sign up)
Firebase Project - For push notifications (Optional)

🚀 Quick Start

# Clone the repository
git clone <repository-url>
cd NextJS

# Backend setup
cd backend
npm install
cp .env.example .env
# Edit .env with your configuration
npm run prisma:generate
npm run prisma:migrate
npm run dev

# Frontend setup (in a new terminal)
cd ../next-app
npm install
cp .env.local.example .env.local
# Edit .env.local with your configuration
npm run dev

Visit http://localhost:3000 to see the application.

📥 Installation

Step 1: Clone Repository

git clone <repository-url>
cd NextJS

Step 2: Backend Setup

cd backend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Set up database
npm run prisma:generate
npm run prisma:migrate

# (Optional) Seed database
npm run prisma:seed

Step 3: Frontend Setup

cd ../next-app

# Install dependencies
npm install

# Set up environment variables
cp .env.local.example .env.local
# Edit .env.local with your configuration

⚙️ Configuration

Backend Environment Variables

Create backend/.env:

# Server Configuration
NODE_ENV=development
PORT=5000

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/delivery_network"

# Authentication
JWT_SECRET="your-super-secret-jwt-key-minimum-32-characters-long"

# CORS
CORS_ORIGIN="http://localhost:3000"

# Redis (Optional)
REDIS_ENABLED=true
REDIS_URL="redis://localhost:6379"

# Firebase (Optional)
FIREBASE_PROJECT_ID="your-project-id"
FIREBASE_PRIVATE_KEY="your-private-key"
FIREBASE_CLIENT_EMAIL="your-client-email"

Frontend Environment Variables

Create next-app/.env.local:

# API Configuration
NEXT_PUBLIC_API_URL="http://localhost:5000/api"

# Authentication
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-nextauth-secret-minimum-32-characters"

# Maps
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN="pk.your-mapbox-token"

Generate Secure Secrets

# Generate JWT_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Generate NEXTAUTH_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

🏃 Running the Application

Development Mode

Terminal 1 - Start Backend:

cd backend
npm run dev

Backend runs on http://localhost:5000

Terminal 2 - Start Frontend:

cd next-app
npm run dev

Frontend runs on http://localhost:3000

Production Mode

Build and Start Backend:

cd backend
npm run build
npm start

Build and Start Frontend:

cd next-app
npm run build
npm start

📚 API Documentation

Base URLs

Development: http://localhost:5000/api
Production: https://your-backend-url.onrender.com/api

Authentication Methods

JWT Authentication (Web App)

Authorization: Bearer <jwt_token>

API Key Authentication (Partner API)

X-API-Key: pk_<your_api_key>

Quick API Examples

Register User:

curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "securePassword123",
    "role": "AGENT"
  }'

Create Order (Partner API):

curl -X POST http://localhost:5000/api/partner-api/orders \
  -H "X-API-Key: pk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pickupLat": 28.7041,
    "pickupLng": 77.1025,
    "dropLat": 28.6139,
    "dropLng": 77.2090,
    "payoutAmount": 150.00,
    "priority": "HIGH"
  }'

Complete API Reference

📖 See docs/API_DOCUMENTATION.md for complete API documentation.

🚢 Deployment

Quick Deployment Guide

See docs/QUICK_DEPLOY.md for fast-track deployment.

Detailed Deployment

See docs/DEPLOYMENT.md for comprehensive deployment instructions.

Deployment Platforms

Backend: Render.com (recommended)
Frontend: Netlify (recommended)
Database: Render PostgreSQL or external PostgreSQL
Redis: Render Redis or external Redis

Deployment Checklists

💻 Development

Available Scripts

Backend Scripts

npm run dev              # Start development server with hot reload
npm run build            # Build for production
npm start                # Start production server
npm run prisma:generate  # Generate Prisma Client
npm run prisma:migrate   # Run database migrations
npm run prisma:studio    # Open Prisma Studio (database GUI)
npm run prisma:seed      # Seed database with sample data

Frontend Scripts

npm run dev              # Start development server
npm run build            # Build for production
npm start                # Start production server
npm run lint             # Run ESLint

Code Structure

Backend: MVC pattern with controllers, services, and routes
Frontend: Component-based architecture with Next.js App Router
Database: Prisma ORM with migrations
Real-time: Socket.io for WebSocket connections

Environment Setup

Copy .env.example to .env in backend
Copy .env.local.example to .env.local in next-app
Fill in all required environment variables
Run database migrations
Start development servers

🔒 Security

✅ JWT Authentication - Secure token-based authentication
✅ API Key Authentication - For partner integrations
✅ Password Hashing - bcryptjs with salt rounds
✅ CORS Protection - Configurable allowed origins
✅ Input Validation - Zod and Express Validator
✅ File Upload Validation - Type and size restrictions
✅ Environment Variables - Sensitive data in .env files
✅ SQL Injection Protection - Prisma ORM parameterized queries
✅ XSS Protection - React's built-in XSS protection

🗄️ Database

The application uses PostgreSQL with Prisma ORM.

Key Models

User - Authentication and user profiles
Agent - Delivery agent profiles and status
Partner - Partner accounts and API keys
Order - Delivery orders and tracking
Document - Agent KYC documents
SupportTicket - Support ticket management

Database Schema

See backend/prisma/schema.prisma for the complete schema definition.

Migrations

# Create a new migration
npm run prisma:migrate

# Apply migrations in production
npm run prisma:migrate:deploy

🌐 Real-time Features

WebSocket Support - Real-time order updates via Socket.io
Location Tracking - Real-time agent location updates
Order Notifications - Push notifications for order status changes
Live Map - Real-time map updates for admin dashboard

📱 Mobile Support

The frontend is fully responsive with:

✅ Collapsible Sidebar - Mobile-optimized navigation
✅ Touch-Friendly UI - Optimized for mobile interactions
✅ Responsive Design - Works seamlessly on all screen sizes
✅ Progressive Web App - Can be installed on mobile devices

📖 Documentation

All documentation is available in the docs/ directory:

Document	Description
API_DOCUMENTATION.md	Complete API reference
DEPLOYMENT.md	Deployment guide
QUICK_DEPLOY.md	Quick deployment reference
PARTNER_INTEGRATION_GUIDE.md	Partner API integration
backend-deployment-checklist.md	Backend deployment checklist
frontend-deployment-checklist.md	Frontend deployment checklist

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow TypeScript best practices
Write meaningful commit messages
Add tests for new features
Update documentation as needed
Follow the existing code style

📝 License

This project is licensed under the ISC License.

🆘 Support

Need help? Check out:

🎯 Roadmap

🙏 Acknowledgments

Next.js - React framework
Express.js - Web framework
Prisma - Database toolkit
Mapbox - Maps platform
Tailwind CSS - CSS framework

Built with ❤️ using Next.js, Express.js, and TypeScript

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 133 Commits
backend		backend
docs		docs
next-app		next-app
.gitignore		.gitignore
AGENT_FEATURES_IMPLEMENTATION.md		AGENT_FEATURES_IMPLEMENTATION.md
CAMERA_SCANNING_IMPLEMENTATION.md		CAMERA_SCANNING_IMPLEMENTATION.md
COMPLETE_IMPLEMENTATION_SUMMARY.md		COMPLETE_IMPLEMENTATION_SUMMARY.md
README.md		README.md
c --noEmit		c --noEmit
fix-submodule.ps1		fix-submodule.ps1
t --count HEAD		t --count HEAD

omix2003/CentralizedDeliveryNetwork

Folders and files

Latest commit

History

Repository files navigation