Enterprise-Grade Transportation Backend Solution

Built with passion, designed for scale

Velocia is a production-ready, scalable backend API for modern ride-sharing platforms. Built with cutting-edge technologies and best practices, it provides a robust foundation for transportation applications with real-time capabilities, secure authentication, and comprehensive administrative controls.

✨ Features

🔐 Authentication & Security JWT-based Authentication with refresh token Role-based Access Control with permissions Password Security using bcrypt encryption Two-Factor Authentication via OTP verification Session Management with Redis caching 🚗 Ride Management Complete Lifecycle Management from request to completion Real-time Status Tracking with live updates Geolocation Services for pickup/dropoff Smart Driver Matching algorithm Dynamic Pricing calculation system

👨‍💼 Administrative Control User & Driver Management dashboard Verification Workflows for driver applications Analytics & Reporting with detailed insights Account Management including suspension Regulatory Compliance Monitoring Dispute Resolution system 💰 Financial Operations Earnings Tracking for drivers Payment Integration ready architecture Transaction History with detailed records Financial Reporting and analytics Commission Management system

🏗️ System Architecture

graph TB
    subgraph "Client Layer"
        A[Mobile Application]
        B[Web Application]
        C[Admin Dashboard]
    end

    subgraph "API Gateway"
        D[Load Balancer]
        F[API Router]
    end

    subgraph "Service Layer"
        G[Auth Service]
        H[User Service]
        I[Ride Service]
        J[Driver Service]
        K[Payment Service]
    end

    subgraph "Data Layer"
        L[(MongoDB)]
        M[(Redis Cache)]
        N[Message Queue]
    end

    A & B & C --> D
    D --> F
    F --> G & H & I & J & K
    G & H & I & J & K --> L
    G & H & I & J & K --> M
    I & J --> N

Loading

Design Principle	Description
🎯 Microservice-Ready	Modular architecture that can be easily decomposed into microservices
📈 Horizontal Scalability	Built to scale out with increased load
🔒 Security-First	Security considerations at every architectural layer
🔄 Event-Driven	Asynchronous communication patterns for better performance
📊 Observable	Comprehensive logging, monitoring, and tracing capabilities

🛠️ Tech Stack

Core Technologies

TypeScript

Node.js

Express

MongoDB

Redis

Vercel

Additional Stack

Category	Technologies	Purpose
🔒 Security	JWT Passport.js Bcrypt	Authentication & protection
✅ Validation	Zod Mongoose	Validation & object modeling
📧 Communication	Nodemailer Socket.io	Email & real-time
🧪 Testing	Postman	Endpoint tests
🚀 Deployment	Vercel	Cloud deployment

🚀 Getting Started

⚡ Quick Installation

# 1. Clone the repository
git clone https://github.com/zahid-official/milestone-17-velociaServer.git
cd milestone-17-velociaServer

# 2. Install dependencies
npm install

# 3. Set up environment variables (Windows)
copy .env.example .env
# Edit .env with your configuration

# 4. Start development server
npm run dev

# 5. Access the API
# http://localhost:5000/api/v1

📦 Using MongoDB Atlas (Recommended)

For easier setup without local MongoDB installation:

1. Create free account at MongoDB Atlas

2. Create a cluster and get connection string

3. Update .env with your connection string:

   MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/velociaDB

🔧 Environment Configuration

Click to view essential .env variables

# Server Configuration
NODE_ENV=development | production
PORT=5000

# Database Configuration
DB_URL=mongodb+srv://username:password@cluster.mongodb.net/velociaDB?retryWrites=true&w=majority&appName=Cluster1
# OR Local MongoDB
# DB_URL=mongodb://localhost:27017/velociaDB

# JWT Configuration
JWT_ACCESS_SECRET=your-jwt-access-secret-change-this
JWT_ACCESS_EXPIRESIN=24h
JWT_REFRESH_SECRET=your-jwt-refresh-secret-change-this
JWT_REFRESH_EXPIRESIN=90d

# Express Session Configuration
EXPRESS_SESSION_SECRET=your-express-session-secret-change-this

# Bcrypt Configuration
BCRYPT_SALT_ROUNDS=10

# Frontend Configuration
FRONTEND_URL=http://localhost:5173

# Default Admin Credentials
DEFAULT_ADMIN_EMAIL=primary@email.com
DEFAULT_ADMIN_PASSWORD=primary@Admin01

# Redis Configuration
RADIS_HOST=your-redis-host
RADIS_PORT=your-redis-port
RADIS_USERNAME=default
RADIS_PASSWORD=your-redis-password

# SMTP Configuration
SMTP_PORT=465
SMTP_HOST=smtp.gmail.com
SMTP_FROM=your-email@gmail.com
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password

---

📚 API Documentation

🔗 Base URLs

Development: http://localhost:5000/api/v1
Production: https://velocia-api.vercel.app/api/v1

📋 API Endpoints

🔐 Click to view Authentication Routes

HTTP Method	Endpoint	Description	Authentication Required
GET	/auth/regenerate-token	Generate new access token using refresh token	No
POST	/auth/login	Authenticate user with credentials	No
POST	/auth/logout	Invalidate current user session	No
POST	/auth/sendOTP	Send OTP for verification purposes	No
POST	/auth/verifyOTP	Verify OTP code for authentication	No
PATCH	/auth/forgot-password	Initiate password reset process	No
PATCH	/auth/reset-password	Complete password reset with verification	Yes (Any Role)
PATCH	/auth/change-password	Update user password	Yes (Any Role)

👤 Click to view User Management Routes

HTTP Method	Endpoint	Description	Authentication Required
GET	/user/	Retrieve all registered users	Yes (Admin Only)
GET	/user/singleUser/:id	Retrieve specific user by ID	Yes (Admin Only)
GET	/user/profile	Retrieve current user profile information	Yes (Any Role)
POST	/user/register	Create new user account	No
PATCH	/user/update/:id	Update user account information	Yes (Owner/Admin)
PATCH	/user/block/:id	Block user account	Yes (Admin Only)
PATCH	/user/unblock/:id	Unblock user account	Yes (Admin Only)

🚕 Click to view Driver Management Routes

HTTP Method	Endpoint	Description	Authentication Required
GET	/driver/	Retrieve all driver applications	Yes (Admin Only)
GET	/driver/singleDriver/:driverId	Retrieve specific driver information	Yes (Admin Only)
GET	/driver/earnings	View driver earnings history	Yes (Driver Only)
POST	/driver/apply	Submit driver application	Yes (Any Role)
PATCH	/driver/updateDetails/:driverId	Update driver account details	Yes (Owner/Admin)
PATCH	/driver/approve/:driverId	Approve driver application	Yes (Admin Only)
PATCH	/driver/reject/:driverId	Reject driver application	Yes (Admin Only)
PATCH	/driver/suspend/:driverId	Suspend driver account	Yes (Admin Only)
PATCH	/driver/unsuspend/:driverId	Reactivate suspended driver account	Yes (Admin Only)
PATCH	/driver/availability/:driverId	Update driver availability status	Yes (Driver Only)

🏍️ Click to view Ride Management Routes

HTTP Method	Endpoint	Description	Authentication Required
GET	/ride/	Retrieve all platform rides	Yes (Admin Only)
GET	/ride/singleRide/:rideId	Retrieve specific ride details	Yes (Admin Only)
GET	/ride/requestedRides	View available ride requests	Yes (Driver/Admin)
GET	/ride/history	Retrieve rider's complete ride history	Yes (Rider Only)
POST	/ride/request	Request a new ride	Yes (Rider Only)
PATCH	/ride/cancel/:rideId	Cancel pending ride request	Yes (Rider Only)
PATCH	/ride/accept/:rideId	Accept ride request	Yes (Driver Only)
PATCH	/ride/reject/:rideId	Reject ride request	Yes (Driver Only)
PATCH	/ride/pickUp/:rideId	Confirm rider pickup	Yes (Driver Only)
PATCH	/ride/inTransit/:rideId	Update ride status to in transit	Yes (Driver Only)
PATCH	/ride/complete/:rideId	Mark ride as completed	Yes (Driver Only)

API Response Format

All API responses follow this consistent structure:

Success Response

{
  "success": true,
  "statusCode": 200,
  "message": "Operation completed successfully",
  "data": {
     "Response payload"
  },
  "meta": {
    "page": 2,
    "limit": 10,
    "totalPage": 25,
    "totalDoc": 245
  }
}

Error Response

{
  "success": false,
  "statusCode": 400,
  "message": "Validation error",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

👥 User Roles & Permissions

Role Hierarchy

graph TD
    A[Administrator] --> B[Full System Access]
    C[Driver] --> D[Ride Operations]
    E[Rider] --> F[Ride Booking]

    B --> G[User Management]
    B --> H[Driver Management]
    B --> I[Platform Analytics]

    D --> J[Accept/Reject Rides]
    D --> K[Manage Availability]
    D --> L[View Earnings]

    F --> M[Request Rides]
    F --> N[View History]
    F --> O[Rate Drivers]

Loading

Administrator Role

Administrators have comprehensive platform oversight with full system access. Key responsibilities include:

• User Management: Complete control over user accounts, including creation, modification, and deactivation
• Driver Operations: Review and process driver applications, manage driver status and permissions
• Platform Oversight: Access to all rides, transactions, and system analytics
• System Administration: Configuration management and platform maintenance capabilities
• Dispute Resolution: Handle customer service issues and ride disputes

Rider Role

Riders represent the customer base with access to core ride-booking functionality:

• Account Management: Personal profile creation, modification, and maintenance
• Ride Services: Request rides with specified pickup locations and destinations
• Ride Management: Cancel rides within allowed timeframes and track ride progress
• History Access: View complete ride history with detailed trip information
• Service Interaction: Rate drivers and provide feedback on completed rides

Driver Role

Drivers are service providers with specialized tools for ride fulfillment:

• Application Process: Submit applications for platform approval with required documentation
• Ride Operations: Accept or reject ride requests based on availability and preferences
• Service Delivery: Manage complete ride lifecycle from pickup to completion
• Financial Tracking: Access earnings history and payment information
• Availability Control: Set online/offline status and manage working hours

---

🔒Security

Authentication Framework

JWT Implementation

• Stateless authentication using JSON Web Tokens
• Dual-token system with access and refresh tokens
• Automatic token refresh for seamless user experience
• Secure token storage and transmission practices

Password Security

• bcrypt hashing with configurable salt rounds
• Password complexity requirements and validation
• Secure password reset process with OTP verification
• Protection against common password attacks

Authorization System

Role-Based Access Control

• Granular permission system based on user roles
• Resource-level access control for sensitive operations
• Dynamic permission validation for all protected endpoints
• Inheritance-based permission structure for scalability

Data Protection

Encryption Standards

• Data encryption at rest and in transit
• Secure communication protocols (HTTPS)
• Database connection encryption
• API endpoint security headers

Privacy Controls

• Personal data protection compliance
• User consent management
• Data retention policies
• Secure data deletion procedures

---

💻Development & Deployment

📂 Project Structure

project/
├── 📁 src/
│   ├── 📁 app/
│   │   ├── 📁 config/                    # Application configuration
│   │   │   ├── 📄 env.ts                 # Environment variable management
│   │   │   ├── 📄 env.interface.ts       # Environment type definitions
│   │   │   ├── 📄 passport.ts            # Authentication strategy configuration
│   │   │   └── 📄 redis.ts               # Redis connection setup
│   │   │
│   │   ├── 📁 errors/                    # Error handling
│   │   │   └── 📄 AppError.ts            # Custom application error class
│   │   │
│   │   ├── 📁 interfaces/                # Global type definitions
│   │   │   └── 📄 index.d.ts             # Shared interface declarations
│   │   │
│   │   ├── 📁 middlewares/               # Express middleware functions
│   │   │   ├── 📄 globalErrorHandler.ts  # Centralized error handling
│   │   │   ├── 📄 notFoundHandler.ts     # 404 error handling
│   │   │   ├── 📄 validateSchema.ts      # Request validation middleware
│   │   │   └── 📄 validateToken.ts       # Authentication middleware
│   │   │
│   │   ├── 📁 modules/                   # Feature-based modules
│   │   │   ├── 📁 auth/                  # Authentication services
│   │   │   │   ├── 📄 auth.controller.ts
│   │   │   │   ├── 📄 auth.routes.ts
│   │   │   │   ├── 📄 auth.service.ts
│   │   │   │   └── 📄 auth.validation.ts
│   │   │   │
│   │   │   ├── 📁 user/                  # User management
│   │   │   │   ├── 📄 user.controller.ts
│   │   │   │   ├── 📄 user.interface.ts
│   │   │   │   ├── 📄 user.model.ts
│   │   │   │   ├── 📄 user.routes.ts
│   │   │   │   ├── 📄 user.service.ts
│   │   │   │   └── 📄 user.validation.ts
│   │   │   │
│   │   │   ├── 📁 driver/                # Driver operations
│   │   │   │   ├── 📄 driver.controller.ts
│   │   │   │   ├── 📄 driver.interface.ts
│   │   │   │   ├── 📄 driver.model.ts
│   │   │   │   ├── 📄 driver.routes.ts
│   │   │   │   ├── 📄 driver.service.ts
│   │   │   │   └── 📄 driver.validation.ts
│   │   │   │
│   │   │   └── 📁 ride/                  # Ride management
│   │   │       ├── 📄 ride.controller.ts
│   │   │       ├── 📄 ride.interface.ts
│   │   │       ├── 📄 ride.model.ts
│   │   │       ├── 📄 ride.routes.ts
│   │   │       ├── 📄 ride.service.ts
│   │   │       └── 📄 ride.validation.ts
│   │   │
│   │   ├── 📁 routes/                    # Route aggregation
│   │   │   └── 📄 index.ts               # Main route configuration
│   │   │
│   │   └── 📁 utils/                     # Utility functions
│   │       ├── 📄 catchAsync.ts          # Async error handling
│   │       ├── 📄 constants.ts           # Application constants
│   │       ├── 📄 JWT.ts                 # JWT utility functions
│   │       ├── 📄 sendResponse.ts        # Standardized response formatting
│   │       └── 📁 templates/             # Email templates
│   │           ├── 📄 forgotPassword.ejs
│   │           └── 📄 sendOtp.ejs
│   │
│   ├── 📄 app.ts                         # Express application setup
│   └── 📄 server.ts                      # Server bootstrap and initialization
│
├── 📄 .env.example                       # Environment example
├── 📄 .gitignore                         # Git ignore rules
├── 📄 package.json                       # Dependencies
├── 📄 tsconfig.json                      # TypeScript config
├── 📄 eslint.config.mjs                  # Eslint config
└── 📄 README.md                          # This file

Deploy to Vercel

Manual Deployment

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Set environment variables
vercel env add MONGODB_URI
vercel env add JWT_ACCESS_SECRET

# Deploy to production
vercel --prod

Vercel Configuration

{
  "version": 2,
  "builds": [
    {
      "src": "dist/server.js",
      "use": "@vercel/node"
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "dist/server.js"
    }
  ]
}

🌟 Author

Zahid Official

Web Developer | Tech Enthusiast

Built with passion and dedication to create scalable solutions

---

🤝 Contributing

Contributions make the open source community amazing! Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Velocia - A modern transportation backend solution.