IoT-Powered Cold Chain Logistics for Perishable Goods

PeriSense is a full-stack platform for monitoring the freshness of perishable goods during transit. It combines real-time IoT sensor readings with an XGBoost machine-learning model to predict fruit ripeness stages, alerting vendors and drivers when conditions change.

---

Architecture

┌─────────────┐       ┌──────────────┐       ┌────────────────┐
│  Main App   │       │   Vehicle    │       │ Vendor Portal  │
│   (React)   │       │  Dashboard   │       │    (React)     │
│  :3000      │       │   (React)    │       │   :3001        │
│             │       │  :3002       │       │                │
└──────┬──────┘       └──────┬───────┘       └───────┬────────┘
       │                     │                       │
       │   REST / JSON       │    REST / JSON        │  REST / JSON
       ▼                     ▼                       ▼
┌──────────────┐      ┌──────────────┐       ┌──────────────┐
│ Main Backend │      │   Sensors    │       │    Vendor    │
│   (Node.js)  │      │   Service    │       │   Service    │
│  :5000       │      │  (FastAPI)   │       │  (FastAPI)   │
│              │      │  :4000       │       │  :5000       │
└──────┬───────┘      └──────┬───────┘       └──────┬───────┘
       │                     │                       │
       │                     │                       │
       ▼                     ▼                       ▼
┌─────────────────────────────────────────────────────────────┐
│                     MongoDB (Atlas / local)                  │
│  local_db.sensor_logs  ←sync→  sensors_db.sensor_logs       │
│                         sensors_db.vendor_messages           │
└─────────────────────────────────────────────────────────────┘

Service	Stack	Port	Purpose
Main Frontend	React (CRA)	3000	Multi-role dashboard – auth, maps, work management
Vendor Frontend	React (CRA)	3001	Sensor log viewer + messaging panel
Vehicle Dashboard	React (CRA)	3002	Real-time zone status cards for drivers
Sensors Service	FastAPI + XGBoost	4000	ML-powered ripeness prediction, edge-to-cloud sync
Vendor Service	FastAPI	5000	Vendor-facing API for logs and messaging

---

Tech Stack

Backend: Python 3.10+, FastAPI, XGBoost, Motor (async MongoDB), Pydantic v2

Frontend: React 18, React Router v6, Axios, Leaflet, React-Leaflet

Database: MongoDB (local edge + Atlas cloud)

ML Model: XGBoost classifier trained on 7 sensor features (temp, humidity, three gas sensors) predicting 5 ripeness stages

External APIs: OpenCage Geocoding, OpenRouteService Routing

---

Quick Start

Prerequisites

• Node.js ≥ 18 & npm
• Python ≥ 3.10
• MongoDB (local or Atlas)
• API keys for OpenCage and OpenRouteService

1. Clone & configure

git clone https://github.com/<you>/perishable-goods-mgmt.git
cd perishable-goods-mgmt
cp .env.example .env          # ← fill in your secrets

2. Start MongoDB (optional — use Docker)

docker compose up -d          # starts a local MongoDB on :27017

3. Sensors service

cd sensors
pip install -r requirements.txt
python server.py              # → http://localhost:4000

4. Vendor service

cd vendor
pip install -r requirements.txt
python server.py              # → http://localhost:5000

5. React frontends

# Main frontend
cd frontend && npm install && npm start    # → :3000

# Vendor frontend
cd vendor/frontend && npm install && npm start   # → :3001

# Vehicle dashboard
cd vehicle && npm install && npm start     # → :3002

---

Environment Variables

See .env.example for a full list. Key variables:

Variable	Service	Description
MONGODB_LOCAL_URI	sensors	Local MongoDB for edge logging
MONGODB_CLOUD_URI	sensors, vendor	Atlas connection string
REACT_APP_API_URL	frontend	Main backend URL
REACT_APP_OPENCAGE_API_KEY	frontend	Geocoding key
REACT_APP_ORS_API_KEY	frontend	Routing key(s), comma-separated

---

Project Structure

perishable-goods-mgmt/
├── frontend/             # Main React app (auth, maps, dashboards)
│   └── src/
│       ├── config.js     # Centralized API & key config
│       └── screens/      # Route-level page components
├── vehicle/              # Vehicle dashboard React app
│   └── src/
│       ├── config.js
│       ├── pages/
│       ├── components/
│       └── services/
├── vendor/
│   ├── server.py         # Vendor FastAPI service
│   ├── frontend/         # Vendor React app
│   │   └── src/
│   │       ├── config.js
│   │       └── pages/
│   └── requirements.txt
├── sensors/
│   ├── server.py         # Sensors FastAPI service + ML model
│   ├── xgb_ripeness_stage5.pkl
│   ├── test.py
│   ├── dbtest.py
│   └── requirements.txt
├── .env.example
├── docker-compose.yml
└── README.md

---

ML Model

The ripeness prediction model (xgb_ripeness_stage5.pkl) is a multi-class XGBoost classifier trained on labeled sensor data:

Feature	Description
Temp-int	Internal compartment temperature (°C)
Humid-int	Internal humidity (%)
Temp-ext	Ambient temperature (°C)
Humid-ext	Ambient humidity (%)
TGS20	TGS2620 gas sensor reading
TGS02	TGS2602 gas sensor reading
SGP	SGP30 VOC sensor reading

Output: Ripeness stage 1–5 (Unripe → Spoiled) with confidence probability.

---

License

MIT