Overview

TrashTrace is a full-stack web application that lets anyone create a traceable waste shipment, generate a QR code to attach to the physical package, and verify whether that package reached its intended destination (e.g. a recycling centre) based on GPS scan data. It is built for transparency — the system explicitly states that tracking is QR-scan-based, not physical movement tracking.

Architecture

The project is structured into a frontend and backend:

• Frontend: Built with React and Vite, it serves as a Single Page Application (SPA). Key components include pages for creating shipments, tracking shipments, scanning QR codes, and an owner dashboard. It also utilizes utility functions for geolocation and owner token management.
• Backend: Developed using Node.js and Express, it functions as an API that can also be deployed as a Vercel serverless function. It connects to MongoDB using Mongoose for data persistence, defining models for Trash, Scan, and Notification. Routes handle trash shipments and notifications, with utility functions for geocoding addresses (using OpenStreetMap Nominatim) and calculating distances (Haversine formula). Tests are managed with Jest.

Features

• Create Shipment: Register a waste package with type, destination, and GPS source location.
• QR Code Generation: Generate a scannable QR code per package for download or printing.
• Scan & Track: Couriers scan the package, and GPS coordinates are logged.
• Delivery Verification: Packages are marked DELIVERED if scanned within a configurable radius of the destination.
• Owner Dashboard: A device-based dashboard displays all packages and notifications for the owner.
• Notifications: An in-app notification log tracks package scans and deliveries.
• Geocoding: Destination addresses are geocoded via OpenStreetMap Nominatim.

Local Setup

Prerequisites:

• Node.js ≥ 18
• MongoDB Atlas account or a local MongoDB instance

Steps:

1. Clone the repository and install dependencies using npm.
2. Copy the .env.example file to .env and configure your MongoDB connection string.
3. Run the application locally using npm run dev.

Vercel Deployment

The project can be deployed to Vercel. The setup involves pushing the code to GitHub, importing the project into Vercel, configuring environment variables (including the MongoDB URI and Vercel deployment URL), and Vercel handles the build and deployment process, serving the React SPA and the Node.js serverless function.

API Endpoints

The backend exposes several API endpoints for managing shipments, scans, and notifications, including:

• GET /api/health: Health check.
• POST /api/trash: Create a new trash shipment.
• GET /api/trash/:trackingId: Get tracking info.
• POST /api/trash/:trackingId/scan: Record a courier scan with latitude and longitude.
• GET /api/notifications/:token: Get notifications for an owner.

How QR Tracking Works

A unique tracking ID is generated for each shipment, and a QR code is created encoding the tracking URL. When a courier scans the QR code, their GPS coordinates are sent to the backend. The system then calculates the distance to the destination and updates the package status to DELIVERED or IN_TRANSIT. Notifications are generated if an owner token is provided.

Important Limitation: This system tracks QR code scans, not physical package location. A scan near the destination suggests arrival but does not guarantee it.