🔍 Smart Recovery Network

A high-performance, AI-powered Lost & Found platform built for college campuses.
Matches items using perceptual image hashing + TF-IDF text similarity, issues encrypted JWT QR claim tickets, and delivers real-time notifications via Socket.io.

Live Repo: github.com/shyam-dot/SmartRecoveryNetwork

---

🏗️ Project Structure

SmartRecoveryNetwork/
├── backend/
│   ├── config/          → MongoDB connection
│   ├── middleware/       → JWT auth, Admin guard, Multer upload
│   ├── models/           → User, FoundItem, LostItem, Claim, AnonymousTip
│   ├── routes/           → auth, admin, user, qr routes
│   ├── utils/            → AI Matcher, QR Generator, Mailer, Socket Handler
│   └── server.js         → Express entry point
├── frontend/
│   ├── src/
│   │   ├── components/   → Navbar
│   │   ├── pages/        → Landing, Login, Register, AnonymousTip
│   │   │   ├── admin/    → AdminDashboard, AddFoundItem, ScanQR, ManageItems
│   │   │   └── user/     → UserDashboard
│   │   ├── services/     → api, authService, adminService, userService
│   │   ├── utils/        → socketClient
│   │   └── App.js        → Routing
├── .env.example          → Environment variable template
├── .gitignore
├── README.md
├── CONTRIBUTING.md
└── LICENSE

---

✨ Features

🤖 AI Matching Engine

• Text: TF-IDF Cosine Similarity via the natural library
• Image: Perceptual Hash (pHash) + Hamming Distance via sharp
• Searches all unclaimed found items (cross-category) with a scored ranking
• Returns top 3 near-matches even below confirmation threshold

🛡️ Security

• JWT stored in httpOnly cookies (XSS-proof)
• helmet for HTTP hardening, express-mongo-sanitize against NoSQL injection
• express-rate-limit for DDoS/brute-force protection
• QR codes signed with a separate QR_JWT_SECRET from auth tokens

📡 Real-Time

• Socket.io pushes instant match alerts to student dashboards
• QR code delivered via WebSocket the moment a match is confirmed

🖨️ Offline Claim Tickets

• High-resolution PNG tickets generated in-browser via Canvas API
• Contains owner name, item name, AI score, and the encrypted QR

⚙️ Admin Tools

• Log found items with photo → auto-triggers AI matching
• Manage DB — view all found and lost items, filter by status
• Manual Match — admin selects lost + found item manually
• Scan QR — live camera or file upload to verify and release items
• Backward-compatible QR verification (old & new token formats)

🕐 Automation

• node-cron daily job emails admin when items are unclaimed for 30+ days
• Images auto-compressed to 800px JPEG via sharp before MongoDB storage

---

🚀 Getting Started

Prerequisites

• Node.js ≥ 18
• MongoDB Atlas account
• Gmail account with App Password for email

Installation

# 1. Clone the repository
git clone git@github.com:shyam-dot/SmartRecoveryNetwork.git
cd SmartRecoveryNetwork

# 2. Install backend dependencies
cd backend
npm install

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your actual values

# 4. Install frontend dependencies
cd ../frontend
npm install

# 5. Start both servers
# Terminal 1 – Backend
cd backend && npm run dev

# Terminal 2 – Frontend  
cd frontend && npm start

App runs at http://localhost:3000 | API at http://localhost:5000

---

🔐 Environment Variables

Copy backend/.env.example to backend/.env and fill in:

Variable	Description
PORT	Backend port (default: 5000)
MONGO_URI	MongoDB Atlas connection string
JWT_SECRET	Secret for auth tokens
QR_JWT_SECRET	Separate secret for QR claim tokens
QR_EXPIRY	QR token TTL (e.g. 48h)
EMAIL_USER	Gmail address for notifications
EMAIL_PASS	Gmail App Password
ADMIN_EMAIL	Email to receive aging item alerts
CLIENT_URL	Frontend URL (e.g. http://localhost:3000)

---

👥 User Roles

Role	Access
Student	Register, report lost item, get AI match, download QR ticket
Admin	Log found items, scan QR to release, manage DB, manual match

---

📄 License

MIT © 2026 Shyam — SmartRecoveryNetwork