IoT Supply Chain Tracking System - Backend

Complete backend implementation for real-time IoT supply chain tracking with GPS and RFID verification.

🎯 Features

✅ Order Management - Create and track orders with RFID-tagged items
✅ Real-time GPS Tracking - Track trucks in real-time using GPS coordinates
✅ RFID Verification - Verify delivered items using RFID tags
✅ Discrepancy Detection - Automatically detect missing or extra items
✅ WebSocket Updates - Real-time updates for dashboards
✅ Authentication - JWT-based user authentication with roles
✅ ESP32 Simulator - Mock hardware for testing without physical devices

🚀 Quick Start

Prerequisites

Node.js v18 or higher
MongoDB (local installation or MongoDB Atlas account)

Installation

# 1. Clone the repository
git clone https://github.com/Sasmonk/backend_v1.git
cd backend_v1

# 2. Install dependencies
npm install

# 3. Create .env file from example
cp .env.example .env

# 4. Edit .env file with your configuration:
#    - MONGODB_URI: Your MongoDB connection string
#    - JWT_SECRET: A strong secret key for JWT tokens

# 5. Seed database with sample data
npm run seed

# 6. Start development server
npm run dev

# 7. (Optional) Start ESP32 simulator in another terminal
npm run simulator

Server will run at: http://localhost:5000

Quick Test

# Test health endpoint
curl http://localhost:5000/health

# Run comprehensive test suite
npm run test:full

🎯 Project Overview

This system tracks goods from factory to customer with:

Factory Dispatch: Create orders and track shipments
GPS Tracking: Real-time location updates from trucks
RFID Verification: Verify delivered items at customer location
Dispute Management: Handle missing items and discrepancies
Real-time Updates: WebSocket for live dashboard updates

Tech Stack

Runtime: Node.js v18+ (ES6 Modules)
Framework: Express.js
Database: MongoDB with Mongoose
Real-time: Socket.io
Authentication: JWT (jsonwebtoken)
Validation: Joi
Security: Helmet, CORS, Rate Limiting
Password Hashing: bcryptjs

⚙️ Setup Instructions

1. MongoDB Setup

Option A: Local MongoDB

# Install MongoDB locally
# Start MongoDB service
mongod

Option B: MongoDB Atlas (Recommended)

Go to MongoDB Atlas
Create a free cluster (M0)
Create database user
Whitelist IP address (use 0.0.0.0/0 for testing)
Get connection string
Update .env file with connection string

2. Environment Variables

Create .env file:

PORT=5000
MONGODB_URI=mongodb://localhost:27017/supply-chain
NODE_ENV=development
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
JWT_SECRET=your-strong-secret-key-change-in-production

For MongoDB Atlas:

MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/supply-chain

3. Database Seeding

npm run seed

Creates:

3 Factories (Mumbai, Delhi, Bangalore)
5 Customers (different cities)
10 Orders (various statuses)
35+ Tracking records
7 Verifications

📡 API Documentation

Authentication

Signup

POST /api/auth/signup
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "Password123",
  "role": "customer"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "Password123"
}

Get Profile (requires authentication)

GET /api/auth/me
Authorization: Bearer <token>

Order Management

POST /api/orders/create - Create new order
GET /api/orders - List orders (with filters)
GET /api/orders/:orderId - Get order details
PATCH /api/orders/:orderId/status - Update order status
DELETE /api/orders/:orderId - Cancel order

GPS Tracking

POST /api/tracking/update - Update GPS location
GET /api/tracking/:orderId/latest - Get latest location
GET /api/tracking/:orderId/history - Get tracking history
GET /api/tracking/:orderId/route - Get route (GeoJSON)
POST /api/tracking/:orderId/eta - Calculate ETA
GET /api/tracking/active - Get active shipments

RFID Verification

POST /api/verification/start - Start verification
POST /api/verification/scan - Scan RFID tag
POST /api/verification/complete - Complete verification
GET /api/verification/:orderId - Get verification status

Complete API Documentation: See API_ENDPOINTS.txt

User Guide: See USER_GUIDE.txt

🔌 WebSocket Events

Client → Server Events

join:order - Join order room
leave:order - Leave order room
join:factory - Join factory dashboard
join:customer - Join customer dashboard

Server → Client Events

order:created - New order created
order:status_updated - Order status changed
tracking:location_updated - GPS location updated
verification:started - Verification started
verification:item_scanned - RFID tag scanned
verification:completed - Verification completed
missing:report_sent - Missing items reported

Example Client Code

import io from 'socket.io-client';

const socket = io('http://localhost:5000');

// Join order room
socket.emit('join:order', 'ORD-20251107-001');

// Listen for location updates
socket.on('tracking:location_updated', (data) => {
  console.log('Location:', data.location);
});

🤖 ESP32 Simulator

Since you don't have physical ESP32 hardware, use the simulator:

npm run simulator

Features:

Sends GPS updates every 5 seconds
Simulates RFID scanning every 10 seconds (when truck stops)
Automatically finds active orders
Shows real-time progress in console

What it does:

Finds active orders for trucks
Simulates truck movement along route
Sends GPS coordinates to API
Simulates RFID scanning at destination

🧪 Testing

Automated Test Suite

# Run comprehensive test suite
npm run test:full

Tests include:

✅ Health check
✅ User authentication (signup/login)
✅ Order creation and management
✅ GPS tracking updates
✅ RFID verification flow
✅ Error handling
✅ Validation

Manual Testing

# Test health endpoint
curl http://localhost:5000/health

# Test with test.http file (REST Client extension)
# Or use the frontend playground
npm run client

Test Results

All tests passing (100% success rate) ✅

📦 Project Structure

backend_v1/
├── src/
│   ├── config/
│   │   ├── db.js              # MongoDB connection
│   │   └── socket.js          # Socket.io configuration
│   ├── models/
│   │   ├── Order.js           # Order model
│   │   ├── Tracking.js        # GPS tracking model
│   │   ├── Verification.js    # RFID verification model
│   │   ├── Factory.js         # Factory model
│   │   ├── Customer.js        # Customer model
│   │   └── User.js            # User model (authentication)
│   ├── routes/
│   │   ├── orderRoutes.js     # Order API routes
│   │   ├── trackingRoutes.js  # Tracking API routes
│   │   ├── verificationRoutes.js # Verification API routes
│   │   └── authRoutes.js      # Authentication routes
│   ├── controllers/
│   │   ├── orderController.js
│   │   ├── trackingController.js
│   │   ├── verificationController.js
│   │   └── authController.js
│   ├── middleware/
│   │   ├── errorHandler.js    # Global error handler
│   │   ├── validation.js      # Joi validation
│   │   ├── rateLimiter.js     # Rate limiting
│   │   └── auth.js            # JWT authentication
│   ├── utils/
│   │   ├── responseFormatter.js
│   │   ├── idGenerator.js
│   │   └── distanceCalculator.js
│   ├── scripts/
│   │   ├── seedDatabase.js    # Database seeding
│   │   ├── esp32Simulator.js  # ESP32 mock simulator
│   │   ├── testAPI.js         # Basic API tests
│   │   └── fullTestSuite.js   # Comprehensive test suite
│   └── server.js              # Main server file
├── frontend/
│   ├── index.html             # Simple playground UI
│   └── app.js                 # Frontend JavaScript
├── .env.example               # Environment variables template
├── .gitignore                 # Git ignore rules
├── package.json               # Dependencies and scripts
├── README.md                  # This file
├── API_ENDPOINTS.txt          # Complete API documentation
├── USER_GUIDE.txt             # User workflow guide
└── NEXT_STEPS.txt             # Development roadmap

🚀 Deployment

Environment Variables

Set these in your production environment:

PORT=5000
MONGODB_URI=mongodb+srv://...
NODE_ENV=production
ALLOWED_ORIGINS=https://your-frontend.com
JWT_SECRET=strong-production-secret

Deployment Platforms

Railway

railway login
railway init
railway up

Render

Connect GitHub repository
Set environment variables
Deploy

Heroku

heroku create
heroku config:set MONGODB_URI=...
heroku config:set JWT_SECRET=...
git push heroku main

Production Checklist

📝 Available Scripts

npm start          # Start production server
npm run dev        # Start development server (with auto-reload)
npm run seed       # Seed database with sample data
npm run simulator  # Start ESP32 simulator
npm test           # Run basic API tests
npm run test:full  # Run comprehensive test suite
npm run client     # Start frontend playground

🔐 Security

✅ Password hashing with bcryptjs
✅ JWT token authentication
✅ Rate limiting on all endpoints
✅ Input validation with Joi
✅ Helmet.js security headers
✅ CORS configuration
✅ MongoDB injection prevention

📚 Documentation

API_ENDPOINTS.txt - Complete API reference
USER_GUIDE.txt - User workflow guide
NEXT_STEPS.txt - Development roadmap

🤝 Contributing

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

📄 License

This project is licensed under the ISC License.

👤 Author

Sasmonk

GitHub: @Sasmonk

🙏 Acknowledgments

Express.js community
MongoDB documentation
Socket.io documentation
All open-source contributors

📞 Support

For issues and questions:

Open an issue on GitHub
Check documentation files
Review API_ENDPOINTS.txt for API details

Last Updated: November 2024
Version: 1.0.0

Name		Name	Last commit message	Last commit date
frontend		frontend
src		src
.env.example		.env.example
.gitignore		.gitignore
API_ENDPOINTS.txt		API_ENDPOINTS.txt
NEXT_STEPS.txt		NEXT_STEPS.txt
README.md		README.md
USER_GUIDE.txt		USER_GUIDE.txt
package-lock.json		package-lock.json
package.json		package.json
readme_backend.md		readme_backend.md
test.http		test.http

Latest commit

History

Folders and files

Repository files navigation