First Go Server

A full-featured parcel delivery management system backend built with Node.js, Express, and MongoDB. This platform enables users to send parcels, track deliveries, manage payments, and coordinate with delivery riders.

Overview

First Go is a complete backend solution for a parcel delivery service. It provides REST APIs for managing parcels, user authentication, payment processing with Stripe, rider management, and real-time tracking capabilities. The system is designed for scalability and supports multiple user roles including customers, riders, and administrators.

Features

Core Features

• User Management: User registration, profile management, and role-based access control (user, rider, admin)
• Parcel Management: Create, retrieve, update, and delete parcel deliveries with status tracking
• Rider System: Rider registration, approval workflow, and delivery assignment
• Payment Processing: Secure payment handling via Stripe integration with transaction verification
• Tracking System: Real-time parcel tracking with detailed status logs
• Search & Filter: Advanced filtering for parcels, users, and riders
• Authentication: Firebase authentication with JWT token verification

API Endpoints

User APIs

• GET /user/:email/role - Get user role
• POST /user - Register new user
• GET /users - List all users (admin only, searchable)
• PATCH /users/:id/role - Update user role

Parcel APIs

• GET /parcels - Get parcels (filterable by email, rider, delivery status)
• GET /parcels/:id - Get specific parcel details
• POST /parcels - Create new parcel with auto-generated tracking ID
• PATCH /parcels/:id/status - Update delivery status
• PATCH /parcels/:id - Assign parcel to rider (admin only)
• DELETE /parcels/:id - Delete parcel
• GET /parcels/delivery/status - Get delivery statistics

Payment APIs

• GET /payments - Get payment history
• POST /do-payment - Initiate Stripe payment
• PATCH /payment-success - Verify and process payment

Rider APIs

• POST /be-a-rider - Register as rider
• GET /riders - List riders with filtering (admin only)
• PATCH /riders/:id - Approve/reject rider application

Tracking APIs

• GET /trackings/:trackingId - Get full tracking history with timestamps

Tech Stack

• Runtime: Node.js
• Framework: Express.js
• Database: MongoDB with Mongoose
• Authentication: Firebase Admin SDK
• Payment: Stripe API
• Environment Management: dotenv

Prerequisites

• Node.js 14+ and npm
• MongoDB database (MongoDB Atlas or local)
• Firebase project with service account credentials
• Stripe account and API keys
• Environment variables configured

Installation

1. Clone the repository

git clone https://github.com/parvejtalukder/First_Go_Server.git
cd First_Go_Server

2. Install dependencies

npm install

3. Configure environment variables

Create a .env file in the root directory with the following variables:

# Server
PORT=3000

# MongoDB
DB_USER=your_mongodb_user
DB_PASS=your_mongodb_password

# Firebase
FBS_KEY=your_base64_encoded_firebase_key

# Stripe
PAYMENT=your_stripe_secret_key

# Frontend
DOMAIN=http://localhost:5173

Firebase Key Setup: Your Firebase service account JSON should be Base64 encoded and stored in FBS_KEY.

4. Start the server

npm start

The server will run on http://localhost:3000 (or your specified PORT)

Project Structure

├── package.json
├── .env
└── index.js (Main application file)
    ├── Authentication middleware (verifyToken, verifyAdmin)
    ├── User routes and handlers
    ├── Parcel routes and handlers
    ├── Payment routes and handlers
    ├── Rider routes and handlers
    └── Tracking routes and handlers

Database Schema

Collections

• users: User profiles with roles (user, rider, admin)
• parcels: Parcel information with delivery status
• payments: Payment records and transaction details
• riders: Rider profiles with work status
• trackings: Detailed tracking logs for each parcel

API Usage Examples

Create a Parcel

curl -X POST http://localhost:3000/parcels \
  -H "Content-Type: application/json" \
  -d '{
    "senderEmail": "user@example.com",
    "parcelName": "Package",
    "cost": 1500
  }'

Initiate Payment

curl -X POST http://localhost:3000/do-payment \
  -H "Content-Type: application/json" \
  -d '{
    "parcelId": "object_id",
    "parcelName": "Package",
    "cost": 1500,
    "senderEmail": "user@example.com"
  }'

Register as Rider

curl -X POST http://localhost:3000/be-a-rider \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "email": "rider@example.com",
    "displayName": "John Rider",
    "phone": "1234567890"
  }'

Security Features

• Token Verification: JWT token verification via Firebase Admin SDK
• Role-Based Access Control: Different permissions for users, riders, and admins
• Email Validation: Ensures users can only access their own data
• Payment Verification: Stripe webhook validation for payment processing
• CORS Configuration: Restricted origins for API access

CORS Configuration

The server allows requests from:

• http://localhost:5173 (local development)
• https://pht-first-go.web.app (production frontend)

Tracking System

Parcels are automatically assigned readable tracking IDs in the format: FGO-YYMMDD-XXXXXX

Tracking events include:

• created - Parcel created
• pending-pickup - Waiting for rider pickup
• rider-assigned - Rider assigned to delivery
• delivered - Parcel delivered

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a 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

Troubleshooting

MongoDB Connection Issues

• Verify credentials in .env
• Check MongoDB Atlas IP whitelist includes your IP
• Ensure database name matches in connection string

Firebase Authentication Errors

• Verify FBS_KEY is properly Base64 encoded
• Check Firebase project has Admin SDK enabled
• Ensure service account has correct permissions

Stripe Payment Issues

• Verify Stripe API key is correct
• Check payment amounts are in cents
• Ensure webhook endpoints are configured

License

This project is open source and available under the MIT License.

Author

Parvej Husen Talukder

Support

For issues, questions, or suggestions, please open an issue on the GitHub repository.